Star

gen_ai.* attributes: OpenTelemetry GenAI semantic conventions

From semantic-conventions-genai at 547934a (schema 1.42.0-dev, no release yet)Synced View as MarkdownOpen in ClaudeOpen in ChatGPT

Short answer

The gen_ai.* attributes describe model calls, agents and tool calls: gen_ai.operation.name, gen_ai.provider.name, gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.agent.name, gen_ai.tool.name and more. Every one is Development. Since 2026 they are defined in the semantic-conventions-genai repository, together with the mcp.* attributes for the Model Context Protocol.

What do the gen_ai.* and mcp.* attributes describe?

An agent run is a tree of model calls and tool calls. The GenAI conventions name each one: chat for a model call, execute_tool for a tool, invoke_agent for the agent around them. The operation goes in gen_ai.operation.name, and the span name is built from it.

Most keys fall into a few groups. gen_ai.request.* and gen_ai.response.* describe one model call, gen_ai.usage.* counts its tokens, gen_ai.agent.* and gen_ai.tool.* say who acted and with what. Message content (gen_ai.input.messages, gen_ai.output.messages) is opt-in.

Which spans set them?

Every span in the conventions that references at least one of these attributes, with the span name it should get and its kind.

  • {gen_ai.operation.name} {gen_ai.request.model}CLIENTgen_ai.client.inference
  • {gen_ai.operation.name} {gen_ai.request.model}CLIENTgen_ai.embeddings.client
  • {gen_ai.operation.name} {gen_ai.data_source.id}CLIENTgen_ai.retrieval.client
  • {gen_ai.operation.name}CLIENTgen_ai.fetch_response.client
  • {gen_ai.operation.name}CLIENTgen_ai.memory.client
  • create_agent {gen_ai.agent.name}CLIENTgen_ai.create_agent.client
  • invoke_agent {gen_ai.agent.name}CLIENTgen_ai.invoke_agent.client
  • invoke_agent {gen_ai.agent.name}INTERNALgen_ai.invoke_agent.internal
  • execute_tool {gen_ai.tool.name}INTERNALgen_ai.execute_tool.internal
  • invoke_workflow {gen_ai.workflow.name}INTERNALgen_ai.invoke_workflow.internal
  • plan {gen_ai.agent.name}INTERNALgen_ai.plan.internal
  • {mcp.method.name}CLIENTmcp.client
  • {mcp.method.name}SERVERmcp.server
  • {gen_ai.operation.name} {gen_ai.request.model}CLIENTopenai.gen_ai.client.inference (refines gen_ai.client.inference)
  • {gen_ai.operation.name}CLIENTopenai.fetch_response.client (refines gen_ai.fetch_response.client)
  • {gen_ai.operation.name} {gen_ai.request.model}CLIENTazure.ai.gen_ai.client.inference (refines gen_ai.client.inference)
  • {gen_ai.operation.name} {gen_ai.request.model}CLIENTanthropic.gen_ai.client.inference (refines gen_ai.client.inference)
  • {gen_ai.operation.name} {gen_ai.request.model}CLIENTaws.bedrock.gen_ai.client.inference (refines gen_ai.client.inference)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name}INTERNALgen_ai.execute_tool.load_skill.internal (refines gen_ai.execute_tool.internal)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name}INTERNALgen_ai.execute_tool.read_skill_resource.internal (refines gen_ai.execute_tool.internal)
  • gen_ai.execute_tool.command.internalINTERNALgen_ai.execute_tool.command.internal (refines gen_ai.execute_tool.internal)

What does a real span record?

execute_tool pay_vendorINTERNAL
AttributeValue
gen_ai.operation.nameexecute_tool
gen_ai.tool.namepay_vendor
gen_ai.tool.call.idcall_1
gen_ai.tool.typefunction
gen_ai.tool.call.arguments{"amountEth":"0.25"}
From a real run on 2026-10-04: the AI SDK example agent in the hashspan repository, ai 7.0.127, @ai-sdk/otel 1.0.127, a scripted offline model, local Anvil chain. The run in full.

The chat span before it carried gen_ai.operation.name chat, gen_ai.request.model scripted-model and gen_ai.response.finish_reasons ["tool-calls"]. The model was scripted, so its provider and token counts are not real ones.

Why does the OpenTelemetry registry show gen_ai.* as deprecated?

