OpenTelemetry GenAI Semantic Conventions for Security Teams: Agent, MCP and LLM Telemetry for Audit and Detection

Security teams cannot investigate an agent incident if every framework logs model calls, tool calls and MCP traffic in its own format, and the OpenTelemetry GenAI semantic conventions are becoming the shared schema that fixes this. They define span names, attributes and metrics for model inference, agent invocations, tool execution, MCP and A2A, so that one trace can follow a user request through an agent, its tools and other agents. This guide explains what the conventions contain from a security point of view, which attributes matter for audit and detection, how to handle prompt and tool content safely, and what the conventions do not yet cover, such as the delegated user and the credential used. It reflects the conventions as published on 27 October 2026, after they moved to a dedicated repository, and is written for detection engineers, SOC teams and platform engineers instrumenting agents. For the wider observability picture see the LLM Observability Guide.

Key takeaways

• Status is Development and the home has moved. The opentelemetry.io page now shows a "Moved" notice pointing to the open-telemetry/semantic-conventions-genai repository, whose documents are marked Development and which had not cut a release at the time of checking. Expect attribute names to change.
• The schema covers the whole agent path. There are spans for inference, embeddings, retrieval, memory, create_agent, invoke_agent, invoke_workflow, plan and execute_tool, plus dedicated MCP and A2A conventions.
• Content capture is off by default. Prompts, outputs, tool arguments and tool results are opt-in, and the conventions recommend external storage with references for production use.
• Trace context crosses MCP. Both the MCP specification (revision 2026-07-28) and the conventions use unprefixed traceparent, tracestate and baggage keys in params._meta, which links client and server spans across the protocol.
• Identity is your job. The conventions name agents, tools, conversations and servers, but not the end user an agent acts for or the token it used. Add those attributes yourself.

Where the conventions stand

The GenAI conventions began in the main OpenTelemetry semantic conventions repository and have moved to open-telemetry/semantic-conventions-genai, which extends the core conventions (it references core version 1.44.0) and generates its Markdown from YAML models using the Weaver tool. At the time of checking, its changelog contained only unreleased entries and its schema URL was still marked as to be decided. Every GenAI, MCP and A2A document is marked Development, the OpenTelemetry status that allows breaking changes.

• What this means for detection content: write detections against a normalised view in your SIEM or pipeline, not directly against raw attribute names, so a rename is a mapping change rather than a rule rewrite.
• Version pinning: record the instrumentation library version and the conventions version on each resource, so analysts know which names applied when.
• Provider and evaluation coverage: provider-specific pages exist for Anthropic, Azure AI Inference, AWS Bedrock and OpenAI, and a gen_ai.evaluation.result event records evaluation outcomes. Where you run guardrail or safety classifiers, emitting their verdicts as evaluation results keeps them in the same trace as the call they judged.
• Lagging protocol details: the MCP conventions still define mcp.session.id and session duration metrics and link to MCP revision 2025-11-25, while MCP 2026-07-28 removed protocol sessions. Expect gaps when conventions trail protocol revisions.

The spans that matter for security

Metrics worth collecting

• Agent behaviour: gen_ai.invoke_agent.duration, gen_ai.invoke_agent.tool_calls and gen_ai.invoke_agent.inference_calls, which are scoped to a single agent invocation and expose loops and runaway runs.
• Tools and MCP: gen_ai.execute_tool.duration, mcp.client.operation.duration and mcp.server.operation.duration by tool and server.
• Consumption: gen_ai.client.operation.duration and the token metrics such as gen_ai.client.inference.usage.input_tokens and gen_ai.client.inference.usage.output_tokens, the basis for detecting resource abuse (MITRE ATLAS AML.T0034.002 Agentic Resource Consumption).

Propagating context across MCP and agents

HTTP trace propagation alone only covers the HTTP request, not individual MCP messages, and stdio has no HTTP at all. The MCP conventions therefore tell instrumentations to inject context with the configured OpenTelemetry propagators into params._meta, using the unprefixed keys traceparent, tracestate and baggage, and the server to use that context as the remote parent. MCP revision 2026-07-28 formally reserves these three keys as an exception to its rule that _meta keys carry a DNS prefix.

• Treat inbound context as untrusted: a malicious client or server can forge traceparent to attach its activity to someone else's trace or to break correlation. Use propagated context for linking, never for authorisation, and record the authenticated peer alongside it.
• Baggage leaks: baggage travels to every downstream server. Never place user identifiers, tokens or classification labels you would not share with a third-party MCP server in baggage.
• Cross-protocol joins: propagate the same trace through A2A calls so one user request can be followed from the first agent, through a remote agent, to the MCP tool that changed data.

Handling prompts, outputs and tool content safely

The conventions treat instructions, user messages and model outputs as sensitive and often large. Instrumentations SHOULD NOT capture them by default and SHOULD offer opt-in. Three patterns are described:

