getsentry / getsentry/sentry-javascript

mcp-server integration: align attribute names to current OTel GenAI/MCP semconv

Aperta
#21,482 2 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Improvement javascript Spans
Lingua principale
TypeScript
Stelle
8.7k
Fork
1.8k
Merge medio
1g 17h
PR unite (30g)
515

Descrizione

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)

Guida per i contributori

Apri la guida per i contributori

Valutazione

Questa issue non è ancora stata valutata.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.