Because the names moved, not because they changed. In semantic-conventions v1.44.0 every gen_ai.* attribute is marked deprecated with the note "Moved to the OpenTelemetry GenAI semantic conventions repository", and the registry on opentelemetry.io shows that as Deprecated. The JavaScript package does the same: version 1.43.0 already marks ATTR_GEN_AI_AGENT_ID deprecated.

The rows on this page come from the new repository, so they show the current status. The ones marked Deprecated here were really renamed or removed, such as gen_ai.system, now gen_ai.provider.name.

One rename shows up in real traces. In the run above, AI SDK recorded gen_ai.usage.cache_creation.input_tokens. The GenAI repository has since renamed it to gen_ai.usage.cache_write.input_tokens, so a dashboard that groups by one name misses the other.

All 79 gen_ai.* attributes

gen_ai.agent.description

stringDevelopment

Free-form description of the GenAI agent provided by the application.

Examples Helps with math problems, Generates fiction stories

Set on
  • create_agent {gen_ai.agent.name} CLIENT: gen_ai.create_agent.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (conditionally required)

Official definition

gen_ai.agent.id

stringDevelopment

The unique and stable identifier of the GenAI hosted agent resource.

Examples asst_5j66UpCpwteGg4YSxUnt7lPY, arn:aws:bedrock:us-east-1:123:agent/42, urn:agent:projects-123:projects:123:locations:us-east1:aiplatform:reasoningEngines:456

Set on
  • create_agent {gen_ai.agent.name} CLIENT: gen_ai.create_agent.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (conditionally required)

Official definition

gen_ai.agent.name

stringDevelopment

Human-readable name of the GenAI agent provided by the application.

Examples Math Tutor, Fiction Writer

Set on
  • create_agent {gen_ai.agent.name} CLIENT: gen_ai.create_agent.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (conditionally required)
  • execute_tool {gen_ai.tool.name} INTERNAL: gen_ai.execute_tool.internal (conditionally required)
  • plan {gen_ai.agent.name} INTERNAL: gen_ai.plan.internal (conditionally required)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} INTERNAL: gen_ai.execute_tool.load_skill.internal (conditionally required)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (conditionally required)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (conditionally required)

Official definition

gen_ai.agent.version

stringDevelopment

The version of the GenAI agent.

Examples 1.0.0, 2025-05-01

Set on
  • create_agent {gen_ai.agent.name} CLIENT: gen_ai.create_agent.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (conditionally required)

Official definition

gen_ai.conversation.compacted

booleanDevelopment

Indicates whether the effective conversation context used for this operation is a compacted view of a prior conversation.

Examples true

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)

Official definition

gen_ai.conversation.id

stringDevelopment

The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation.

Examples conv_5j66UpCpwteGg4YSxUnt7lPY

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (conditionally required), openai.gen_ai.client.inference (conditionally required), azure.ai.gen_ai.client.inference (conditionally required), anthropic.gen_ai.client.inference (conditionally required), aws.bedrock.gen_ai.client.inference (conditionally required)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (conditionally required)
  • execute_tool {gen_ai.tool.name} INTERNAL: gen_ai.execute_tool.internal (conditionally required)
  • invoke_workflow {gen_ai.workflow.name} INTERNAL: gen_ai.invoke_workflow.internal (conditionally required)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} INTERNAL: gen_ai.execute_tool.load_skill.internal (conditionally required)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (conditionally required)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (conditionally required)

Official definition

gen_ai.data_source.id

stringDevelopment

The data source identifier.

Examples H7STPQYOND

Set on
  • {gen_ai.operation.name} {gen_ai.data_source.id} CLIENT: gen_ai.retrieval.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (conditionally required)

Official definition

gen_ai.evaluation.explanation

stringDevelopment

A free-form explanation for the assigned score provided by the evaluator.

Examples The response is factually accurate but lacks sufficient detail to fully address the question.

Official definition

gen_ai.input.messages

anyDevelopment

The chat history provided to the model as an input.

