# Semantic conventions for generative AI metrics **Status**: [Development][DocumentStatus] - [Generative AI client metrics](#generative-ai-client-metrics) - [Metric: `gen_ai.client.token.usage`](#metric-gen_aiclienttokenusage) - [Metric: `gen_ai.client.operation.duration`](#metric-gen_aiclientoperationduration) - [Metric: `gen_ai.client.operation.time_to_first_chunk`](#metric-gen_aiclientoperationtime_to_first_chunk) - [Metric: `gen_ai.client.operation.time_per_output_chunk`](#metric-gen_aiclientoperationtime_per_output_chunk) - [Generative AI model server metrics](#generative-ai-model-server-metrics) - [Metric: `gen_ai.server.request.duration`](#metric-gen_aiserverrequestduration) - [Metric: `gen_ai.server.time_per_output_token`](#metric-gen_aiservertime_per_output_token) - [Metric: `gen_ai.server.time_to_first_token`](#metric-gen_aiservertime_to_first_token) - [Generative AI workflow metrics](#generative-ai-workflow-metrics) - [Metric: `gen_ai.workflow.duration`](#metric-gen_aiworkflowduration) - [Generative AI agent metrics](#generative-ai-agent-metrics) - [Metric: `gen_ai.invoke_agent.duration`](#metric-gen_aiinvoke_agentduration) - [Metric: `gen_ai.invoke_agent.inference_calls`](#metric-gen_aiinvoke_agentinference_calls) - [Metric: `gen_ai.invoke_agent.tool_calls`](#metric-gen_aiinvoke_agenttool_calls) - [Generative AI tool metrics](#generative-ai-tool-metrics) - [Metric: `gen_ai.execute_tool.duration`](#metric-gen_aiexecute_toolduration) ## Generative AI client metrics The conventions described in this section are specific to Generative AI client applications. **Disclaimer:** These are initial Generative AI client metric instruments and attributes but more may be added in the future. The following metric instruments describe Generative AI operations. An operation may be a request to an LLM, a function call, or some other distinct action within a larger Generative AI workflow. Individual systems may include additional system-specific attributes. It is recommended to check system-specific documentation, if available. ### Metric: `gen_ai.client.token.usage` This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 4, 16, 64, 256, 1024, 4096, 16384, 65536, 262144, 1048576, 4194304, 16777216, 67108864]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.client.token.usage` | Histogram | `{token}` | Number of input and output tokens used. [1] |  | | **[1]:** This metric SHOULD be reported when an operation involves the usage of tokens and the count is readily available. For example, if GenAI system returns usage information in the streaming response, it SHOULD be used. Or if GenAI system returns each token independently, instrumentation SHOULD count number of output tokens and record the result. If instrumentation cannot efficiently obtain number of input and/or output tokens, it MAY allow users to enable offline token counting. Otherwise it MUST NOT report usage metric. When systems report both used tokens and billable tokens, instrumentation MUST report billable tokens. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | | [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The Generative AI provider as identified by the client or server instrumentation. [2] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | | [`gen_ai.token.type`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The type of token being counted. | `input`; `output` | | [`gen_ai.request.model`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | The name of the GenAI model a request is being made to. [3] | `gpt-4` | | [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Conditionally Required` If `server.address` is set. | int | GenAI server port. [4] | `80`; `8080`; `443` | | [`gen_ai.response.model`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` | string | The name of the model that generated the response. | `gpt-4-0613` | | [`server.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Recommended` | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | **[1] `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. **[2] `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. **[3] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. **[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[5] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. --- `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 |  | | `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 |  | --- `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) [6] |  | | `gcp.gen_ai` | Any Google generative AI endpoint [7] |  | | `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [8] |  | | `groq` | [Groq](https://groq.com/) |  | | `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) |  | | `mistral_ai` | [Mistral AI](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/) |  | **[6]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. **[7]:** May be used when specific backend is unknown. **[8]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. --- `gen_ai.token.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 | | --- | --- | --- | | `input` | Input tokens (prompt, input, etc.) |  | | `output` | Output tokens (completion, response, etc.) |  | ### Metric: `gen_ai.client.operation.duration` This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.client.operation.duration` | Histogram | `s` | GenAI operation duration. |  | | **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/error.md) |  | `Conditionally Required` If the operation ended in an error. | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` [3] | string | The Generative AI provider as identified by the client or server instrumentation. [4] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | | [`gen_ai.request.model`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | The name of the GenAI model a request is being made to. [5] | `gpt-4` | | [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Conditionally Required` If `server.address` is set. | int | GenAI server port. [6] | `80`; `8080`; `443` | | [`gen_ai.response.model`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` | string | The name of the model that generated the response. | `gpt-4-0613` | | [`server.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Recommended` | string | GenAI server address. [7] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | **[1] `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. **[2] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. **[3] `gen_ai.provider.name`:** If the operation involves a call to a GenAI provider. **[4] `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. **[5] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. **[6] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[7] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. --- `error.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 | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | --- `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 |  | | `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 |  | --- `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) [8] |  | | `gcp.gen_ai` | Any Google generative AI endpoint [9] |  | | `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [10] |  | | `groq` | [Groq](https://groq.com/) |  | | `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) |  | | `mistral_ai` | [Mistral AI](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/) |  | **[8]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. **[9]:** May be used when specific backend is unknown. **[10]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. ### Metric: `gen_ai.client.operation.time_to_first_chunk` This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.client.operation.time_to_first_chunk` | Histogram | `s` | Time to receive the first chunk, measured from when the client issues the generation request to when the first chunk is received in the response stream. [1] |  | | **[1]:** This metrics SHOULD be reported for streaming calls and SHOULD NOT be reported otherwise. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | | [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The Generative AI provider as identified by the client or server instrumentation. [2] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | | [`gen_ai.request.model`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | The name of the GenAI model a request is being made to. [3] | `gpt-4` | | [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Conditionally Required` If `server.address` is set. | int | GenAI server port. [4] | `80`; `8080`; `443` | | [`gen_ai.response.model`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` | string | The name of the model that generated the response. | `gpt-4-0613` | | [`server.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Recommended` | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | **[1] `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. **[2] `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. **[3] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. **[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[5] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. --- `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 |  | | `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 |  | --- `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) [6] |  | | `gcp.gen_ai` | Any Google generative AI endpoint [7] |  | | `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [8] |  | | `groq` | [Groq](https://groq.com/) |  | | `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) |  | | `mistral_ai` | [Mistral AI](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/) |  | **[6]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. **[7]:** May be used when specific backend is unknown. **[8]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. ### Metric: `gen_ai.client.operation.time_per_output_chunk` This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.client.operation.time_per_output_chunk` | Histogram | `s` | Time per output chunk, recorded for each chunk received after the first one, measured as the time elapsed from the end of the previous chunk to the end of the current chunk. [1] |  | | **[1]:** This metrics SHOULD be reported for streaming calls and SHOULD NOT be reported otherwise. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | | [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The Generative AI provider as identified by the client or server instrumentation. [2] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | | [`gen_ai.request.model`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | The name of the GenAI model a request is being made to. [3] | `gpt-4` | | [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Conditionally Required` If `server.address` is set. | int | GenAI server port. [4] | `80`; `8080`; `443` | | [`gen_ai.response.model`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` | string | The name of the model that generated the response. | `gpt-4-0613` | | [`server.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Recommended` | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | **[1] `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. **[2] `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. **[3] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. **[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[5] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. --- `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 |  | | `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 |  | --- `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) [6] |  | | `gcp.gen_ai` | Any Google generative AI endpoint [7] |  | | `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [8] |  | | `groq` | [Groq](https://groq.com/) |  | | `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) |  | | `mistral_ai` | [Mistral AI](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/) |  | **[6]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. **[7]:** May be used when specific backend is unknown. **[8]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. ## Generative AI model server metrics The following metric instruments describe Generative AI model servers' operational metrics. It includes both functional and performance metrics. ### Metric: `gen_ai.server.request.duration` This metric reports the model server latency in terms of time spent per request. This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.server.request.duration` | Histogram | `s` | Generative AI server request duration such as time-to-last byte or last output token. |  | | **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | | [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The Generative AI provider as identified by the client or server instrumentation. [2] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/error.md) |  | `Conditionally Required` If the operation ended in an error. | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`gen_ai.request.model`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | The name of the GenAI model a request is being made to. [4] | `gpt-4` | | [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Conditionally Required` If `server.address` is set. | int | GenAI server port. [5] | `80`; `8080`; `443` | | [`gen_ai.response.model`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` | string | The name of the model that generated the response. | `gpt-4-0613` | | [`server.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Recommended` | string | GenAI server address. [6] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | **[1] `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. **[2] `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. **[3] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. **[4] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. **[5] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[6] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. --- `error.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 | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | --- `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 |  | | `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 |  | --- `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) [7] |  | | `gcp.gen_ai` | Any Google generative AI endpoint [8] |  | | `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [9] |  | | `groq` | [Groq](https://groq.com/) |  | | `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) |  | | `mistral_ai` | [Mistral AI](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/) |  | **[7]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. **[8]:** May be used when specific backend is unknown. **[9]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. ### Metric: `gen_ai.server.time_per_output_token` This metric reports the model server latency in terms of time per token generated after the first token for any model servers which support serving LLMs. It is measured by subtracting the time taken to generate the first output token from the request duration and dividing the rest of the duration by the number of output tokens generated after the first token. This is important in measuring the performance of the decode phase of LLM inference. This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.01, 0.025, 0.05, 0.075, 0.1, 0.15, 0.2, 0.3, 0.4, 0.5, 0.75, 1.0, 2.5]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.server.time_per_output_token` | Histogram | `s` | Time per output token generated after the first token for successful responses. |  | | **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | | [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The Generative AI provider as identified by the client or server instrumentation. [2] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | | [`gen_ai.request.model`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | The name of the GenAI model a request is being made to. [3] | `gpt-4` | | [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Conditionally Required` If `server.address` is set. | int | GenAI server port. [4] | `80`; `8080`; `443` | | [`gen_ai.response.model`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` | string | The name of the model that generated the response. | `gpt-4-0613` | | [`server.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Recommended` | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | **[1] `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. **[2] `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. **[3] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. **[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[5] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. --- `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 |  | | `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 |  | --- `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) [6] |  | | `gcp.gen_ai` | Any Google generative AI endpoint [7] |  | | `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [8] |  | | `groq` | [Groq](https://groq.com/) |  | | `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) |  | | `mistral_ai` | [Mistral AI](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/) |  | **[6]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. **[7]:** May be used when specific backend is unknown. **[8]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. ### Metric: `gen_ai.server.time_to_first_token` This metric reports the model server latency in terms of time spent to generate the first token of the response for any model servers which support serving LLMs. It helps measure the time spent in the queue and the prefill phase. It is important especially for streaming requests. It is calculated at a request level and is reported as a histogram using the buckets mentioned below. This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.001, 0.005, 0.01, 0.02, 0.04, 0.06, 0.08, 0.1, 0.25, 0.5, 0.75, 1.0, 2.5, 5.0, 7.5, 10.0]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.server.time_to_first_token` | Histogram | `s` | Time to generate first token for successful responses. |  | | **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.operation.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | | [`gen_ai.provider.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | The Generative AI provider as identified by the client or server instrumentation. [2] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | | [`gen_ai.request.model`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | The name of the GenAI model a request is being made to. [3] | `gpt-4` | | [`server.port`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Conditionally Required` If `server.address` is set. | int | GenAI server port. [4] | `80`; `8080`; `443` | | [`gen_ai.response.model`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` | string | The name of the model that generated the response. | `gpt-4-0613` | | [`server.address`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/server.md) |  | `Recommended` | string | GenAI server address. [5] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | **[1] `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. **[2] `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. **[3] `gen_ai.request.model`:** The name of the GenAI model a request is being made to. If the model is supplied by a vendor, then the value must be the exact name of the model requested. If the model is a fine-tuned custom model, the value should have a more specific name than the base model that's been fine-tuned. **[4] `server.port`:** When observed from the client side, and when communicating through an intermediary, `server.port` SHOULD represent the server port behind any intermediaries, for example proxies, if it's available. **[5] `server.address`:** When observed from the client side, and when communicating through an intermediary, `server.address` SHOULD represent the server address behind any intermediaries, for example proxies, if it's available. --- `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 |  | | `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 |  | --- `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) [6] |  | | `gcp.gen_ai` | Any Google generative AI endpoint [7] |  | | `gcp.vertex_ai` | [Vertex AI](https://cloud.google.com/vertex-ai) [8] |  | | `groq` | [Groq](https://groq.com/) |  | | `ibm.watsonx.ai` | [IBM Watsonx AI](https://www.ibm.com/products/watsonx-ai) |  | | `mistral_ai` | [Mistral AI](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/) |  | **[6]:** Used when accessing the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. **[7]:** May be used when specific backend is unknown. **[8]:** Used when accessing the 'aiplatform.googleapis.com' endpoint. ## Generative AI workflow metrics Individual systems may include additional system-specific attributes. It is recommended to check system-specific documentation, if available. `gen_ai.workflow.duration` represents the end-to-end duration of a workflow execution, measured from the point where application code initiates the workflow to the point where the workflow completes, independent of workflow complexity. If instrumentation measures only a single provider-facing client operation (for example, one model API call), `gen_ai.client.operation.duration` SHOULD be used instead. Instrumentation MAY emit both metrics for the same request path when both boundaries are available. ### Metric: `gen_ai.workflow.duration` This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 5, 10, 30, 60, 120, 300, 600, 1800, 3600, 7200]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.workflow.duration` | Histogram | `s` | GenAI workflow duration. [1] |  | | **[1]:** This metric instrument describes an operation that executes a coordinated process composed of multiple agents or other operations involving generative AI. When this metric is reported alongside a `gen_ai.invoke_workflow` span, the metric value SHOULD be the same as the span duration. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/error.md) |  | `Conditionally Required` If the operation ended in an error. | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`gen_ai.workflow.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` If available. | string | Human-readable name of the GenAI workflow provided by the application. [2] | `multi_agent_rag`; `customer_support_pipeline` | **[1] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. **[2] `gen_ai.workflow.name`:** This attribute can be populated in different frameworks; for example, as the name of the first chain in LangChain or the name of the crew in CrewAI. The workflow name is usually provided by the application in a way that is specific to the generative AI framework or library that orchestrates the workflow. It is usually a static name that is expected to be unique within an application. `gen_ai.workflow.name` MUST have low cardinality. Semantic conventions for individual Generative AI frameworks SHOULD document what `gen_ai.workflow.name` means in the context of that framework. If there is no low-cardinality workflow name available for a given framework, this attribute MUST NOT be captured by default. --- `error.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 | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | ## Generative AI agent metrics Individual systems may include additional system-specific attributes. It is recommended to check system-specific documentation, if available. ### Metric: `gen_ai.invoke_agent.duration` This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.1, 0.2, 0.4, 0.8, 1.6, 3.2, 6.4, 12.8, 25.6, 51.2, 102.4, 204.8, 409.6]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.invoke_agent.duration` | Histogram | `s` | The end-to-end duration of a single in-process agent invocation, from the moment the invocation starts until the agent emits the last chunk of its final response or terminates with an error. [1] |  | | **[1]:** Intended for instrumentations of agent frameworks (for example, ADK, LangChain agents, CrewAI agents) that can reliably bound a single agent invocation. If instrumentation can only measure a single provider-facing client operation (for example, one model API call), `gen_ai.client.operation.duration` SHOULD be used instead. If instrumentation can reliably bound a higher-level workflow that coordinates multiple agents, `gen_ai.workflow.duration` SHOULD be used for that workflow. Instrumentation MAY emit several of these metrics for the same request path when more than one boundary is available. When this metric is reported alongside a `gen_ai.invoke_agent.internal` span, the metric value SHOULD be the same as the span duration. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/error.md) |  | `Conditionally Required` If the operation ended in an error. | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` When available. | string | The human-readable name of the invoked GenAI agent. | `Math Tutor`; `Fiction Writer` | | [`gen_ai.request.model`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If applicable. | string | The name of the GenAI model configured for the agent. [2] | `gpt-4` | **[1] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. **[2] `gen_ai.request.model`:** This attribute SHOULD be populated if and only if the instrumented library allows to set only a single model per agent. It SHOULD NOT be populated for agents that support multiple models or dynamic selection. --- `error.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 | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | ### Metric: `gen_ai.invoke_agent.inference_calls` This metric is [recommended][MetricRecommended] for instrumentations of agent frameworks that can reliably attribute inference (model) calls to a single agent invocation. This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 2, 4, 8, 16, 32, 64, 128]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.invoke_agent.inference_calls` | Histogram | `{inference_call}` | The number of inference (model) calls a GenAI agent makes during a single invocation. [1] |  | | **[1]:** The distribution is scoped to a single agent invocation and SHOULD include only the inference calls the agent itself issued including failed ones; calls made by sub-agents or transferred-to agents are recorded against those agents' own invocations so that each inference call is counted exactly once across the call tree. This metric SHOULD be emitted together with the `gen_ai.invoke_agent.internal` span for the same invocation. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` | string | Human-readable name of the GenAI agent provided by the application. | `Math Tutor`; `Fiction Writer` | ### Metric: `gen_ai.invoke_agent.tool_calls` This metric is [recommended][MetricRecommended] for instrumentations of agent frameworks that can reliably attribute tool calls to a single agent invocation. This metric SHOULD be specified with [ExplicitBucketBoundaries] of [1, 2, 4, 8, 16, 32, 64, 128]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.invoke_agent.tool_calls` | Histogram | `{tool_call}` | The number of tool calls a GenAI agent makes during a single invocation. [1] |  | | **[1]:** The distribution is scoped to a single agent invocation and SHOULD include only the tool calls the agent itself triggers including failed ones; calls made by sub-agents or transferred-to agents are recorded against those agents' own invocations so that each tool call is counted exactly once across the call tree. Only client-side tool calls (tools executed by the agent or framework) are counted. Tools executed server-side by the model provider (for example, provider built-in web search or code execution) are not counted here. This metric SHOULD be emitted together with the `gen_ai.invoke_agent.internal` span for the same invocation. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` | string | Human-readable name of the GenAI agent provided by the application. | `Math Tutor`; `Fiction Writer` | ## Generative AI tool metrics Individual systems may include additional system-specific attributes. It is recommended to check system-specific documentation, if available. ### Metric: `gen_ai.execute_tool.duration` This metric SHOULD be specified with [ExplicitBucketBoundaries] of [0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92]. | Name | Instrument Type | Unit (UCUM) | Description | Stability | Entity Associations | | -------- | --------------- | ----------- | -------------- | --------- | ------ | | `gen_ai.execute_tool.duration` | Histogram | `s` | The duration of a single tool execution. [1] |  | | **[1]:** Instrumentation that can reliably bound a single tool call SHOULD record this metric for every tool execution they can observe. When this metric is reported alongside a `gen_ai.execute_tool` span, the metric value SHOULD be the same as the span duration. **Requirement level:** [Recommended](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/signal-requirement-level.md). **Attributes:** | Key | Stability | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Value Type | Description | Example Values | | --- | --- | --- | --- | --- | --- | | [`gen_ai.tool.name`](/docs/registry/attributes/gen-ai.md) |  | `Required` | string | Name of the tool utilized by the agent. | `Flights` | | [`error.type`](https://github.com/open-telemetry/semantic-conventions/blob/v1.43.0/docs/registry/attributes/error.md) |  | `Conditionally Required` If the operation ended in an error. | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | | [`gen_ai.agent.name`](/docs/registry/attributes/gen-ai.md) |  | `Conditionally Required` When applicable. | string | The human-readable name of the agent executing the tool. | `Math Tutor`; `Fiction Writer` | | [`gen_ai.tool.type`](/docs/registry/attributes/gen-ai.md) |  | `Recommended` If available. | string | Type of the tool utilized by the agent [2] | `function`; `extension`; `datastore` | **[1] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI provider or the client library, the canonical name of exception that occurred, or another low-cardinality error identifier. Instrumentations SHOULD document the list of errors they report. **[2] `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. --- `error.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 | | --- | --- | --- | | `_OTHER` | A fallback error value to be used when the instrumentation doesn't define a custom value. |  | [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status [ExplicitBucketBoundaries]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.55.0/specification/metrics/api.md#instrument-advisory-parameters