# Gen AI **Attributes:** | Key | Stability | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | | `gen_ai.agent.description` |  | string | Free-form description of the GenAI agent provided by the application. | `Helps with math problems`; `Generates fiction stories` | | `gen_ai.agent.id` |  | string | The unique and stable identifier of the GenAI hosted agent resource. [1] | `asst_5j66UpCpwteGg4YSxUnt7lPY`; `arn:aws:bedrock:us-east-1:123:agent/42`; `urn:agent:projects-123:projects:123:locations:us-east1:aiplatform:reasoningEngines:456` | | `gen_ai.agent.name` |  | string | Human-readable name of the GenAI agent provided by the application. | `Math Tutor`; `Fiction Writer` | | `gen_ai.agent.version` |  | string | The version of the GenAI agent. | `1.0.0`; `2025-05-01` | | `gen_ai.conversation.compacted` |  | boolean | Indicates whether the effective conversation context used for this operation is a compacted view of a prior conversation. [2] | `true` | | `gen_ai.conversation.id` |  | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [3] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | | `gen_ai.data_source.id` |  | string | The data source identifier. [4] | `H7STPQYOND` | | `gen_ai.embeddings.dimension.count` |  | int | The number of dimensions the resulting output embeddings should have. | `512`; `1024` | | `gen_ai.evaluation.explanation` |  | string | A free-form explanation for the assigned score provided by the evaluator. | `The response is factually accurate but lacks sufficient detail to fully address the question.` | | `gen_ai.evaluation.name` |  | string | The name of the evaluation metric used for the GenAI response. | `Relevance`; `IntentResolution` | | `gen_ai.evaluation.score.label` |  | string | Human readable label for evaluation. [5] | `relevant`; `not_relevant`; `correct`; `incorrect`; `pass`; `fail` | | `gen_ai.evaluation.score.value` |  | double | The evaluation score returned by the evaluator. | `4.0` | | `gen_ai.input.messages` |  | any | The chat history provided to the model as an input. [6] | [
  {
    "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"
      }
    ]
  }
] | | `gen_ai.input.messages_ref` |  | string | An absolute URI identifying the input messages in external storage. [7] | `s3://example-bucket/gen-ai/674f35f4-e3f6-41f5-b104-864b3964f6d3_inputs.json` | | `gen_ai.main_agent.description` |  | string | The free-form description of the top-level Generative AI agent in the process. [8] | `Helps with math problems`; `Generates fiction stories` | | `gen_ai.main_agent.id` |  | string | The unique and stable identifier of the top-level Generative AI agent in the process [9] | `asst_5j66UpCpwteGg4YSxUnt7lPY`; `arn:aws:bedrock:us-east-1:123:agent/42`; `urn:agent:projects-123:projects:123:locations:us-east1:aiplatform:reasoningEngines:456` | | `gen_ai.main_agent.name` |  | string | The human-readable name of the top-level Generative AI agent in the process. [10] | `Math Tutor`; `Fiction Writer` | | `gen_ai.memory.query.text` |  | string | The search query used to retrieve memories. [11] | `user dietary preferences`; `past flight bookings` | | `gen_ai.memory.record.count` |  | int | The number of memory records relevant to the operation. [12] | `3` | | `gen_ai.memory.record.id` |  | string | The unique identifier of the memory record. | `mem_5j66UpCpwteGg4YSxUnt7lPY` | | `gen_ai.memory.records` |  | any | The memory records stored or retrieved in a memory operation. [13] | [
  {
    "content": "User prefers dark mode",
    "id": "mem_123",
    "score": 0.95
  },
  {
    "content": {
      "preference": "vegetarian meals",
      "confidence": 0.9
    },
    "metadata": {
      "source": "profile"
    }
  }
] | | `gen_ai.memory.store.id` |  | string | The unique identifier of the memory store. [14] | `ms_abc123`; `user-preferences-store` | | `gen_ai.operation.name` |  | string | The name of the operation being performed. [15] | `chat`; `generate_content`; `text_completion` | | `gen_ai.output.messages` |  | any | Messages returned by the model where each message represents a specific model response (choice, candidate). [16] | [
  {
    "role": "assistant",
    "parts": [
      {
        "type": "text",
        "content": "The weather in Paris is currently rainy with a temperature of 57°F."
      }
    ]
  }
] | | `gen_ai.output.messages_ref` |  | string | An absolute URI identifying the output messages in external storage. [17] | `s3://example-bucket/gen-ai/674f35f4-e3f6-41f5-b104-864b3964f6d3_outputs.json` | | `gen_ai.output.type` |  | string | Represents the content type requested by the client. [18] | `text`; `json`; `image` | | `gen_ai.prompt.name` |  | string | The name of the prompt that uniquely identifies it. | `analyze-code` | | `gen_ai.prompt.variable` |  | string | The variables supplied to the prompt template, the `` being the variable name, the value being the variable value. [19] | `Alice`; `French` | | `gen_ai.prompt.version` |  | string | The version of the prompt template used. [20] | `1.0.0`; `2025-05-01`; `prod`; `v2` | | `gen_ai.provider.name` |  | string | The Generative AI provider as identified by the client or server instrumentation. [21] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | | `gen_ai.request.choice.count` |  | int | The target number of candidate completions to return. | `3` | | `gen_ai.request.encoding_formats` |  | string[] | The encoding formats requested in an embeddings operation, if specified. [22] | `["base64"]`; `["float", "binary"]` | | `gen_ai.request.frequency_penalty` |  | double | The frequency penalty setting for the GenAI request. | `0.1` | | `gen_ai.request.max_tokens` |  | int | The maximum number of tokens the model generates for a request. | `100` | | `gen_ai.request.model` |  | string | The name of the GenAI model a request is being made to. | `gpt-4` | | `gen_ai.request.presence_penalty` |  | double | The presence penalty setting for the GenAI request. | `0.1` | | `gen_ai.request.previous_response.id` |  | string | The unique identifier of a previous response or interaction used to provide context for the current operation. [23] | `resp_0123456789aBCdef`; `interaction-123` | | `gen_ai.request.reasoning.level` |  | string | The reasoning or thinking effort level requested for a GenAI model. [24] | `low`; `medium`; `high` | | `gen_ai.request.seed` |  | int | Requests with same seed value more likely to return same result. | `100` | | `gen_ai.request.stop_sequences` |  | string[] | List of sequences that the model will use to stop generating further tokens. | `["forest", "lived"]` | | `gen_ai.request.stream` |  | boolean | Indicates whether the GenAI request was made in streaming mode. | | | `gen_ai.request.stream_cursor` |  | string | The cursor identifying the last streamed event already received, used to resume a streamed response from that position. [25] | `42`; `event-abc123` | | `gen_ai.request.temperature` |  | double | The temperature setting for the GenAI request. | `0.0` | | `gen_ai.request.top_k` |  | int | The top-K sampling setting for the GenAI request: restricts token generation at each step to the K most likely next tokens. [26] | `40` | | `gen_ai.request.top_p` |  | double | The top_p sampling setting for the GenAI request. | `1.0` | | `gen_ai.response.finish_reasons` |  | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. [27] | `["stop"]`; `["stop", "length"]`; `["stop", "length", "error"]` | | `gen_ai.response.id` |  | string | The unique identifier for the completion. | `chatcmpl-123` | | `gen_ai.response.model` |  | string | The name of the model that generated the response. | `gpt-4-0613` | | `gen_ai.response.status` |  | string | The lifecycle status of a generated response, as reported by the provider when the response is fetched or polled. [28] | `completed`; `in_progress` | | `gen_ai.response.time_to_first_chunk` |  | double | 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. | `0.5`; `1.2` | | `gen_ai.retrieval.documents` |  | any | The documents retrieved. [29] | [
  {
    "id": "doc_123",
    "score": 0.95
  },
  {
    "id": "doc_456",
    "score": 0.87
  },
  {
    "id": "doc_789",
    "score": 0.82
  }
] | | `gen_ai.retrieval.query.text` |  | string | The query text used for retrieval. [30] | `What is the capital of France?`; `weather in Paris` | | `gen_ai.retrieval.top_k` |  | int | The maximum number of documents the retriever was asked to return for the query (also known as `k`, `limit`, or `max_num_results`). | `5` | | `gen_ai.skill.description` |  | string | The [description of the Agent Skill](https://agentskills.io/specification#skill-md-format). [31] | `Review a changelist against the team's review policy.` | | `gen_ai.skill.name` |  | string | The name of the [Agent Skill](https://agentskills.io/specification#skill-md-format). | `code-review`; `pdf-processing` | | `gen_ai.skill.resource.name` |  | string | The skill-relative name of the resource (script, reference, or asset) being accessed or executed. | `references/review_policy.md`; `assets/report_template.html` | | `gen_ai.skill.source.uri` |  | string | The source URI for loading the skill. [32] | `https://skills.example.com/code-review`; `gs://example-skills/code-review`; `file:///opt/skills/code-review` | | `gen_ai.system_instructions` |  | any | The system message or instructions provided to the GenAI model separately from the chat history. [33] | [
  {
    "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."
  }
] | | `gen_ai.system_instructions_ref` |  | string | An absolute URI identifying the system instructions in external storage. [34] | `s3://example-bucket/gen-ai/e68562472088cf0fec6124d5268608b01b1e248afb408e748738d39c6352d169_system_instruction.json` | | `gen_ai.token.modality` |  | string | The modality of the tokens being counted. [35] | `text`; `image`; `audio` | | `gen_ai.tool.call.arguments` |  | any | Parameters passed to the tool call. [36] | {
    "location": "San Francisco?",
    "date": "2025-10-01"
} | | `gen_ai.tool.call.id` |  | string | The tool call identifier supplied by the model or provider. [37] | `call_mszuSIzqtI65i1wAUOE8w5H4` | | `gen_ai.tool.call.result` |  | any | The result returned by the tool call (if any and if execution was successful). [38] | {
  "temperature_range": {
    "high": 75,
    "low": 60
  },
  "conditions": "sunny"
} | | `gen_ai.tool.definitions` |  | any | The list of tool definitions available to the GenAI agent or model. [39] | [
  {
    "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"
      ]
    }
  }
] | | `gen_ai.tool.definitions_ref` |  | string | An absolute URI identifying the tool definitions in external storage. [40] | `s3://example-bucket/gen-ai/b61c3b21581c79d687c07f31970d1a9482dca47756ccf014d408fd6cd091ef66_tool.definitions.json` | | `gen_ai.tool.description` |  | string | The tool description. [41] | `Multiply two numbers` | | `gen_ai.tool.name` |  | string | Name of the tool utilized by the agent. | `Flights` | | `gen_ai.tool.type` |  | string | Type of the tool utilized by the agent [42] | `function`; `extension`; `datastore` | | `gen_ai.transfer.mode` |  | string | Describes how control passes to the transfer target. | `return_to_caller`; `pass_control` | | `gen_ai.transfer.target.name` |  | string | The human-readable name of the agent targeted by the transfer. | `weather_agent` | | `gen_ai.usage.audio.cache_read.input_tokens` |  | int | The number of audio input tokens served from a provider-managed cache. [43] | `60` | | `gen_ai.usage.audio.input_tokens` |  | int | The number of audio input tokens. [44] | `120` | | `gen_ai.usage.audio.output_tokens` |  | int | The number of audio output tokens. [45] | `240` | | `gen_ai.usage.cache_read.input_tokens` |  | int | The number of input tokens served from a provider-managed cache. [46] | `50` | | `gen_ai.usage.cache_write.input_tokens` |  | int | The number of input tokens written to a provider-managed cache. [47] | `25` | | `gen_ai.usage.image.cache_read.input_tokens` |  | int | The number of image input tokens served from a provider-managed cache. [48] | `128` | | `gen_ai.usage.image.input_tokens` |  | int | The number of image input tokens. [49] | `258` | | `gen_ai.usage.image.output_tokens` |  | int | The number of image output tokens. [50] | `1290` | | `gen_ai.usage.input_tokens` |  | int | The number of tokens used in the GenAI input (prompt). [51] | `100` | | `gen_ai.usage.output_tokens` |  | int | The number of tokens used in the GenAI response (completion). [52] | `180` | | `gen_ai.usage.reasoning.output_tokens` |  | int | The number of output tokens used for reasoning (e.g. chain-of-thought, extended thinking). [53] | `50` | | `gen_ai.usage.text.cache_read.input_tokens` |  | int | The number of text input tokens served from a provider-managed cache. [54] | `40` | | `gen_ai.usage.text.input_tokens` |  | int | The number of text input tokens. [55] | `100` | | `gen_ai.usage.text.output_tokens` |  | int | The number of text output tokens. [56] | `180` | | `gen_ai.workflow.name` |  | string | Human-readable name of the GenAI workflow provided by the application. [57] | `multi_agent_rag`; `customer_support_pipeline` | **[1] `gen_ai.agent.id`:** For hosted agents, this SHOULD be the provider-assigned stable identifier of the agent resource such as [AWS Bedrock agent ARN](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) or [GCP Agent Registry identifier](https://docs.cloud.google.com/agent-registry/concepts#agent-identifier). It's NOT RECOMMENDED to record in-memory agent instance ids on this attribute due to their transient nature. **[2] `gen_ai.conversation.compacted`:** This attribute is a positive indicator of context compaction. Instrumentations SHOULD set it to `true` only when they can reliably determine that context compaction was applied. Instrumentations SHOULD NOT set it to `false`; they SHOULD leave it unset otherwise. **[3] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have an identifier for the conversation readily available for a given operation, for example: - when the client framework being instrumented manages conversation history (see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/), [LangChain `session_id`](https://reference.langchain.com/python/langchain-core/runnables/history/RunnableWithMessageHistory), and [Google ADK sessions](https://adk.dev/sessions/session)) - when instrumenting GenAI client libraries that maintain a conversation on the backend (see [AWS Bedrock agent sessions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-session-state.html), [OpenAI Assistant threads](https://platform.openai.com/docs/api-reference/threads)) When no identifier for the conversation is available, instrumentations SHOULD NOT populate conversation id. For example, a new UUID, a trace identifier, or a hash of request content SHOULD NOT be used as a fallback value. Application developers that manage conversation history MAY add conversation id to GenAI and other spans or logs using custom span or log record processors or hooks provided by instrumentation libraries. **[4] `gen_ai.data_source.id`:** Data sources are used by AI agents and RAG applications to store grounding data. A data source may be an external database, object store, document collection, website, or any other storage system used by the GenAI agent or application. The `gen_ai.data_source.id` SHOULD match the identifier used by the GenAI system rather than a name specific to the external storage, such as a database or object store. Semantic conventions referencing `gen_ai.data_source.id` MAY also leverage additional attributes, such as `db.*`, to further identify and describe the data source. **[5] `gen_ai.evaluation.score.label`:** This attribute provides a human-readable interpretation of the evaluation score produced by an evaluator. For example, a score value of 1 could mean "relevant" in one evaluation system and "not relevant" in another, depending on the scoring range and evaluator. The label SHOULD have low cardinality. Possible values depend on the evaluation metric and evaluator used; implementations SHOULD document the possible values. **[6] `gen_ai.input.messages`:** Messages MUST be provided in the order they were sent to the model. Instrumentations MAY provide a way for users to filter or truncate input messages. > [!Warning] > This attribute is likely to contain sensitive information including user/PII data. See [Recording content on attributes](/docs/gen-ai/gen-ai-spans.md#recording-content-on-attributes) section for more details. Instrumentations MUST follow [JSON schema](/model/gen-ai/gen-ai-input-messages.json). When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. **[7] `gen_ai.input.messages_ref`:** The presence of this attribute does not indicate whether storing the content succeeded or whether the content remains available. It is NOT RECOMMENDED to embed credentials, such as signed URL query parameters, in the URI. Access to the stored content SHOULD be secured by other means, for example by storage-level access control. > [!Warning] > The URI may expose sensitive storage metadata, such as storage provider, > bucket or container names, tenant or object identifiers. **[8] `gen_ai.main_agent.description`:** In Agent-to-Agent (A2A) communication, this maps to the `description` property declared in the Agent Card. **[9] `gen_ai.main_agent.id`:** For main agents, this SHOULD be the provider-assigned stable identifier of the agent resource such as [AWS Bedrock agent ARN](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_Agent.html) or [GCP Agent Registry identifier](https://docs.cloud.google.com/agent-registry/concepts#agent-identifier). Instrumentation MUST NOT generate `gen_ai.main_agent.id` from an in-memory or process-local identifier. If no stable identifier is available, the agent entity is not emitted, and instrumentation continues to report `gen_ai.agent.name` at the span level when relevant. **[10] `gen_ai.main_agent.name`:** In Agent-to-Agent (A2A) communication, this maps to the `name` property declared in the Agent Card. **[11] `gen_ai.memory.query.text`:** Instrumentations SHOULD NOT capture this attribute by default. Capture SHOULD be gated by an explicit user opt-in via [content capture configuration](/docs/gen-ai/gen-ai-spans.md#content-capture-configuration). > [!Warning] > This attribute may contain sensitive information. **[12] `gen_ai.memory.record.count`:** For `search_memory` operations, this is the number of memory records returned by the operation. For `create_memory` operations, this is the number of memory records the operation attempted to create. For `update_memory` operations, this is the number of memory records the operation attempted to modify. For `upsert_memory` operations, this is the number of memory records the operation attempted to create or update. For `delete_memory` operations, this is the number of memory records the operation attempted to delete. **[13] `gen_ai.memory.records`:** Instrumentations SHOULD NOT capture this attribute by default. Capture SHOULD be gated by an explicit user opt-in via [content capture configuration](/docs/gen-ai/gen-ai-spans.md#content-capture-configuration). > [!Warning] > This attribute may contain sensitive information including user/PII data. Instrumentations MUST follow [JSON schema](/model/gen-ai/gen-ai-memory-records.json). When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. **[14] `gen_ai.memory.store.id`:** Semantic conventions for individual components SHOULD document what `gen_ai.memory.store.id` maps to within the implementation. **[15] `gen_ai.operation.name`:** If one of the predefined values applies, but specific system uses a different name it's RECOMMENDED to document it in the semantic conventions for specific GenAI system and use system-specific name in the instrumentation. If a different name is not documented, instrumentation libraries SHOULD use applicable predefined value. **[16] `gen_ai.output.messages`:** Each message represents a single output choice/candidate generated by the model. Each message corresponds to exactly one generation (choice/candidate) and vice versa - one choice cannot be split across multiple messages or one message cannot contain parts from multiple choices. Instrumentations MAY provide a way for users to filter or truncate output messages. `gen_ai.response.finish_reasons` remains aligned with the generations returned by the provider, not with a filtered or truncated `gen_ai.output.messages` value. When an operation ends in an error, this attribute SHOULD only be set when the operation produced output, including partial streamed output. Instrumentation SHOULD NOT synthesize output content for a failed operation. > [!Warning] > This attribute is likely to contain sensitive information including user/PII data. See [Recording content on attributes](/docs/gen-ai/gen-ai-spans.md#recording-content-on-attributes) section for more details. Instrumentations MUST follow [JSON schema](/model/gen-ai/gen-ai-output-messages.json). When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. **[17] `gen_ai.output.messages_ref`:** The presence of this attribute does not indicate whether storing the content succeeded or whether the content remains available. It is NOT RECOMMENDED to embed credentials, such as signed URL query parameters, in the URI. Access to the stored content SHOULD be secured by other means, for example by storage-level access control. > [!Warning] > The URI may expose sensitive storage metadata, such as storage provider, > bucket or container names, tenant or object identifiers. **[18] `gen_ai.output.type`:** This attribute SHOULD be used when the client requests output of a specific type. The model may return zero or more outputs of this type. This attribute specifies the output modality and not the actual output format. For example, if an image is requested, the actual output could be a URL pointing to an image file. Additional output format details may be recorded in the future in the `gen_ai.output.{type}.*` attributes. **[19] `gen_ai.prompt.variable`:** Prompt templates are parameterized with variables that are filled in at runtime. This attribute records the variable values passed to the template. The attribute name defines the variable name, and the attribute value is the variable value serialized as a string. Examples: - A variable `user_name` with value `Alice` SHOULD be recorded as the `gen_ai.prompt.variable.user_name` attribute with value `"Alice"`. - A variable `language` with value `French` SHOULD be recorded as the `gen_ai.prompt.variable.language` attribute with value `"French"`. > [!Warning] > This attribute may contain sensitive information. **[20] `gen_ai.prompt.version`:** The version string can follow any versioning scheme chosen by the application (e.g., SemVer, date-based, or platform-specific tags). When a prompt management system is in use, this SHOULD match the version identifier used by that system. **[21] `gen_ai.provider.name`:** Semantic conventions for individual GenAI operations SHOULD clarify which kinds of providers (e.g. inference, embeddings, retrieval, memory, hosted agent providers) apply when it is not clear from context. The attribute SHOULD be set based on the instrumentation's best knowledge and may differ from the actual upstream provider. For example, a client SDK may be configured against a proxy or hosting platform that transparently relays requests to a different provider. The `gen_ai.provider.name` attribute acts as a discriminator that identifies the GenAI telemetry format flavor specific to that provider within GenAI semantic conventions. It SHOULD be set consistently with provider-specific attributes and signals. For example, GenAI spans, metrics, and events related to AWS Bedrock should have the `gen_ai.provider.name` set to `aws.bedrock` and include applicable `aws.bedrock.*` attributes and are not expected to include `openai.*` attributes. **[22] `gen_ai.request.encoding_formats`:** In some GenAI systems the encoding formats are called embedding types. Also, some GenAI systems only accept a single format per request. **[23] `gen_ai.request.previous_response.id`:** Instrumentations SHOULD populate this attribute when the request references a previous response or interaction identifier to continue a conversation or pass prior context. For example, `previous_response_id` in [OpenAI Responses API](https://developers.openai.com/api/docs/guides/conversation-state#passing-context-from-the-previous-response) or `previous_interaction_id` in [Google GenAI Interactions API](https://ai.google.dev/gemini-api/docs/interactions-overview). **[24] `gen_ai.request.reasoning.level`:** The value SHOULD be the exact string value sent to the provider. Semantic conventions for individual providers SHOULD document which input parameter maps to this attribute. **[25] `gen_ai.request.stream_cursor`:** Instrumentations SHOULD populate this attribute when a request resumes a streamed response from a prior position, for example when fetching a stored response with streaming enabled. For example, `starting_after` in the [OpenAI Responses API](https://developers.openai.com/api/docs/guides/background#streaming-a-background-response) or `last_event_id` in the [Google GenAI Interactions API](https://ai.google.dev/api/interactions-api). **[26] `gen_ai.request.top_k`:** This is a decoding/sampling parameter (e.g., Anthropic `top_k`, Cohere `k`, Google `topK`), not an output-shaping parameter. In particular, OpenAI's `top_logprobs` controls how many per-token log-probabilities are returned in the response and does not change generation; it MUST NOT be reported as `gen_ai.request.top_k`. **[27] `gen_ai.response.finish_reasons`:** Values correspond to generations in the same order as the returned choices/candidates. Each position SHOULD contain the finish reason for the corresponding choice/candidate. If a finish reason was expected but not received, for example because generation failed, was cancelled, or a stream ended before the final event, instrumentations SHOULD report `error` for that position instead of omitting it. `error` indicates that the generation ended abnormally, whether reported by the provider or inferred by the instrumentation. **[28] `gen_ai.response.status`:** This attribute captures the lifecycle state of a (possibly background or long-running) generation, such as whether it is queued, still running, or has reached a terminal state. It is distinct from `gen_ai.response.finish_reasons`, which describes why the model stopped once it began producing output. The value SHOULD be the provider's response status mapped onto the closest member of this enum or a provider-specific value when none of these apply. Semantic conventions for individual GenAI providers SHOULD document how their status values map to this attribute. **[29] `gen_ai.retrieval.documents`:** Each document object SHOULD contain the following properties when available: `id` (string): A unique identifier for the document, `score` (double): The relevance score of the document Instrumentations MUST follow [JSON schema](/model/gen-ai/gen-ai-retrieval-documents.json). When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. **[30] `gen_ai.retrieval.query.text`:** > [!Warning] > This attribute may contain sensitive information. **[31] `gen_ai.skill.description`:** > [!WARNING] > This attribute may contain sensitive information. **[32] `gen_ai.skill.source.uri`:** This SHOULD identify the skill source, not a temporary location where the skill was materialized for execution. > [!WARNING] > This attribute may contain sensitive information. Sensitive URI components, such as user information and access tokens in query parameters, SHOULD be scrubbed when instrumentations can identify them. **[33] `gen_ai.system_instructions`:** This attribute SHOULD be used when the corresponding provider or API allows to provide system instructions or messages separately from the chat history. Instructions that are part of the chat history SHOULD be recorded in `gen_ai.input.messages` attribute instead. Instrumentations MAY provide a way for users to filter or truncate system instructions. > [!Warning] > This attribute may contain sensitive information. See [Recording content on attributes](/docs/gen-ai/gen-ai-spans.md#recording-content-on-attributes) section for more details. Instrumentations MUST follow [JSON schema](/model/gen-ai/gen-ai-system-instructions.json). When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. **[34] `gen_ai.system_instructions_ref`:** The presence of this attribute does not indicate whether storing the content succeeded or whether the content remains available. It is NOT RECOMMENDED to embed credentials, such as signed URL query parameters, in the URI. Access to the stored content SHOULD be secured by other means, for example by storage-level access control. > [!Warning] > The URI may expose sensitive storage metadata, such as storage provider, > bucket or container names, tenant or object identifiers. **[35] `gen_ai.token.modality`:** When the provider does not break usage down by modality and the modality cannot be reliably determined, instrumentations SHOULD report the tokens under the `unknown` modality. **[36] `gen_ai.tool.call.arguments`:** > [!WARNING] > This attribute may contain sensitive information. It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. Instrumentations MUST follow [JSON schema](/model/gen-ai/gen-ai-tool-call-arguments.json). When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. **[37] `gen_ai.tool.call.id`:** This attribute SHOULD be set to the identifier received from the model or provider if and only if one was supplied. **[38] `gen_ai.tool.call.result`:** > [!WARNING] > This attribute may contain sensitive information. It's expected to be an object - in case a serialized string is available to the instrumentation, the instrumentation SHOULD do the best effort to deserialize it to an object. Instrumentations MUST follow [JSON schema](/model/gen-ai/gen-ai-tool-call-result.json). When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. **[39] `gen_ai.tool.definitions`:** > [!WARNING] > This attribute may contain sensitive information. Since this attribute could be large, it's NOT RECOMMENDED to populate non-required properties by default. Instrumentations MAY provide a way to enable populating optional properties. Instrumentations MUST follow [JSON schema](/model/gen-ai/gen-ai-tool-definitions.json). When the attribute is recorded on events, it MUST be recorded in structured form. When recorded on spans, it MAY be recorded as a JSON string if structured format is not supported and SHOULD be recorded in structured form otherwise. **[40] `gen_ai.tool.definitions_ref`:** The presence of this attribute does not indicate whether storing the content succeeded or whether the content remains available. It is NOT RECOMMENDED to embed credentials, such as signed URL query parameters, in the URI. Access to the stored content SHOULD be secured by other means, for example by storage-level access control. > [!Warning] > The URI may expose sensitive storage metadata, such as storage provider, > bucket or container names, tenant or object identifiers. **[41] `gen_ai.tool.description`:** > [!WARNING] > This attribute may contain sensitive information. **[42] `gen_ai.tool.type`:** Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems. Agent-side operations involve actions that are performed by the agent on the server or within the agent's controlled environment. Function: A tool executed on the client-side, where the agent generates parameters for a predefined function, and the client executes the logic. Client-side operations are actions taken on the user's end or within the client application. Datastore: A tool used by the agent to access and query structured or unstructured external data for retrieval-augmented tasks or knowledge updates. **[43] `gen_ai.usage.audio.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.cache_read.input_tokens` and in `gen_ai.usage.audio.input_tokens`. **[44] `gen_ai.usage.audio.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. **[45] `gen_ai.usage.audio.output_tokens`:** The value SHOULD be included in `gen_ai.usage.output_tokens`. **[46] `gen_ai.usage.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. **[47] `gen_ai.usage.cache_write.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. **[48] `gen_ai.usage.image.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.cache_read.input_tokens` and in `gen_ai.usage.image.input_tokens`. **[49] `gen_ai.usage.image.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. **[50] `gen_ai.usage.image.output_tokens`:** The value SHOULD be included in `gen_ai.usage.output_tokens`. **[51] `gen_ai.usage.input_tokens`:** This value SHOULD include all types of input tokens, including cached tokens. Instrumentations SHOULD make a best effort to populate this value, using a total provided by the provider when available or, depending on the provider API, by summing different token types parsed from the provider output. When the provider reports both billed token counts and model-consumed token counts (for example, Cohere exposes both `usage.billed_units` and `usage.tokens`), instrumentations SHOULD report the billed count so the value matches the units the customer is charged for. Detailed usage attributes are subsets of total and aggregate counts. For example, if a request has 100 text tokens (40 cached) and 200 image tokens: - `gen_ai.usage.input_tokens`: 300 - `gen_ai.usage.cache_read.input_tokens`: 40 - `gen_ai.usage.text.input_tokens`: 100 - `gen_ai.usage.text.cache_read.input_tokens`: 40 - `gen_ai.usage.image.input_tokens`: 200 **[52] `gen_ai.usage.output_tokens`:** When the provider reports both billed token counts and model-consumed token counts (for example, Cohere exposes both `usage.billed_units` and `usage.tokens`), instrumentations SHOULD report the billed count so the value matches the units the customer is charged for. **[53] `gen_ai.usage.reasoning.output_tokens`:** The value SHOULD be included in `gen_ai.usage.output_tokens`. **[54] `gen_ai.usage.text.cache_read.input_tokens`:** The value SHOULD be included in `gen_ai.usage.cache_read.input_tokens` and in `gen_ai.usage.text.input_tokens`. **[55] `gen_ai.usage.text.input_tokens`:** The value SHOULD be included in `gen_ai.usage.input_tokens`. **[56] `gen_ai.usage.text.output_tokens`:** The value SHOULD be included in `gen_ai.usage.output_tokens`. **[57] `gen_ai.workflow.name`:** The workflow name is usually a static, application-unique identifier defined in a framework-specific way. For example, it can be the name of the first chain in LangChain, the name of the crew in CrewAI, or the entry point agent in ADK or OpenAI Agents when no explicit workflow name is provided. This attribute MUST have low cardinality. It is NOT RECOMMENDED to use instrumentation-time constants or names of types representing the workflow, such as "StateGraph". When no meaningful, low-cardinality workflow name is available for a given framework, this attribute MUST NOT be captured by default. Semantic conventions for individual Generative AI frameworks SHOULD document what `gen_ai.workflow.name` means in the context of that framework. --- `gen_ai.operation.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `chat` | Chat completion operation such as [OpenAI Chat API](https://platform.openai.com/docs/api-reference/chat) |  | | `create_agent` | Create GenAI agent |  | | `create_memory` | Create new memory records |  | | `create_memory_store` | Create or initialize a memory store |  | | `delete_memory` | Delete memory records |  | | `delete_memory_store` | Delete or deprovision a memory store |  | | `embeddings` | Embeddings operation such as [OpenAI Create embeddings API](https://platform.openai.com/docs/api-reference/embeddings/create) |  | | `execute_tool` | Execute a tool |  | | `fetch_response` | Fetch a previously generated model response by its identifier, without performing inference, such as [OpenAI Get a model response](https://platform.openai.com/docs/api-reference/responses/get) [58] |  | | `generate_content` | Multimodal content generation operation such as [Gemini Generate Content](https://ai.google.dev/api/generate-content) |  | | `invoke_agent` | Invoke GenAI agent |  | | `invoke_workflow` | Invoke GenAI workflow |  | | `plan` | Agent planning or task decomposition phase |  | | `retrieval` | Retrieval operation such as [OpenAI Search Vector Store API](https://platform.openai.com/docs/api-reference/vector-stores/search) |  | | `search_memory` | Search/query memories from a memory store |  | | `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  | | `update_memory` | Update existing memory records |  | | `upsert_memory` | Create or update memory records without the caller choosing which |  | **[58]:** Instrumentations SHOULD NOT report token usage (as attributes or metrics) for this operation. --- `gen_ai.output.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `image` | Image |  | | `json` | JSON object with known or unknown schema |  | | `speech` | Speech |  | | `text` | Plain text |  | --- `gen_ai.provider.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `anthropic` | [Anthropic](https://www.anthropic.com/) |  | | `aws.bedrock` | [AWS Bedrock](https://aws.amazon.com/bedrock) |  | | `azure.ai.inference` | Azure AI Inference |  | | `azure.ai.openai` | [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/overview) |  | | `cohere` | [Cohere](https://cohere.com/) |  | | `deepseek` | [DeepSeek](https://www.deepseek.com/) |  | | `gcp.gemini` | [Gemini](https://cloud.google.com/products/gemini) [59] |  | | `gcp.gen_ai` | Any Google generative AI endpoint [60] |  | | `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [61] |  | | `groq` | [Groq](https://groq.com/) |  | | `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) |  | | `mistral` | [Mistral](https://mistral.ai/) |  | | `moonshot_ai` | [Moonshot AI](https://www.moonshot.ai/) |  | | `openai` | [OpenAI](https://openai.com/) |  | | `perplexity` | [Perplexity](https://www.perplexity.ai/) |  | | `x_ai` | [xAI](https://x.ai/) |  | **[59]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. **[60]:** May be used when specific backend is unknown. **[61]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. --- `gen_ai.response.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `cancelled` | The response generation was cancelled before it completed. |  | | `completed` | The response finished generating successfully. |  | | `failed` | The response generation failed with an error. |  | | `in_progress` | The response is still being generated, for example a background or streamed response that has not finished. |  | | `incomplete` | The response stopped before generation completed, for example because a token limit or content filter was reached. |  | | `queued` | The response has been accepted by the provider but generation has not started yet. |  | --- `gen_ai.token.modality` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `audio` | Audio tokens. |  | | `image` | Image tokens. |  | | `text` | Text tokens. |  | | `unknown` | The modality is not known. |  | --- `gen_ai.transfer.mode` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. | Value | Description | Stability | | --- | --- | --- | | `pass_control` | The initiator does not wait for the target to finish. The target takes control of the remaining work. |  | | `return_to_caller` | The initiator waits for the target to finish and then resumes execution. |  |