• Tool arguments and results: gen_ai.tool.call.arguments and gen_ai.tool.call.result are opt-in and flagged as possibly sensitive. They are also the most valuable fields in an incident, because they show what data left through a tool (ATLAS AML.T0086 Exfiltration via AI Agent Tool Invocation). Capture them to a restricted store for high-risk tools rather than everywhere.
• Tool definitions: gen_ai.tool.definitions is opt-in. Capturing a hash of the definitions per run gives you rug-pull and tool-poisoning detection without storing full text each time.
• Secrets in URLs: the A2A conventions require sensitive url.query content to be scrubbed and list keys such as X-Amz-Signature, X-Amz-Credential and X-Amz-Security-Token for redaction to REDACTED. Apply the same scrubbing to every GenAI and MCP span.

See the Privacy in Security Logging and Monitoring Guide for retention and lawful basis questions.

Filling the identity gap

For a security team the most important question in an agent incident is "on whose behalf, with which credential?" The GenAI conventions identify the agent (gen_ai.agent.id, gen_ai.agent.name, gen_ai.agent.version), the conversation, the tool and the MCP or A2A peer, but they do not define attributes for the delegated end user, the OAuth client, the token's scopes or the authorisation server. Add them under your own namespace so they can be renamed later without colliding with official names:

• Delegated subject: a stable, pseudonymous user identifier derived from the verified token (for example a hash of the sub claim), never an email address in clear.
• Agent workload identity: the service account, workload identity or client ID the agent authenticated as.
• Credential context: token issuer, granted scopes or allowance, and a token identifier such as a hash of the jti, never the token itself.
• Policy decision: allow or deny from your gateway or policy engine, with the policy version.

See the Agent Identity and Access Guide for the identity model these attributes should reflect.

Where to instrument: framework, gateway or server

The same tool call can be recorded in three places, and each sees different things. Most organisations need at least two of them, because no single point sees both the model's reasoning context and the authenticated identity on the wire.

• Small teams: start at the gateway, which gives one consistent schema and one redaction point, then add framework instrumentation for the highest-risk agents.
• Large or regulated organisations: instrument all three, require trace propagation in vendor contracts for MCP servers you buy, and keep content stores separate from operational telemetry with their own retention.
• Third-party servers: you will not get their server spans. Treat your gateway and client spans as the record of evidence, and ask vendors whether they propagate the trace context you send.

Detections built on the conventions

Rolling out GenAI telemetry

1. Inventory instrumentation: list agent frameworks, model SDKs, MCP clients and servers, and which already emit GenAI spans. Record library and conventions versions.
2. Decide content policy first: choose pattern 1, 2 or 3 per environment and per tool risk tier, with the data protection officer, before turning anything on.
3. Add identity attributes: implement the namespaced user, workload, credential and policy attributes at the gateway or framework layer.
4. Pilot in pre-production: send to a separate backend, validate trace continuity across MCP and A2A, and check redaction.
5. Normalise in the pipeline: map raw attributes to stable SIEM fields using the OpenTelemetry Collector or your log pipeline, then build detections on the normalised fields.
6. Roll out by ring and keep a kill switch: content capture must be switchable off per service without redeploying; if a leak is found, disable capture, purge the affected store and rotate any secret seen.

Measuring coverage

• Share of agent runs with an unbroken trace from invoke_agent to every execute_tool and MCP server span.
• Share of tool calls carrying delegated subject and credential attributes.
• Share of MCP servers in use that propagate trace context.
• Number of telemetry records found containing secrets or unredacted personal data (target: zero).
• Time to rebuild the full action history of an agent run during an exercise.

Framework mapping

Common failure patterns

• Turning on full content capture in production. Prompts, retrieved documents and tool results then sit in an observability platform that many engineers can query.
• Writing detections on raw Development names. A rename in the conventions silently breaks the rule.
• Broken traces at the MCP boundary. Servers that ignore params._meta context start new traces, so tool actions cannot be tied to the agent run that caused them.
• Trusting propagated context. Treating a traceparent or baggage value as evidence of who called is an authorisation flaw.
• No user or credential on spans. Without them, the trace shows what happened but not whose access was used, which is the question regulators and incident responders ask first.
• Logging tokens in URLs or headers. Unscrubbed query strings and headers put bearer tokens and signed URLs into telemetry.

Practitioner checklist

• Track the semantic-conventions-genai repository and record the conventions version your instrumentation emits.
• Collect invoke_agent, execute_tool, inference, MCP and A2A spans for every production agent.
• Set a content capture pattern per environment; prefer external storage with references in production.
• Capture tool arguments and results only for high-risk tools, into a restricted store.
• Propagate traceparent through MCP params._meta and A2A, and never use it for authorisation.
• Add namespaced attributes for delegated user, workload identity, credential context and policy decision.
• Scrub tokens and signed URL parameters from all GenAI spans.
• Build detections on normalised fields and test them against a recorded agent run.

Standards and references

• OpenTelemetry: GenAI Semantic Conventions repository
• OpenTelemetry: Generative AI semantic conventions (moved notice)
• OpenTelemetry: Semantic conventions for Model Context Protocol
• OpenTelemetry: Semantic conventions for GenAI agent and framework spans
• OpenTelemetry: Semantic conventions for Agent2Agent Protocol
• Model Context Protocol: Base protocol, _meta and trace context (revision 2026-07-28)

Related NHI Mgmt Group resources: LLM Observability Guide · AI Agent Observability and Incident Response Guide · MCP Incident Response Playbook · SIEM Guide