Skip to main content

What the specification is

dagstack/logger-spec is the normative source of truth for structured logging in the dagstack ecosystem. It pins down what must hold in any implementation (dagstack/logger-python, dagstack/logger-typescript, dagstack/logger-go) and why that choice was made.

How the "Specification" section differs from the guides​

SectionAudienceWhat it gives you
ConceptsApplication developerExplains how the logger works today, in terms of a specific language.
GuidesApplication developerWalks through a task step by step.
Specification (this section)Implementation author / reviewerExplains why a decision was made; pins down normative guarantees.

ADRs​

As of v1.0, one ADR is in place:

  1. ADR-0001: Logger contract — wire format, severity, the Logger API, sinks, semantic conventions, scoped overrides, configuration via config-spec, redaction, sampling, async / shutdown, conformance.

Additional ADRs are queued for the post-pilot v1.1 backlog, including a structural split of the AI-agent extension pack into a dedicated ADR-0002, OTel GenAI version pinning policy, exception stacktrace formatting, and a deprecation path for the plugin-system Progress sink.

The normative source​

The pages in this section are a descriptive prose summary of the ADR. The formal normative text lives in dagstack/logger-spec. If you are working on changes inside an implementation, read the normative version: it covers every edge case, the serialisation rules, and the requirements on conformance fixtures.

How the specification changes​

  1. Open an issue in dagstack/logger-spec.
  2. Submit a PR with a new ADR or a revision of an existing one.
  3. Architect review plus sign-off from the maintainers of every implementation (each implementation must confirm that it can ship the change).
  4. After merge, update the implementations and refresh the summary in this section.