SEP-414: Document OpenTelemetry Trace Context Propagation Conventions #414
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,96 @@ | ||
| # SEP-414: Document OpenTelemetry Trace Context Propagation Conventions | ||
|
|
||
| - **Status**: Final | ||
| - **Type**: Standards Track | ||
| - **Created**: 2025-04-25 | ||
| - **Author(s)**: Adrian Cole (@codefromthecrypt) | ||
| - **Sponsor**: Marcelo Trylesinski (@Kludex) | ||
| - **PR**: https://github.com/modelcontextprotocol/modelcontextprotocol/pull/414 | ||
|
|
||
| ## Abstract | ||
|
|
||
| This SEP documents conventions for OpenTelemetry (OTel) trace context propagation in MCP. | ||
|
|
||
| [OTel semantic conventions for MCP](https://github.com/open-telemetry/semantic-conventions/blob/e126ea9105b15912ccd80deab98929025189b696/docs/gen-ai/mcp.md#context-propagation) | ||
| specify using `_meta` as the carrier for W3C Trace Context keys. This is already in practice in the | ||
| C# SDK and other implementations. | ||
|
|
||
| This specification documents an exception to the DNS prefixing convention for keys in `_meta`. | ||
| This enables interoperability across existing and new implementations and serves as a foundation | ||
| for related SEPs (such as [SEP-2028](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2028)). | ||
|
|
||
| ## Specification | ||
|
|
||
| This SEP adds documentation to the MCP specification, noting: | ||
|
|
||
| 1. When OTel trace context is propagated via `_meta`, the keys `traceparent`, `tracestate`, and | ||
| `baggage` follow [W3C Trace Context](https://www.w3.org/TR/trace-context/) and | ||
| [W3C Baggage](https://www.w3.org/TR/baggage/) value formats. | ||
|
|
||
| 2. A non-normative example showing trace context in `_meta`. | ||
|
|
||
| 3. A note clarifying why this an exception to DNS prefixing keys in `_meta`: to remain | ||
| compatible with existing implementations and the OpenTelemetry semantic conventions. | ||
|
|
||
| See [agentclientprotocol/agent-client-protocol#297](https://github.com/agentclientprotocol/agent-client-protocol/pull/297) | ||
| for equivalent documentation changes in ACP. | ||
|
|
||
| ### Non-normative example | ||
|
|
||
| ```json | ||
| { | ||
| "jsonrpc": "2.0", | ||
| "id": 2, | ||
| "method": "tools/call", | ||
| "params": { | ||
| "name": "get_weather", | ||
| "arguments": { | ||
| "location": "New York" | ||
| }, | ||
| "_meta": { | ||
| "traceparent": "00-0af7651916cd43dd8448eb211c80319c-00f067aa0ba902b7-01" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Rationale | ||
|
|
||
| ### Why document this? | ||
|
|
||
| This is currently documented elsewhere, but not as an MCP specification. Doing so ensures that | ||
| SEPs depending on this pattern can complete, as well as other SDKs in and outside the MCP org | ||
|
Contributor
Author
There was a problem hiding this comment. they are listed in the below section of SEPs |
||
| can as well, such as [Logfire](https://github.com/pydantic/logfire/blob/09232402fd7e268c667db59d1e9f890ed30f7850/logfire/_internal/integrations/mcp.py#L149-L162) and [ToolHive](https://github.com/stacklok/toolhive/issues/3399). | ||
|
|
||
| If we don't document this shared concern, differing interpretations could materialize, such | ||
| as namespacing traceparent like `io.modelcontextprotocol.traceparent`, which will break traces | ||
| and log correlation. | ||
|
|
||
| ### Related SEPs | ||
|
|
||
| - [SEP-1788](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1788) - reserved | ||
| keys in `_meta`; should be updated with `traceparent`, `tracestate`, and `baggage` when this | ||
| SEP is implemented | ||
| - [SEP-2028](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2028) - builds on | ||
| this SEP for forwarding `_meta` values to HTTP headers | ||
|
|
||
| ## Backward Compatibility | ||
|
|
||
| This SEP documents existing conventions and is backward compatible. | ||
|
|
||
| ## Security Implications | ||
|
|
||
| Trace context in `_meta` may include correlation IDs. Implementations should follow existing | ||
| data-handling guidance appropriate to their environment. | ||
|
|
||
| ## Reference Implementation | ||
|
|
||
| Existing implementations using this pattern: | ||
|
|
||
| - [C# SDK instrumentation](https://github.com/modelcontextprotocol/csharp-sdk/blob/main/src/ModelContextProtocol.Core/Diagnostics.cs) | ||
| - [Python SDK instrumentation](https://github.com/modelcontextprotocol/python-sdk/pull/1693) | ||
| - [OpenInference MCP instrumentation (Python)](https://github.com/Arize-ai/openinference/tree/main/python/instrumentation/openinference-instrumentation-mcp) | ||
| - [OpenInference MCP instrumentation (TypeScript)](https://github.com/Arize-ai/openinference/tree/main/js/packages/openinference-instrumentation-mcp) | ||
| - [Envoy AI Gateway](https://github.com/envoyproxy/ai-gateway/blob/6331b54aef81dd6c8d3d184acc4e2cb8167cea2a/internal/tracing/tracingapi/mcp.go) | ||
| - [Logfire](https://github.com/pydantic/logfire/blob/09232402fd7e268c667db59d1e9f890ed30f7850/logfire/_internal/integrations/mcp.py#L149-L162) | ||
| - [ToolHive](https://github.com/stacklok/toolhive/issues/3399) | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hmm, _meta keys are supposed to have reverse DNS vendor prefix (e.g.
io.opentelemetry/traceparent), so this is not compliant with how things are supposed to be. The problem is that it seems everyone is already doing this.... may need a pragmatic compromise.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Q: How disruptive would it be to have OpenTelemetry update this? Perhaps add both during a deprecation period?
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There is a huge ecosystem already using opentelemetry that has adopted the
traceparentconvention, and changing that would have a very high impact. I think this change is unlikely to happen.Namespacing with the vendor prefix makes perfect sense for things that are new, but I think it is important to acknowledge that there may be some widely adopted and well-established conventions already in the ecosystem that, if we want this to be as interoperable as possible and facilitate adoption, should be supported.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
added a commit to clarify this exception