Skip to content

docs: upstream proposal — W3C multi-tenant tracestate keys - #53

Open
michaelbushe wants to merge 1 commit into
mainfrom
docs/49-upstream-tracestate-proposal
Open

docs: upstream proposal — W3C multi-tenant tracestate keys#53
michaelbushe wants to merge 1 commit into
mainfrom
docs/49-upstream-tracestate-proposal

Conversation

@michaelbushe

Copy link
Copy Markdown
Member

Fixes #49

Adds doc/proposals/tracestate-multi-tenant.md: the finalized, ready-to-post upstream proposal for the W3C multi-tenant tracestate key form (tenant-id@system-id). The document leads with the privacy constraint that explains why no OTel API supports the form (naive support reads as automatic tenant propagation, and tracestate flows to every downstream hop including third-party services), then asks for two things: a required conformance fix (TraceState implementations MUST accept the W3C multi-tenant key form) and optional vendor-neutral convenience accessors, with automatic stamping explicitly out of scope. W3C and OTel spec text is quoted verbatim (verified against the published Recommendation and spec), and the supporting-notes section records the shipped 241/14 validation grammar, the platform posture from #49, and the SIG positioning. Docs-only: no code or CHANGELOG changes; dart analyze --fatal-infos and dart format remain clean.

Posting to open-telemetry/opentelemetry-specification remains Michael's manual step — this doc is the copy-paste artifact (section 2 is the paste; section 3 is discussion notes).

🤖 Generated with Claude Code

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@robert-northmind

robert-northmind commented Jul 20, 2026

Copy link
Copy Markdown
Collaborator

Hi @michaelbushe, I'm learning a lot about Otel now thanks to your PRs. So big thanks ☺️

On this PR, I think there might be some confusion. At least for me.
There seems to be a new draft version of the W3C Trace Context. Called Level-2. (still in draft). Here
And it changes the key grammar and meaning of a @ in a TraceState. It seems that there is no longer a dedicated meaning attached to @. Instead is it just a normal allowed char in the TraceState key.

And the OTel Spec Api propagators references that TraceContexts should be parsed and validated agains that Level-2 version. See here.

So maybe this is a reason why the Otel TraceState Docs do not mention the multi-tenant?
There is a link in the Otel TraceState Docs though, which still links to the Level-1 version. So maybe that link should be fixed to instead point to the Level-2.

I also found this in the TraceState handling docs explicitly recognizes multi-tenant syntax but says OpenTelemetry does not specify its interpretation:

OpenTelemetry recognizes this syntax but does not specify an interpretation for multi-tenant tracestate.

And for this comment:

a required conformance fix (TraceState implementations MUST accept the W3C multi-tenant key form)

I just did a check against the opentelemetry-js code, and it seems that it support the multi-tenant format:
https://github.com/open-telemetry/opentelemetry-js/blob/40d67b7690a61bd9af0a4e5b5b9f4a14b11fc50e/packages/opentelemetry-core/src/internal/validators.ts#L6-L33

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

2 participants