Examples [ { "role": "user", "parts": [ { "type": "text", "content": "Weather in Paris?" } ] }, { "role": "assistant", "parts": [ { "type": "tool_call", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "name": "get_weather", "arguments": { "location": "Paris" } } ] }, { "role": "tool", "parts": [ { "type": "tool_call_response", "id": "call_VSPygqKTWdrhaFErNvMV18Yl", "response": "rainy, 57°F" } ] } ]

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (opt-in), openai.gen_ai.client.inference (opt-in), azure.ai.gen_ai.client.inference (opt-in), anthropic.gen_ai.client.inference (opt-in), aws.bedrock.gen_ai.client.inference (opt-in)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (opt-in)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (opt-in)
  • invoke_workflow {gen_ai.workflow.name} INTERNAL: gen_ai.invoke_workflow.internal (opt-in)

Official definition

gen_ai.main_agent.id

stringDevelopment

The unique and stable identifier of the top-level Generative AI agent in the process

Examples asst_5j66UpCpwteGg4YSxUnt7lPY, arn:aws:bedrock:us-east-1:123:agent/42, urn:agent:projects-123:projects:123:locations:us-east1:aiplatform:reasoningEngines:456

Official definition

gen_ai.memory.query.text

stringDevelopment

The search query used to retrieve memories.

Examples user dietary preferences, past flight bookings

Set on
  • {gen_ai.operation.name} CLIENT: gen_ai.memory.client (opt-in)

Official definition

gen_ai.memory.record.id

stringDevelopment

The unique identifier of the memory record.

Examples mem_5j66UpCpwteGg4YSxUnt7lPY

Set on
  • {gen_ai.operation.name} CLIENT: gen_ai.memory.client (conditionally required)

Official definition

gen_ai.memory.records

anyDevelopment

The memory records stored or retrieved in a memory operation.

Examples [ { "content": "User prefers dark mode", "id": "mem_123", "score": 0.95 }, { "content": { "preference": "vegetarian meals", "confidence": 0.9 }, "metadata": { "source": "profile" } } ]

Set on
  • {gen_ai.operation.name} CLIENT: gen_ai.memory.client (opt-in)

Official definition

gen_ai.memory.store.id

stringDevelopment

The unique identifier of the memory store.

Examples ms_abc123, user-preferences-store

Set on
  • {gen_ai.operation.name} CLIENT: gen_ai.memory.client (conditionally required)

Official definition

gen_ai.operation.name

stringDevelopment

The name of the operation being performed.

Values chat, generate_content, text_completion, embeddings, retrieval, fetch_response, create_agent, invoke_agent, execute_tool, invoke_workflow, plan, search_memory, create_memory, update_memory, upsert_memory, delete_memory, create_memory_store, delete_memory_store

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (required), gen_ai.embeddings.client (required), openai.gen_ai.client.inference (required), azure.ai.gen_ai.client.inference (required), anthropic.gen_ai.client.inference (required), aws.bedrock.gen_ai.client.inference (required)
  • {gen_ai.operation.name} {gen_ai.data_source.id} CLIENT: gen_ai.retrieval.client (required)
  • {gen_ai.operation.name} CLIENT: gen_ai.fetch_response.client (required), gen_ai.memory.client (required), openai.fetch_response.client (required)
  • create_agent {gen_ai.agent.name} CLIENT: gen_ai.create_agent.client (required)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (required)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (required)
  • execute_tool {gen_ai.tool.name} INTERNAL: gen_ai.execute_tool.internal (required)
  • invoke_workflow {gen_ai.workflow.name} INTERNAL: gen_ai.invoke_workflow.internal (required)
  • plan {gen_ai.agent.name} INTERNAL: gen_ai.plan.internal (required)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} INTERNAL: gen_ai.execute_tool.load_skill.internal (required)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (required)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (required)
  • {mcp.method.name} CLIENT: mcp.client (recommended)
  • {mcp.method.name} SERVER: mcp.server (recommended)

Official definition

gen_ai.output.messages

anyDevelopment

Messages returned by the model where each message represents a specific model response (choice, candidate).

Examples [ { "role": "assistant", "parts": [ { "type": "text", "content": "The weather in Paris is currently rainy with a temperature of 57°F." } ] } ]

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (opt-in), openai.gen_ai.client.inference (opt-in), azure.ai.gen_ai.client.inference (opt-in), anthropic.gen_ai.client.inference (opt-in), aws.bedrock.gen_ai.client.inference (opt-in)
  • {gen_ai.operation.name} CLIENT: gen_ai.fetch_response.client (opt-in), openai.fetch_response.client (opt-in)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (opt-in)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (opt-in)
  • invoke_workflow {gen_ai.workflow.name} INTERNAL: gen_ai.invoke_workflow.internal (opt-in)

