OpenTelemetry GenAI Agent SemConv Cheat Sheet [2026]

Overview

As of April 17, 2026, the OpenTelemetry docs surface Semantic Conventions 1.40.0, and the GenAI and MCP semantic convention pages are still labeled Development. For AI agent observability, the highest-signal items are the agent lifecycle spans create_agent and invoke_agent, tool execution via execute_tool, the required duration metric gen_ai.client.operation.duration, and the recommended usage metric gen_ai.client.token.usage.

This reference is intentionally broad. It prioritizes what to name spans, what attributes to keep low-cardinality, when to opt into prompt or output capture, and which environment variables matter when you wire OTLP export into production.

The one rule that prevents most broken AI telemetry

Record stable identifiers and operation names by default, but keep full instructions, inputs, and outputs opt-in. OpenTelemetry explicitly recommends that sensitive GenAI payloads should not be captured automatically.

Live Search

Filter the cheat sheet: press / to focus search, then type an operation, attribute, metric, or env var such as invoke_agent, gen_ai.request.model, or OTELEXPORTEROTLP_ENDPOINT.

Agent spans

create_agent, invoke_agent, and execute_tool are the anchor operations for agent lifecycle and tool calls.

Core metrics

gen_ai.client.operation.duration is required. gen_ai.client.token.usage is recommended when token counts are available.

Payload capture

Instructions, inputs, and outputs are opt-in and should remain off by default in production.

Version gate

Use OTELSEMCONVSTABILITYOPTIN when your instrumentation supports the latest experimental GenAI conventions.

SDK config

Set service identity, resource attributes, sampling policy, and propagators before chasing span-level detail.

MCP interoperability

MCP spans add transport and method context that plain RPC spans do not capture cleanly.

Keyboard Shortcuts

Shortcut	Action	Why it matters
/	Focus live search	Jump straight to an operation, attribute, metric, or env var.
g then s	Go to commands by purpose	Useful when mapping spans and attributes during implementation.
g then c	Go to configuration	Fast path to OTLP and sampler settings.
g then a	Go to advanced usage	Jump to payload capture, external storage, and MCP notes.
?	Toggle shortcut help	Small but useful for internal docs portals and team handoffs.

Shortcut hint: the g key starts a two-key navigation sequence. After pressing it once, hit s, c, or a within a second.

Commands Grouped by Purpose

Lifecycle

Remote agent creation and invocation

Use create_agent when your app creates or provisions a remote agent service.
Use invoke_agent when your app runs an existing agent against a task or conversation.
Keep gen_ai.provider.name, gen_ai.request.model, server.address, and server.port available at span creation time when possible because they are useful for sampling and routing decisions.
Prefer low-cardinality naming: createagent {genai.agent.name} and invokeagent {genai.agent.name} when the agent name is stable and readily available.

Tooling

Tool calls and action execution

Use execute_tool for function or tool execution driven by the agent.
Set gen_ai.tool.name for the stable tool identifier, not the full prompt text or user request.
For MCP-based tool calls, add mcp.method.name, mcp.session.id, and transport metadata such as network.transport and network.protocol.name.
Only capture gen_ai.tool.call.arguments and gen_ai.tool.call.result when your privacy and retention model explicitly allows it.

Cost and latency

Metrics that matter first

gen_ai.client.operation.duration: required histogram for end-to-end GenAI client operation latency.
gen_ai.client.token.usage: recommended histogram for input and output token counts when the numbers are readily available.
If the provider only exposes billable tokens, report billable tokens rather than guessed totals.
If token counts are expensive to compute offline, do not emit fake precision. OpenTelemetry says instrumentation must not report usage metrics when it cannot efficiently obtain them unless the user explicitly enables offline counting.

Payloads

Instructions, inputs, and outputs

Keep genai.systeminstructions, gen_ai.input.messages, and gen_ai.output.messages off by default.
Turn them on in pre-production or tightly controlled debugging environments only.
In production, prefer external object storage plus a pointer on the span instead of embedding large payloads directly.
If you need to inspect prompts safely, run samples through TechBytes' Data Masking Tool before they reach long-lived telemetry stores.

Errors

Failure handling

Use error.type for a low-cardinality failure class such as a timeout, provider error code, or canonical exception name.
Do not dump raw stack traces into custom GenAI attributes. Keep exception details in the normal exception fields and events.
Set span status to error when the operation fails and let downstream tools correlate the stable error identifier with logs.

