getsentry / getsentry/sentry-javascript
mcp-server integration: align attribute names to current OTel GenAI/MCP semconv
- 主要语言
- TypeScript
- 星标
- 8.7k
- 派生
- 1.8k
- 平均合并
- 1 天 17 小时
- 30 天内合并 PR
- 515
描述
The MCP server integration's `attributes.ts` is pinned to an old draft of the OTel MCP spec ([commit `3097fb0`](https://github.com/open-telemetry/semantic-conventions/blob/3097fb0af5b9492b0e3f55dc5f6c21a3dc2be8df/docs/gen-ai/mcp.md) in the now-deprecated `open-telemetry/semantic-conventions` repo). The spec has since moved to [`open-telemetry/semantic-conventions-genai`](https://github.com/open-telemetry/semantic-conventions-genai) and the attribute names have materially changed.
## Wrong attribute names
The following SDK constants emit the wrong attribute key. Each has a verified spec equivalent.
| SDK constant | Emits | Should emit | Requirement level | Source |
|---|---|---|---|---|
| `MCP_TOOL_NAME_ATTRIBUTE` | `mcp.tool.name` | `gen_ai.tool.name` | Conditionally required (tool calls) | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) |
| `MCP_PROMPT_NAME_ATTRIBUTE` | `mcp.prompt.name` | `gen_ai.prompt.name` | Conditionally required (prompt ops) | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) |
| `MCP_REQUEST_ID_ATTRIBUTE` | `mcp.request.id` | `jsonrpc.request.id` | Conditionally required (requests) | [spans.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/spans.yaml) |
| `MCP_TRANSPORT_ATTRIBUTE` | `mcp.transport` | `network.transport` | Recommended | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) |
| `MCP_REQUEST_ARGUMENT` (prefix) | `mcp.request.argument.` | `gen_ai.tool.call.arguments` (single attr) | Opt-in | [spans.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/spans.yaml) |
| `MCP_TOOL_RESULT_CONTENT_ATTRIBUTE` | `mcp.tool.result.content` | `gen_ai.tool.call.result` (single attr) | Opt-in | [spans.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/spans.yaml) |
| `MCP_TOOL_RESULT_IS_ERROR_ATTRIBUTE` | `mcp.tool.result.is_error` | `error.type = "tool_error"` | Conditionally required | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) |
Notes:
- `network.transport` values SHOULD be `tcp` or `quic` for HTTP transport and `pipe` for stdio — not the MCP-level transport name.
- `gen_ai.tool.call.arguments` and `gen_ai.tool.call.result` are single serialized attributes, not per-key prefixes.
- `mcp.tool.result.content_count` has no spec equivalent at all.
## Missing attributes
| Attribute | Requirement level | Source | Notes |
|---|---|---|---|
| `gen_ai.operation.name` | Recommended | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) | SHOULD be `execute_tool` on tool call spans; allows consumers to treat MCP tool spans like other GenAI tool spans |
| `rpc.response.status_code` | Conditionally required | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) | When response contains a JSON-RPC error code |
| `jsonrpc.protocol.version` | Recommended | [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) | When not `2.0` |
## Custom attributes with no spec equivalent
These are Sentry-invented attributes that don't appear in the OTel spec. They may be worth keeping as explicit Sentry extensions, but should be documented as such and should not use namespaces that conflict with or extend spec-owned ones:
- `mcp.client.name`, `mcp.client.title`, `mcp.client.version`
- `mcp.server.name`, `mcp.server.title`, `mcp.server.version`
- `mcp.logging.level`, `mcp.logging.logger`, `mcp.logging.data_type`, `mcp.logging.message`
- `mcp.prompt.result.description`, `mcp.prompt.result.message_count`, `mcp.prompt.result.message_role`, `mcp.prompt.result.message_content`
The `mcp.*` namespace in the spec covers only: `mcp.method.name`, `mcp.session.id`, `mcp.resource.uri`, `mcp.protocol.version`. Anything else under `mcp.*` risks colliding with future spec attributes.
## Spec references
- [open-telemetry/semantic-conventions-genai — model/mcp/](https://github.com/open-telemetry/semantic-conventions-genai/tree/main/model/mcp) (current authoritative source)
- [common.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/common.yaml) — shared attributes including `gen_ai.tool.name`, `gen_ai.prompt.name`, `gen_ai.operation.name`
- [spans.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/spans.yaml) — span definitions with `gen_ai.tool.call.arguments`, `gen_ai.tool.call.result`
- [registry.yaml](https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/mcp/registry.yaml) — full `mcp.*` attribute registry (only 4 attributes)
贡献指南
评估
这个 Issue 还没有评估数据。