Official definition

gen_ai.output.type

stringDevelopment

Represents the content type requested by the client.

Values text, json, image, speech

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (conditionally required), openai.gen_ai.client.inference (conditionally required), azure.ai.gen_ai.client.inference (conditionally required), anthropic.gen_ai.client.inference (conditionally required), aws.bedrock.gen_ai.client.inference (conditionally required)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (conditionally required)

Official definition

gen_ai.prompt.name

stringDevelopment

The name of the prompt that uniquely identifies it.

Examples analyze-code

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (conditionally required), openai.gen_ai.client.inference (conditionally required), azure.ai.gen_ai.client.inference (conditionally required), anthropic.gen_ai.client.inference (conditionally required), aws.bedrock.gen_ai.client.inference (conditionally required)
  • {mcp.method.name} CLIENT: mcp.client (conditionally required)
  • {mcp.method.name} SERVER: mcp.server (conditionally required)

Official definition

gen_ai.prompt.variable.<key>

stringDevelopment

The variables supplied to the prompt template, the <key> being the variable name, the value being the variable value.

Examples Alice, French

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (opt-in), openai.gen_ai.client.inference (opt-in), azure.ai.gen_ai.client.inference (opt-in), anthropic.gen_ai.client.inference (opt-in), aws.bedrock.gen_ai.client.inference (opt-in)
  • {mcp.method.name} CLIENT: mcp.client (opt-in)
  • {mcp.method.name} SERVER: mcp.server (opt-in)

Official definition

gen_ai.prompt.version

stringDevelopment

The version of the prompt template used.

Examples 1.0.0, 2025-05-01, prod

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (conditionally required), openai.gen_ai.client.inference (conditionally required), azure.ai.gen_ai.client.inference (conditionally required), anthropic.gen_ai.client.inference (conditionally required), aws.bedrock.gen_ai.client.inference (conditionally required)

Official definition

gen_ai.provider.name

stringDevelopment

The Generative AI provider as identified by the client or server instrumentation.

Values openai, gcp.gen_ai, gcp.vertex_ai, gcp.gemini, anthropic, cohere, azure.ai.inference, azure.ai.openai, ibm.watsonx.ai, aws.bedrock, perplexity, x_ai, deepseek, groq, mistral, moonshot_ai

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (required), gen_ai.embeddings.client (required), openai.gen_ai.client.inference (required), azure.ai.gen_ai.client.inference (required), anthropic.gen_ai.client.inference (required), aws.bedrock.gen_ai.client.inference (required)
  • {gen_ai.operation.name} {gen_ai.data_source.id} CLIENT: gen_ai.retrieval.client (conditionally required)
  • {gen_ai.operation.name} CLIENT: gen_ai.fetch_response.client (required), gen_ai.memory.client (conditionally required), openai.fetch_response.client (required)
  • create_agent {gen_ai.agent.name} CLIENT: gen_ai.create_agent.client (required)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (required)

Official definition

gen_ai.request.choice.count

intDevelopment

The target number of candidate completions to return.

Examples 3

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (conditionally required), openai.gen_ai.client.inference (conditionally required), azure.ai.gen_ai.client.inference (conditionally required), anthropic.gen_ai.client.inference (conditionally required), aws.bedrock.gen_ai.client.inference (conditionally required)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (conditionally required)

Official definition

gen_ai.request.encoding_formats

string[]Development

The encoding formats requested in an embeddings operation, if specified.

Examples ["base64"], ["float","binary"]

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.embeddings.client (recommended)

Official definition

gen_ai.request.frequency_penalty

doubleDevelopment

The frequency penalty setting for the GenAI request.

Examples 0.1

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (recommended)

Official definition

gen_ai.request.max_tokens

intDevelopment

The maximum number of tokens the model generates for a request.

Examples 100

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (recommended)

Official definition

gen_ai.request.model

stringDevelopment

The name of the GenAI model a request is being made to.

Examples gpt-4

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (conditionally required), gen_ai.embeddings.client (conditionally required), openai.gen_ai.client.inference (required), azure.ai.gen_ai.client.inference (conditionally required), anthropic.gen_ai.client.inference (conditionally required), aws.bedrock.gen_ai.client.inference (conditionally required)
  • {gen_ai.operation.name} {gen_ai.data_source.id} CLIENT: gen_ai.retrieval.client (conditionally required)
  • create_agent {gen_ai.agent.name} CLIENT: gen_ai.create_agent.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (recommended)

