diff --git a/COMPLIANCE.md b/COMPLIANCE.md new file mode 100644 index 0000000..93892ef --- /dev/null +++ b/COMPLIANCE.md @@ -0,0 +1,65 @@ +# OpenTelemetry Specification Compliance + +This document tracks the compliance of `dartastic_opentelemetry_api` — the +OpenTelemetry API for Dart — against the +[OpenTelemetry specification](https://opentelemetry.io/docs/specs/otel/) +and the W3C Trace Context Recommendation. It is the durable record of the +2026-07 spec-compliance audit wave coordinated in +[#44](https://github.com/MindfulSoftwareLLC/dartastic_opentelemetry_api/issues/44). + +## How compliance is verified + +Every audited clause follows the same TDD shape: + +1. A commit pins the contract with **red** tests that quote the spec + clause verbatim. +2. A commit turns them **green** — or, where the fix needed design work, + the red tests were `skip:`-ed behind a linked issue so CI stayed green + until the fix landed, then unskipped by the fix PR. + +Semantic conventions are verified differently: the enums are generated +from the registry model with OTel Weaver, and the generator also emits +audit tests asserting every key, value, metric, event, and entity against +the registry it was generated from (see PR +[#52](https://github.com/MindfulSoftwareLLC/dartastic_opentelemetry_api/pull/52)). + +## Status matrix + +Statuses reflect the repository as of 2026-07-18 — the audit wave is +fully merged. Version numbers refer to the release train in +[CHANGELOG.md](CHANGELOG.md); "beta.10" entries ship with the +`1.0.0-beta.10` release. + +| Spec area | Clause(s) | Status | Where | +| --- | --- | --- | --- | +| Context (`context/README.md`) | Context works before/without initialization; keys are unique; immutability | Shipped (beta.8/beta.9) | #27, #31, #32, #34 | +| Propagators (`context/api-propagators.md`) | Global `TextMapPropagator` get/set; "MUST use no-op propagators unless explicitly configured otherwise"; factory-routed like all API objects | Shipped (beta.10) | [#55](https://github.com/MindfulSoftwareLLC/dartastic_opentelemetry_api/pull/55) (fixed #42; #43 pinned the contract) | +| Baggage (`baggage/api.md`, `error-handling.md`) | Values are any valid UTF-8 string incl. empty; API methods never throw on misuse | Shipped (beta.10) | [#36](https://github.com/MindfulSoftwareLLC/dartastic_opentelemetry_api/pull/36) | +| Trace: no-SDK behavior (`trace/api.md`) | Non-recording spans; parent `SpanContext` passthrough; all-zero empty span; `NonRecordingSpan` wrapper | Shipped (beta.10) | [#54](https://github.com/MindfulSoftwareLLC/dartastic_opentelemetry_api/pull/54) (fixed #40; #41 pinned the contracts) | +| Trace: `TraceState` (`trace/api.md`, `error-handling.md`) | Mutations validate input, never throw, never return invalid data | Shipped (beta.10) | [#37](https://github.com/MindfulSoftwareLLC/dartastic_opentelemetry_api/pull/37) | +| Trace: `tracestate` grammar (W3C Trace Context) | Key/value grammar incl. multi-tenant `tenant-id@system-id` form (tenant ≤ 241 starting `lcalpha`/DIGIT, system ≤ 14 starting `lcalpha`) | Shipped (beta.7, exact grammar beta.9) | #38 | +| Trace: multi-tenant `tracestate` accessors | Typed multi-tenant key helpers (beyond the spec — W3C conformance prior art) | Parked pre-donation | #48 (ships as a Dartastic extension); upstream proposal: [#53](https://github.com/MindfulSoftwareLLC/dartastic_opentelemetry_api/pull/53) (fixes #49) | +| Providers (`trace/api.md`, `error-handling.md`) | `tracerProvider('')`/`meterProvider('')`/`loggerProvider('')` return working defaults, never throw | Shipped (beta.10) | [#39](https://github.com/MindfulSoftwareLLC/dartastic_opentelemetry_api/pull/39) | +| API lifecycle | Pre-initialization accessors lazily install the no-op API factory instead of throwing | Shipped (beta.8/beta.9) | #27, #32, #33, #34 | +| Semantic conventions (attribute registry, metrics, events, entities) | Full registry coverage, generated with OTel Weaver, per-namespace files, registry-audit tests | Shipped (beta.10) | [#52](https://github.com/MindfulSoftwareLLC/dartastic_opentelemetry_api/pull/52) (fixed #50, #51) | + +## Known gaps and posture + +- **`telemetry.sdk.language` has no `dart` well-known value upstream** — + an upstream semantic-conventions gap discovered while generating the + registry enums; SDKs keep emitting the literal `dart`. Candidate for an + upstream PR alongside the multi-tenant `tracestate` proposal + ([doc/proposals/tracestate-multi-tenant.md](doc/proposals/tracestate-multi-tenant.md) + once merged). +- **Vendor/RUM conventions** are not part of the OTel specification and + are deprecated for removal from this package (see PR #52); the API + surface will contain only official conventions. +- **Metrics and Logs API clauses** were not part of this audit wave + beyond the provider-accessor and lifecycle work; they are the natural + next audit targets. + +## Coordination + +This work is part of standing up the **Dart & Flutter SIG**. Discussion +happens publicly on the issues and PRs above (interim home: #44) until +the SIG's CNCF Slack channel exists.