Propose W3C multi-tenant tracestate (tenant-id@system-id) upstream to OpenTelemetry

[michaelbushe]

The gap

The W3C Trace Context spec defines a second key form for tracestate list members: {tenant-id}@{system-id} — "in the case of multi-tenant vendors, the key SHOULD be in this format" (used in the wild, e.g. Dynatrace's {tenant}@dt). OpenTelemetry has no trace of it: the spec's TraceState API section, the semantic conventions, and the language APIs (Java, Go, JS, Python surveyed) all treat tracestate keys as opaque strings with no multi-tenant surface — some SDK validators are stricter than W3C and would reject the form outright.

What this library already does (prior art)

• Validation accepts the form with per-part W3C grammars (tenant-id ≤ 241 starting lcalpha/DIGIT; system-id ≤ 14 starting lcalpha) — shipped since 1.0.0-beta.7.
• feat: first-class W3C multi-tenant tracestate keys (tenant-id@system-id) #48 adds first-class, vendor-neutral helpers: TraceState.multiTenantKey(), putMultiTenant/getMultiTenant, tenantsForSystem() — fail-fast validation, header round-trip tested.

The SIG angle

This is a concrete, well-scoped upstream contribution for the OTel Client SIG / specification:

1. Spec issue (opentelemetry-specification): the TraceState API section should acknowledge the W3C multi-tenant key form and require implementations to accept it (some validators reject it — a W3C conformance bug), and optionally define an API for it.
2. Proposal: add multiTenantKey-style accessors to the TraceState API spec (this library's feat: first-class W3C multi-tenant tracestate keys (tenant-id@system-id) #48 surface is the strawman — vendor-neutral, no behavior beyond the W3C grammar).
3. Positioning: Dart's reference implementation is the first OTel API with first-class support — useful prior art for the proposal, and a good visibility point for the Dart/Flutter SIG formation.

Draft upstream issue text lives below; Michael posts upstream comms himself.

Draft for opentelemetry-specification

Title: TraceState API ignores W3C's multi-tenant key form (tenant-id@system-id)

W3C Trace Context defines two key forms for tracestate list members; the second, {tenant-id}@{system-id}, is the one the spec recommends for multi-tenant vendors and is used in production today (e.g. {tenant}@dt). The OTel specification's TraceState API section doesn't mention it, and several SDK validators reject @ in keys — making them non-conformant with W3C when interoperating with multi-tenant vendors' tracestate entries.

Proposal:

1. Require TraceState implementations to accept the W3C multi-tenant key form (conformance fix).
2. (Optional) Specify convenience accessors: build/validate a multi-tenant key from (tenantId, systemId); get/put by pair; enumerate a system's tenants. Prior art: the Dart OTel API implements exactly this surface, vendor-neutrally [link].

Non-goals (platform posture, recorded so it isn't relitigated)

Stamping {orgId}@dartastic from SDKs is not enabled by default anywhere: tracestate propagates to every downstream hop including third-party services the app calls, so broadcasting tenant identity is an opt-in decision for a feature that consumes it (cross-service per-tenant sampling, edge diagnostics). Ingest tenancy remains derived from the verified key — tracestate tenant is context, never authorization.

Why no language implements it (and why that's the pitch, not the objection)

Likely the real reason every OTel API ignores the W3C form (Michael, 2026-07-11): naive support reads as automatic tenant propagation, and tracestate flows to every downstream hop — including third-party services the instrumented app calls — so stamping tenant identity by default is a privacy leak. The upstream proposal should lead with this: the ask is explicit accessors + validation conformance only (accept the W3C form, offer typed get/put), with automatic stamping explicitly out of scope. That converts the reason-nobody-built-it into the design constraint of the proposal.