Official definition

gen_ai.request.presence_penalty

doubleDevelopment

The presence penalty setting for the GenAI request.

Examples 0.1

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (recommended)

Official definition

gen_ai.request.previous_response.id

stringDevelopment

The unique identifier of a previous response or interaction used to provide context for the current operation.

Examples resp_0123456789aBCdef, interaction-123

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)

Official definition

gen_ai.request.reasoning.level

stringDevelopment

The reasoning or thinking effort level requested for a GenAI model.

Examples low, medium, high

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)

Official definition

gen_ai.request.seed

intDevelopment

Requests with same seed value more likely to return same result.

Examples 100

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (conditionally required), openai.gen_ai.client.inference (conditionally required), azure.ai.gen_ai.client.inference (conditionally required), anthropic.gen_ai.client.inference (conditionally required), aws.bedrock.gen_ai.client.inference (conditionally required)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (conditionally required)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (conditionally required)

Official definition

gen_ai.request.stop_sequences

string[]Development

List of sequences that the model will use to stop generating further tokens.

Examples ["forest","lived"]

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (recommended)

Official definition

gen_ai.request.stream

booleanDevelopment

Indicates whether the GenAI request was made in streaming mode.

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (conditionally required), openai.gen_ai.client.inference (conditionally required), azure.ai.gen_ai.client.inference (conditionally required), anthropic.gen_ai.client.inference (conditionally required), aws.bedrock.gen_ai.client.inference (conditionally required)

Official definition

gen_ai.request.stream_cursor

stringDevelopment

The cursor identifying the last streamed event already received, used to resume a streamed response from that position.

Examples 42, event-abc123

Set on
  • {gen_ai.operation.name} CLIENT: gen_ai.fetch_response.client (conditionally required), openai.fetch_response.client (conditionally required)

Official definition

gen_ai.request.temperature

doubleDevelopment

The temperature setting for the GenAI request.

Examples 0

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (recommended)

Official definition

gen_ai.request.top_k

intDevelopment

The top-K sampling setting for the GenAI request: restricts token generation at each step to the K most likely next tokens.

Examples 40

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (conditionally required), openai.gen_ai.client.inference (conditionally required), azure.ai.gen_ai.client.inference (conditionally required), anthropic.gen_ai.client.inference (conditionally required), aws.bedrock.gen_ai.client.inference (conditionally required)

Official definition

gen_ai.request.top_p

doubleDevelopment

The top_p sampling setting for the GenAI request.

Examples 1

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (recommended)

Official definition

gen_ai.response.finish_reasons

string[]Development

Array of reasons the model stopped generating tokens, corresponding to each generation received.

Examples ["stop"], ["stop","length"], ["stop","length","error"]

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • {gen_ai.operation.name} CLIENT: gen_ai.fetch_response.client (recommended), openai.fetch_response.client (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (recommended)

Official definition

gen_ai.response.id

stringDevelopment

The unique identifier for the completion.

Examples chatcmpl-123

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • {gen_ai.operation.name} CLIENT: gen_ai.fetch_response.client (required), openai.fetch_response.client (required)

Official definition

gen_ai.response.model

stringDevelopment

The name of the model that generated the response.

Examples gpt-4-0613

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), gen_ai.embeddings.client (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • {gen_ai.operation.name} CLIENT: gen_ai.fetch_response.client (recommended), openai.fetch_response.client (recommended)

Official definition

gen_ai.response.status

stringDevelopment

The lifecycle status of a generated response, as reported by the provider when the response is fetched or polled.

Values queued, in_progress, completed, incomplete, failed, cancelled

Set on
  • {gen_ai.operation.name} CLIENT: gen_ai.fetch_response.client (recommended), openai.fetch_response.client (recommended)

Official definition

gen_ai.response.time_to_first_chunk

doubleDevelopment

Time to first chunk in a streaming response, measured from request issuance, in seconds. The value is measured from when the client issues the generation request to when the first chunk is received in the response stream.

Examples 0.5, 1.2

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)

Official definition

gen_ai.retrieval.documents

anyDevelopment

