Metadata-Version: 2.4
Name: dagstack-logger
Version: 0.1.3
Summary: Python binding for dagstack/logger-spec — OTel-compatible structured logging, named loggers hierarchy, context propagation, sinks, scoped overrides
Project-URL: Homepage, https://git.goldix.org/dagstack/logger-python
Project-URL: Repository, https://git.goldix.org/dagstack/logger-python
Project-URL: Issues, https://git.goldix.org/dagstack/logger-python/issues
Project-URL: Specification, https://git.goldix.org/dagstack/logger-spec
Author-email: Evgenii Demchenko <demchenkoev@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: dagstack,logger,logging,observability,opentelemetry,otel,structured-logging
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Logging
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: opentelemetry-api<2.0,>=1.20
Provides-Extra: otlp
Requires-Dist: opentelemetry-exporter-otlp<2.0,>=1.20; extra == 'otlp'
Requires-Dist: opentelemetry-sdk<2.0,>=1.20; extra == 'otlp'
Description-Content-Type: text/markdown

# dagstack-logger

Python binding for [dagstack/logger-spec](https://github.com/dagstack/logger-spec) — OTel-compatible structured logging with a named-logger hierarchy, W3C trace context propagation, pluggable sinks, and scoped overrides.

Configured through [dagstack-config](https://github.com/dagstack/config-python).

**Status: Phase 1 MVP.** Console / File / In-memory sinks ship; OTLP, redaction processor chain, and the AI-agent extension pack land in Phase 2+.

## Roadmap

- **Phase 1 release (`0.1.x`)** — current. `LogRecord` / `Severity` / W3C hex encoding / dagstack JSON-lines wire format; `ConsoleSink` (JSON/pretty TTY-aware), `FileSink` (rotation), `InMemorySink` (ring buffer); `Logger` hierarchy with context propagation, redaction by suffix, and scoped overrides. `Logger.configure(config_section)` integrates with `dagstack-config`. No OTLP sink, no LogProcessor chain, no AI-agent extension pack (§5.5 of logger-spec) yet.
- **Phase 2+** — `OTLPSink`, `LokiSink`, `SentrySink`, the LogProcessor chain (redaction / sampling), AI-agent conventions.

## Spec

The spec lives as a submodule in `spec/` → [dagstack/logger-spec](https://github.com/dagstack/logger-spec). The core decisions are in `spec/adr/0001-logger-contract.md`.

## Local development

```bash
git clone --recurse-submodules https://github.com/dagstack/logger-python.git
cd logger-python
uv sync --group dev

make test           # pytest
make lint           # ruff check + format --check
make typecheck      # mypy --strict
```

## Dependencies

- `dagstack-config>=0.4.1` — for configuration.
- `opentelemetry-api>=1.20,<2.0` — for trace / span / baggage context propagation (mandatory per spec §3.4).
- `opentelemetry-sdk` + exporter (optional via `[otlp]` extras) — for `OTLPSink` in Phase 2+.

## Licensing

Apache-2.0.

## Related

- [`dagstack/logger-spec`](https://github.com/dagstack/logger-spec) — language-agnostic spec.
- [`dagstack/config-python`](https://github.com/dagstack/config-python) — config binding; the logger reads its `logging:` section through this binding.
- [`dagstack/plugin-system-python`](https://github.com/dagstack/plugin-system-python) — plugin system; the logger's `instrumentation_scope` can be derived from a plugin manifest.