Agent lifecycle quick map

createagent   -> Provision or register an agent
invokeagent   -> Run the agent on a task or conversation
executetool   -> Execute a tool or function on the agent's behalf

High-signal attributes
- genai.operation.name
- genai.provider.name
- genai.request.model
- genai.agent.name
- genai.tool.name
- error.type

const attrs = {
  'genai.operation.name': 'invokeagent',
  'genai.provider.name': 'openai',
  'genai.request.model': 'gpt-4.1',
  'genai.agent.name': 'support-router',
  'genai.conversation.id': 'conv_7f2e',
  'server.address': 'api.example.ai'
};

Configuration

Most teams waste time tweaking span attributes before fixing exporter topology and resource identity. Start here instead.

Base SDK settings

OTELSERVICENAME: sets service.name and takes precedence over the same key in OTELRESOURCEATTRIBUTES.
OTELRESOURCEATTRIBUTES: attach deployment, region, tenant, or workload identity that should apply to every signal.
OTEL_PROPAGATORS: defaults to tracecontext,baggage in the spec.
OTELTRACESSAMPLER: defaults to parentbasedalwayson. Use ratio-based sampling when AI traffic is too expensive to keep at 100%.

GenAI semantic convention transition

The GenAI spec documents a migration path for older instrumentations. If your library supports it, OTELSEMCONVSTABILITYOPTIN=genailatest_experimental opts into the latest experimental GenAI conventions instead of older emitted variants.

export OTELSERVICENAME=agent-gateway
export OTELRESOURCEATTRIBUTES=deployment.environment=prod,service.namespace=assistants
export OTELPROPAGATORS=tracecontext,baggage
export OTELTRACESSAMPLER=parentbasedtraceidratio
export OTELTRACESSAMPLERARG=0.25
export OTELSEMCONVSTABILITYOPTIN=genailatestexperimental

OTLP endpoint rules that trip people up

OTELEXPORTEROTLP_ENDPOINT is the shared base endpoint.
OTELEXPORTEROTLPTRACESENDPOINT overrides traces only.
For OTLP/HTTP, the base endpoint automatically expands to signal paths like /v1/traces, but signal-specific endpoints are used as-is.
That means a base endpoint and a per-signal traces endpoint do not behave identically.

export OTELEXPORTEROTLP_ENDPOINT=http://collector:4318
# Traces -> http://collector:4318/v1/traces
# Metrics -> http://collector:4318/v1/metrics
# Logs    -> http://collector:4318/v1/logs

export OTELEXPORTEROTLPTRACESENDPOINT=http://collector:4318
# For OTLP/HTTP, this traces endpoint is used as-is.
# It does not automatically append /v1/traces.

If you are generating or cleaning snippets before sharing them internally, TechBytes' Code Formatter is a practical way to normalize shell, JSON, and code examples for observability runbooks.

Advanced Usage

1. Capture content without poisoning your telemetry store

OpenTelemetry recommends three patterns: do not record content, record content directly on spans, or store content externally and record references. For most production agent systems, the third option is the only one that scales cleanly across privacy review, retention rules, and cost control.

Preferred production pattern

Span attributes:
- genai.operation.name=invokeagent
- gen_ai.agent.name=support-router
- app.payload.ref=s3://secure-telemetry/trace-123/payload.json

External store:
- encrypted prompt and output payloads
- separate IAM boundary
- shorter retention than trace metadata

2. Use MCP conventions when your tools speak MCP

If your agent communicates through the Model Context Protocol, use the MCP semantic conventions instead of flattening everything into generic RPC spans. You gain method names like initialize and tool-call context via gen_ai.tool.name, plus session and transport metadata that are otherwise easy to lose.

3. Keep span names readable and attribute values stable

Good span name: invoke_agent support-router
Bad span name: user-specific free text, long prompts, or fully rendered tool arguments
Good attribute value: gen_ai.request.model=gpt-4.1
Bad attribute value: unbounded concatenated prompt fragments

4. Budget for cardinality up front

Agent systems can explode cardinality fast because every thread, tool result, or retrieved document looks unique. Keep identifiers like conversation IDs available for correlation, but do not promote them to dimensions that your backend aggregates blindly. Stable fields belong in metrics dimensions. Noisy fields belong in traces, events, or external payload storage.

Canonical Docs

GenAI semantic conventions GenAI agent spans GenAI metrics GenAI spans and payload capture MCP semantic conventions SDK environment variables OTLP exporter spec