The documents retrieved.

Examples [ { "id": "doc_123", "score": 0.95 }, { "id": "doc_456", "score": 0.87 }, { "id": "doc_789", "score": 0.82 } ]

Set on
  • {gen_ai.operation.name} {gen_ai.data_source.id} CLIENT: gen_ai.retrieval.client (opt-in)

Official definition

gen_ai.retrieval.query.text

stringDevelopment

The query text used for retrieval.

Examples What is the capital of France?, weather in Paris

Set on
  • {gen_ai.operation.name} {gen_ai.data_source.id} CLIENT: gen_ai.retrieval.client (opt-in)

Official definition

gen_ai.retrieval.top_k

intDevelopment

The maximum number of documents the retriever was asked to return for the query (also known as k, limit, or max_num_results).

Examples 5

Set on
  • {gen_ai.operation.name} {gen_ai.data_source.id} CLIENT: gen_ai.retrieval.client (recommended)

Official definition

gen_ai.skill.description

stringDevelopment

The description of the Agent Skill.

Examples Review a changelist against the team's review policy.

Set on
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} INTERNAL: gen_ai.execute_tool.load_skill.internal (recommended)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (recommended)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (recommended)

Official definition

gen_ai.skill.name

stringDevelopment

The name of the Agent Skill.

Examples code-review, pdf-processing

Set on
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} INTERNAL: gen_ai.execute_tool.load_skill.internal (conditionally required)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (conditionally required)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (conditionally required)

Official definition

gen_ai.skill.resource.name

stringDevelopment

The skill-relative name of the resource (script, reference, or asset) being accessed or executed.

Examples references/review_policy.md, assets/report_template.html

Set on
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (conditionally required)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (conditionally required)

Official definition

gen_ai.skill.source.uri

stringDevelopment

The source URI for loading the skill.

Examples https://skills.example.com/code-review, gs://example-skills/code-review, file:///opt/skills/code-review

Set on
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} INTERNAL: gen_ai.execute_tool.load_skill.internal (recommended)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (recommended)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (recommended)

Official definition

gen_ai.system_instructions

anyDevelopment

The system message or instructions provided to the GenAI model separately from the chat history.

Examples [ { "type": "text", "content": "You are an Agent that greet users, always use greetings tool to respond" } ] , [ { "type": "text", "content": "You are a language translator." }, { "type": "text", "content": "Your mission is to translate text in English to French." } ]

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (opt-in), openai.gen_ai.client.inference (opt-in), azure.ai.gen_ai.client.inference (opt-in), anthropic.gen_ai.client.inference (opt-in), aws.bedrock.gen_ai.client.inference (opt-in)
  • {gen_ai.operation.name} CLIENT: gen_ai.fetch_response.client (opt-in), openai.fetch_response.client (opt-in)
  • create_agent {gen_ai.agent.name} CLIENT: gen_ai.create_agent.client (opt-in)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (opt-in)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (opt-in)

Official definition

gen_ai.tool.call.arguments

anyDevelopment

Parameters passed to the tool call.

Examples { "location": "San Francisco?", "date": "2025-10-01" }

Set on
  • execute_tool {gen_ai.tool.name} INTERNAL: gen_ai.execute_tool.internal (opt-in)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} INTERNAL: gen_ai.execute_tool.load_skill.internal (opt-in)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (opt-in)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (opt-in)
  • {mcp.method.name} CLIENT: mcp.client (opt-in)
  • {mcp.method.name} SERVER: mcp.server (opt-in)

Official definition

gen_ai.tool.call.id

stringDevelopment

The tool call identifier supplied by the model or provider.

Examples call_mszuSIzqtI65i1wAUOE8w5H4

Set on
  • execute_tool {gen_ai.tool.name} INTERNAL: gen_ai.execute_tool.internal (conditionally required)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} INTERNAL: gen_ai.execute_tool.load_skill.internal (conditionally required)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (conditionally required)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (conditionally required)

Official definition

gen_ai.tool.call.result

anyDevelopment

The result returned by the tool call (if any and if execution was successful).

Examples { "temperature_range": { "high": 75, "low": 60 }, "conditions": "sunny" }

Set on
  • execute_tool {gen_ai.tool.name} INTERNAL: gen_ai.execute_tool.internal (opt-in)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} INTERNAL: gen_ai.execute_tool.load_skill.internal (opt-in)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (opt-in)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (opt-in)
  • {mcp.method.name} CLIENT: mcp.client (opt-in)
  • {mcp.method.name} SERVER: mcp.server (opt-in)

Official definition

gen_ai.tool.definitions

anyDevelopment

The list of tool definitions available to the GenAI agent or model.

Examples [ { "type": "function", "name": "get_current_weather", "description": "Get the current weather in a given location", "parameters": { "type": "object", "properties": { "location": { "type": "string", "description": "The city and state, e.g. San Francisco, CA" }, "unit": { "type": "string", "enum": [ "celsius", "fahrenheit" ] } }, "required": [ "location", "unit" ] } } ]

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (opt-in), openai.gen_ai.client.inference (opt-in), azure.ai.gen_ai.client.inference (opt-in), anthropic.gen_ai.client.inference (opt-in), aws.bedrock.gen_ai.client.inference (opt-in)
  • {gen_ai.operation.name} CLIENT: gen_ai.fetch_response.client (opt-in), openai.fetch_response.client (opt-in)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (opt-in)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (opt-in)

Official definition

gen_ai.tool.description

stringDevelopment

The tool description.

Examples Multiply two numbers

Set on
  • execute_tool {gen_ai.tool.name} INTERNAL: gen_ai.execute_tool.internal (recommended)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} INTERNAL: gen_ai.execute_tool.load_skill.internal (recommended)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (recommended)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (recommended)

Official definition

gen_ai.tool.name

stringDevelopment

Name of the tool utilized by the agent.

Examples Flights

Set on
  • execute_tool {gen_ai.tool.name} INTERNAL: gen_ai.execute_tool.internal (required)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} INTERNAL: gen_ai.execute_tool.load_skill.internal (required)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (required)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (required)
  • {mcp.method.name} CLIENT: mcp.client (conditionally required)
  • {mcp.method.name} SERVER: mcp.server (conditionally required)

Official definition

gen_ai.tool.type

stringDevelopment

Type of the tool utilized by the agent

Examples function, extension, datastore

Set on
  • execute_tool {gen_ai.tool.name} INTERNAL: gen_ai.execute_tool.internal (recommended)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} INTERNAL: gen_ai.execute_tool.load_skill.internal (recommended)
  • execute_tool {gen_ai.tool.name} {gen_ai.skill.name} {gen_ai.skill.resource.name} INTERNAL: gen_ai.execute_tool.read_skill_resource.internal (recommended)
  • gen_ai.execute_tool.command.internal INTERNAL: gen_ai.execute_tool.command.internal (recommended)

Official definition

gen_ai.usage.audio.cache_read.input_tokens

intDevelopment

The number of audio input tokens served from a provider-managed cache.

Examples 60

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)

Official definition

gen_ai.usage.audio.input_tokens

intDevelopment

The number of audio input tokens.

Examples 120

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)

Official definition

gen_ai.usage.audio.output_tokens

intDevelopment

The number of audio output tokens.

Examples 240

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)

Official definition

gen_ai.usage.cache_read.input_tokens

intDevelopment

The number of input tokens served from a provider-managed cache.

Examples 50

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)

Official definition

gen_ai.usage.cache_write.input_tokens

intDevelopment

The number of input tokens written to a provider-managed cache.

Examples 25

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)

Official definition

gen_ai.usage.image.cache_read.input_tokens

intDevelopment

The number of image input tokens served from a provider-managed cache.

Examples 128

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)

Official definition

gen_ai.usage.image.input_tokens

intDevelopment

The number of image input tokens.

Examples 258

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)

Official definition

gen_ai.usage.image.output_tokens

intDevelopment

The number of image output tokens.

Examples 1290

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)

Official definition

gen_ai.usage.input_tokens

intDevelopment

The number of tokens used in the GenAI input (prompt).

Examples 100

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), gen_ai.embeddings.client (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (recommended)

Official definition

gen_ai.usage.output_tokens

intDevelopment

The number of tokens used in the GenAI response (completion).

Examples 180

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)
  • invoke_agent {gen_ai.agent.name} INTERNAL: gen_ai.invoke_agent.internal (recommended)

Official definition

gen_ai.usage.reasoning.output_tokens

intDevelopment

The number of output tokens used for reasoning (e.g. chain-of-thought, extended thinking).

Examples 50

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)

Official definition

gen_ai.usage.text.cache_read.input_tokens

intDevelopment

The number of text input tokens served from a provider-managed cache.

Examples 40

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)

Official definition

gen_ai.usage.text.input_tokens

intDevelopment

The number of text input tokens.

Examples 100

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)

Official definition

gen_ai.usage.text.output_tokens

intDevelopment

The number of text output tokens.

Examples 180

Set on
  • {gen_ai.operation.name} {gen_ai.request.model} CLIENT: gen_ai.client.inference (recommended), openai.gen_ai.client.inference (recommended), azure.ai.gen_ai.client.inference (recommended), anthropic.gen_ai.client.inference (recommended), aws.bedrock.gen_ai.client.inference (recommended)
  • invoke_agent {gen_ai.agent.name} CLIENT: gen_ai.invoke_agent.client (recommended)

Official definition

gen_ai.workflow.name

stringDevelopment

Human-readable name of the GenAI workflow provided by the application.

Examples multi_agent_rag, customer_support_pipeline

Set on
  • invoke_workflow {gen_ai.workflow.name} INTERNAL: gen_ai.invoke_workflow.internal (conditionally required)

Official definition

All 4 mcp.* attributes

mcp.method.name

stringDevelopment

The name of the request or notification method.

Values notifications/cancelled, initialize, notifications/initialized, notifications/progress, ping, resources/list, resources/templates/list, resources/read, notifications/resources/list_changed, resources/subscribe, resources/unsubscribe, notifications/resources/updated, prompts/list, prompts/get, notifications/prompts/list_changed, tools/list, tools/call, notifications/tools/list_changed, logging/setLevel, notifications/message, sampling/createMessage, completion/complete, roots/list, notifications/roots/list_changed, and 1 more

Set on
  • {mcp.method.name} CLIENT: mcp.client (required)
  • {mcp.method.name} SERVER: mcp.server (required)

Official definition

mcp.protocol.version

stringDevelopment

The version of the Model Context Protocol used.

Examples 2025-06-18

Set on
  • {mcp.method.name} CLIENT: mcp.client (recommended)
  • {mcp.method.name} SERVER: mcp.server (recommended)

Official definition

mcp.resource.uri

stringDevelopment

The value of the resource uri.

Examples postgres://database/customers/schema, file:///home/user/documents/report.pdf

Set on
  • {mcp.method.name} CLIENT: mcp.client (conditionally required)
  • {mcp.method.name} SERVER: mcp.server (conditionally required)

Official definition

mcp.session.id

stringDevelopment

Identifies MCP session.

Examples 191c4850af6c49e08843a3f6c80e5046

Set on
  • {mcp.method.name} CLIENT: mcp.client (recommended)
  • {mcp.method.name} SERVER: mcp.server (recommended)

Official definition

Which names were renamed or removed?

Deprecated names you may still see in older traces, each with what replaced it.

gen_ai.system

stringDeprecated

Replaced by gen_ai.provider.name.

Values openai, gcp.gen_ai, gcp.vertex_ai, gcp.gemini, vertex_ai, gemini, anthropic, cohere, az.ai.inference, az.ai.openai, azure.ai.inference, azure.ai.openai, ibm.watsonx.ai, aws.bedrock, perplexity, xai, deepseek, groq, mistral_ai

Official definition

FAQ

Are the gen_ai attributes stable?

No. Every gen_ai.* and mcp.* attribute is Development, so names can still be renamed or removed. Pin the version of the instrumentation you use, and check renames before you upgrade.

Where are the GenAI semantic conventions defined now?

In the open-telemetry/semantic-conventions-genai repository, which also holds the MCP conventions. The main semantic-conventions repository keeps only deprecated entries that point there.

Why does opentelemetry.io mark gen_ai.agent.id as deprecated?

The registry there is built from the main repository, where every gen_ai.* name is marked deprecated with the note "Moved to the GenAI repository". The name gen_ai.agent.id itself did not change.

Attribute names, types, stability and descriptions are from the OpenTelemetry semantic conventions (open-telemetry/semantic-conventions-genai), © OpenTelemetry Authors, Apache-2.0. Each attribute links to its official definition, which wins where the two differ.

Something wrong or out of date? Report a problem with this page.

Type to search the docs, Learn topics and the blog.