Add `gen_ai.conversation.id` attribute (#2163)
This commit is contained in:
Guangya Liu
GitHub
parent
e065d84eb1
commit
27e657cc77
|
|
@ -0,0 +1,22 @@
|
|||
# Use this changelog template to create an entry for release notes.
|
||||
#
|
||||
# If your change doesn't affect end users you should instead start
|
||||
# your pull request title with [chore] or use the "Skip Changelog" label.
|
||||
|
||||
# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
|
||||
change_type: enhancement
|
||||
|
||||
# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
|
||||
component: gen-ai
|
||||
|
||||
# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
|
||||
note: Add `gen_ai.conversation.id` attribute
|
||||
|
||||
# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
|
||||
# The values here must be integers.
|
||||
issues: [2024]
|
||||
|
||||
# (Optional) One or more lines of additional information to render under the primary note.
|
||||
# These lines will be padded with 2 spaces and then inserted directly into the document.
|
||||
# Use pipe (|) for multiline entries.
|
||||
subtext:
|
||||
|
|
@ -17,6 +17,7 @@ This document defines the attributes used to describe telemetry in the context o
|
|||
| <a id="gen-ai-agent-description" href="#gen-ai-agent-description">`gen_ai.agent.description`</a> | string | Free-form description of the GenAI agent provided by the application. | `Helps with math problems`; `Generates fiction stories` |  |
|
||||
| <a id="gen-ai-agent-id" href="#gen-ai-agent-id">`gen_ai.agent.id`</a> | string | The unique identifier of the GenAI agent. | `asst_5j66UpCpwteGg4YSxUnt7lPY` |  |
|
||||
| <a id="gen-ai-agent-name" href="#gen-ai-agent-name">`gen_ai.agent.name`</a> | string | Human-readable name of the GenAI agent provided by the application. | `Math Tutor`; `Fiction Writer` |  |
|
||||
| <a id="gen-ai-conversation-id" href="#gen-ai-conversation-id">`gen_ai.conversation.id`</a> | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. | `conv_5j66UpCpwteGg4YSxUnt7lPY` |  |
|
||||
| <a id="gen-ai-data-source-id" href="#gen-ai-data-source-id">`gen_ai.data_source.id`</a> | string | The data source identifier. [1] | `H7STPQYOND` |  |
|
||||
| <a id="gen-ai-operation-name" href="#gen-ai-operation-name">`gen_ai.operation.name`</a> | string | The name of the operation being performed. [2] | `chat`; `generate_content`; `text_completion` |  |
|
||||
| <a id="gen-ai-output-type" href="#gen-ai-output-type">`gen_ai.output.type`</a> | string | Represents the content type requested by the client. [3] | `text`; `json`; `image` |  |
|
||||
|
|
|
|||
|
|
@ -37,11 +37,12 @@ Describes an AWS Bedrock operation span.
|
|||
| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | `Required` |  |
|
||||
| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` |  |
|
||||
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error |  |
|
||||
| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [4] | `text`; `json`; `image` | `Conditionally Required` [5] |  |
|
||||
| [`gen_ai.conversation.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [4] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | `Conditionally Required` when available |  |
|
||||
| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [5] | `text`; `json`; `image` | `Conditionally Required` [6] |  |
|
||||
| [`gen_ai.request.choice.count`](/docs/attributes-registry/gen-ai.md) | int | The target number of candidate completions to return. | `3` | `Conditionally Required` if available, in the request, and !=1 |  |
|
||||
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [6] | `gpt-4` | `Conditionally Required` If available. |  |
|
||||
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [7] | `gpt-4` | `Conditionally Required` If available. |  |
|
||||
| [`gen_ai.request.seed`](/docs/attributes-registry/gen-ai.md) | int | Requests with same seed value more likely to return same result. | `100` | `Conditionally Required` if applicable and if the request includes a seed |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [7] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [8] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
|
||||
| [`aws.bedrock.knowledge_base.id`](/docs/attributes-registry/aws.md) | string | The unique identifier of the AWS Bedrock Knowledge base. A [knowledge base](https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base.html) is a bank of information that can be queried by models to generate more relevant responses and augment prompts. | `XFWUPB9PAW` | `Recommended` |  |
|
||||
| [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
|
||||
| [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` |  |
|
||||
|
|
@ -52,10 +53,10 @@ Describes an AWS Bedrock operation span.
|
|||
| [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` |  |
|
||||
| [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` |  |
|
||||
| [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` |  |
|
||||
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [8] | `gpt-4-0613` | `Recommended` |  |
|
||||
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [9] | `gpt-4-0613` | `Recommended` |  |
|
||||
| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` |  |
|
||||
| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
|
||||
**[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.
|
||||
|
||||
|
|
@ -75,19 +76,33 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
|
|||
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.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.
|
||||
**[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have it readily available
|
||||
for a given operation, for example:
|
||||
|
||||
- when client framework being instrumented manages conversation history
|
||||
(see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
|
||||
|
||||
- when instrumenting GenAI client libraries that maintain conversation on the backend side
|
||||
(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))
|
||||
|
||||
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.
|
||||
|
||||
**[5] `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.
|
||||
|
||||
**[5] `gen_ai.output.type`:** when applicable and if the request includes an output format.
|
||||
**[6] `gen_ai.output.type`:** when applicable and if the request includes an output format.
|
||||
|
||||
**[6] `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.
|
||||
**[7] `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.
|
||||
|
||||
**[7] `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.
|
||||
**[8] `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.
|
||||
|
||||
**[8] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. 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.
|
||||
**[9] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. 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.
|
||||
|
||||
**[9] `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.
|
||||
**[10] `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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -134,9 +149,9 @@ Additional output format details may be recorded in the future in the `gen_ai.ou
|
|||
| `az.ai.openai` | Azure OpenAI |  |
|
||||
| `cohere` | Cohere |  |
|
||||
| `deepseek` | DeepSeek |  |
|
||||
| `gcp.gemini` | Gemini [10] |  |
|
||||
| `gcp.gen_ai` | Any Google generative AI endpoint [11] |  |
|
||||
| `gcp.vertex_ai` | Vertex AI [12] |  |
|
||||
| `gcp.gemini` | Gemini [11] |  |
|
||||
| `gcp.gen_ai` | Any Google generative AI endpoint [12] |  |
|
||||
| `gcp.vertex_ai` | Vertex AI [13] |  |
|
||||
| `groq` | Groq |  |
|
||||
| `ibm.watsonx.ai` | IBM Watsonx AI |  |
|
||||
| `mistral_ai` | Mistral AI |  |
|
||||
|
|
@ -144,11 +159,11 @@ Additional output format details may be recorded in the future in the `gen_ai.ou
|
|||
| `perplexity` | Perplexity |  |
|
||||
| `xai` | xAI |  |
|
||||
|
||||
**[10]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
**[11]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
|
||||
**[11]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
**[12]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
|
||||
**[12]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
**[13]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
|
||||
<!-- markdownlint-restore -->
|
||||
<!-- prettier-ignore-end -->
|
||||
|
|
|
|||
|
|
@ -36,12 +36,13 @@ model name is available and `{gen_ai.operation.name}` otherwise.
|
|||
|---|---|---|---|---|---|
|
||||
| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | `Required` |  |
|
||||
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [2] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error |  |
|
||||
| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [3] | `text`; `json`; `image` | `Conditionally Required` [4] |  |
|
||||
| [`gen_ai.conversation.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [3] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | `Conditionally Required` when available |  |
|
||||
| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [4] | `text`; `json`; `image` | `Conditionally Required` [5] |  |
|
||||
| [`gen_ai.request.choice.count`](/docs/attributes-registry/gen-ai.md) | int | The target number of candidate completions to return. | `3` | `Conditionally Required` if available, in the request, and !=1 |  |
|
||||
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [5] | `gpt-4` | `Conditionally Required` If available. |  |
|
||||
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [6] | `gpt-4` | `Conditionally Required` If available. |  |
|
||||
| [`gen_ai.request.seed`](/docs/attributes-registry/gen-ai.md) | int | Requests with same seed value more likely to return same result. | `100` | `Conditionally Required` if applicable and if the request includes a seed |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [6] | `80`; `8080`; `443` | `Conditionally Required` If not default (443). |  |
|
||||
| [`az.namespace`](/docs/attributes-registry/azure.md) | string | [Azure Resource Provider Namespace](https://learn.microsoft.com/azure/azure-resource-manager/management/azure-services-resource-providers) as recognized by the client. [7] | `Microsoft.CognitiveServices` | `Recommended` |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [7] | `80`; `8080`; `443` | `Conditionally Required` If not default (443). |  |
|
||||
| [`az.namespace`](/docs/attributes-registry/azure.md) | string | [Azure Resource Provider Namespace](https://learn.microsoft.com/azure/azure-resource-manager/management/azure-services-resource-providers) as recognized by the client. [8] | `Microsoft.CognitiveServices` | `Recommended` |  |
|
||||
| [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
|
||||
| [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` |  |
|
||||
| [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
|
||||
|
|
@ -50,10 +51,10 @@ model name is available and `{gen_ai.operation.name}` otherwise.
|
|||
| [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` |  |
|
||||
| [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` |  |
|
||||
| [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` |  |
|
||||
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [8] | `gpt-4-0613` | `Recommended` |  |
|
||||
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [9] | `gpt-4-0613` | `Recommended` |  |
|
||||
| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of prompt tokens as reported in the usage prompt_tokens property of the response. | `100` | `Recommended` |  |
|
||||
| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of completion tokens as reported in the usage completion_tokens property of the response. | `180` | `Recommended` |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
|
||||
**[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.
|
||||
|
||||
|
|
@ -61,7 +62,21 @@ model name is available and `{gen_ai.operation.name}` otherwise.
|
|||
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.output.type`:** This attribute SHOULD be set to the output type requested by the client:
|
||||
**[3] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have it readily available
|
||||
for a given operation, for example:
|
||||
|
||||
- when client framework being instrumented manages conversation history
|
||||
(see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
|
||||
|
||||
- when instrumenting GenAI client libraries that maintain conversation on the backend side
|
||||
(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))
|
||||
|
||||
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.output.type`:** This attribute SHOULD be set to the output type requested by the client:
|
||||
- `json` for structured outputs with defined or undefined schema
|
||||
- `image` for image output
|
||||
- `speech` for speech output
|
||||
|
|
@ -74,17 +89,17 @@ URL pointing to an image file.
|
|||
Additional output format details may be recorded in the future in the
|
||||
`gen_ai.output.{type}.*` attributes.
|
||||
|
||||
**[4] `gen_ai.output.type`:** when applicable and if the request includes an output format.
|
||||
**[5] `gen_ai.output.type`:** when applicable and if the request includes an output format.
|
||||
|
||||
**[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] `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.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] `az.namespace`:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.CognitiveServices` for all operations performed by Azure AI Inference clients.
|
||||
**[8] `az.namespace`:** When `az.namespace` attribute is populated, it MUST be set to `Microsoft.CognitiveServices` for all operations performed by Azure AI Inference clients.
|
||||
|
||||
**[8] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. 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.
|
||||
**[9] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. 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.
|
||||
|
||||
**[9] `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.
|
||||
**[10] `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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -170,12 +170,13 @@ Semantic conventions for individual GenAI systems and frameworks MAY specify dif
|
|||
| [`gen_ai.agent.description`](/docs/attributes-registry/gen-ai.md) | string | Free-form description of the GenAI agent provided by the application. | `Helps with math problems`; `Generates fiction stories` | `Conditionally Required` when available |  |
|
||||
| [`gen_ai.agent.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier of the GenAI agent. | `asst_5j66UpCpwteGg4YSxUnt7lPY` | `Conditionally Required` if applicable. |  |
|
||||
| [`gen_ai.agent.name`](/docs/attributes-registry/gen-ai.md) | string | Human-readable name of the GenAI agent provided by the application. | `Math Tutor`; `Fiction Writer` | `Conditionally Required` when available |  |
|
||||
| [`gen_ai.data_source.id`](/docs/attributes-registry/gen-ai.md) | string | The data source identifier. [4] | `H7STPQYOND` | `Conditionally Required` if applicable. |  |
|
||||
| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [5] | `text`; `json`; `image` | `Conditionally Required` [6] |  |
|
||||
| [`gen_ai.conversation.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [4] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | `Conditionally Required` when available |  |
|
||||
| [`gen_ai.data_source.id`](/docs/attributes-registry/gen-ai.md) | string | The data source identifier. [5] | `H7STPQYOND` | `Conditionally Required` if applicable. |  |
|
||||
| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [6] | `text`; `json`; `image` | `Conditionally Required` [7] |  |
|
||||
| [`gen_ai.request.choice.count`](/docs/attributes-registry/gen-ai.md) | int | The target number of candidate completions to return. | `3` | `Conditionally Required` if available, in the request, and !=1 |  |
|
||||
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [7] | `gpt-4` | `Conditionally Required` If available. |  |
|
||||
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [8] | `gpt-4` | `Conditionally Required` If available. |  |
|
||||
| [`gen_ai.request.seed`](/docs/attributes-registry/gen-ai.md) | int | Requests with same seed value more likely to return same result. | `100` | `Conditionally Required` if applicable and if the request includes a seed |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [8] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [9] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
|
||||
| [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
|
||||
| [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` |  |
|
||||
| [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
|
||||
|
|
@ -184,10 +185,10 @@ Semantic conventions for individual GenAI systems and frameworks MAY specify dif
|
|||
| [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` |  |
|
||||
| [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` |  |
|
||||
| [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` |  |
|
||||
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [9] | `gpt-4-0613` | `Recommended` |  |
|
||||
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [10] | `gpt-4-0613` | `Recommended` |  |
|
||||
| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` |  |
|
||||
| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
|
||||
**[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.
|
||||
|
||||
|
|
@ -207,21 +208,35 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
|
|||
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.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.
|
||||
**[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have it readily available
|
||||
for a given operation, for example:
|
||||
|
||||
**[5] `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.
|
||||
- when client framework being instrumented manages conversation history
|
||||
(see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
|
||||
|
||||
- when instrumenting GenAI client libraries that maintain conversation on the backend side
|
||||
(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))
|
||||
|
||||
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.
|
||||
|
||||
**[5] `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.
|
||||
|
||||
**[6] `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.
|
||||
|
||||
**[6] `gen_ai.output.type`:** when applicable and if the request includes an output format.
|
||||
**[7] `gen_ai.output.type`:** when applicable and if the request includes an output format.
|
||||
|
||||
**[7] `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.
|
||||
**[8] `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.
|
||||
|
||||
**[8] `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.
|
||||
**[9] `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.
|
||||
|
||||
**[9] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. 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.
|
||||
**[10] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. 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.
|
||||
|
||||
**[10] `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.
|
||||
**[11] `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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -268,9 +283,9 @@ Additional output format details may be recorded in the future in the `gen_ai.ou
|
|||
| `az.ai.openai` | Azure OpenAI |  |
|
||||
| `cohere` | Cohere |  |
|
||||
| `deepseek` | DeepSeek |  |
|
||||
| `gcp.gemini` | Gemini [11] |  |
|
||||
| `gcp.gen_ai` | Any Google generative AI endpoint [12] |  |
|
||||
| `gcp.vertex_ai` | Vertex AI [13] |  |
|
||||
| `gcp.gemini` | Gemini [12] |  |
|
||||
| `gcp.gen_ai` | Any Google generative AI endpoint [13] |  |
|
||||
| `gcp.vertex_ai` | Vertex AI [14] |  |
|
||||
| `groq` | Groq |  |
|
||||
| `ibm.watsonx.ai` | IBM Watsonx AI |  |
|
||||
| `mistral_ai` | Mistral AI |  |
|
||||
|
|
@ -278,11 +293,11 @@ Additional output format details may be recorded in the future in the `gen_ai.ou
|
|||
| `perplexity` | Perplexity |  |
|
||||
| `xai` | xAI |  |
|
||||
|
||||
**[11]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
**[12]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
|
||||
**[12]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
**[13]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
|
||||
**[13]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
**[14]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
|
||||
<!-- markdownlint-restore -->
|
||||
<!-- prettier-ignore-end -->
|
||||
|
|
|
|||
|
|
@ -47,11 +47,12 @@ client or when the GenAI call happens over instrumented protocol such as HTTP.
|
|||
| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | `Required` |  |
|
||||
| [`gen_ai.system`](/docs/attributes-registry/gen-ai.md) | string | The Generative AI product as identified by the client or server instrumentation. [2] | `openai` | `Required` |  |
|
||||
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error |  |
|
||||
| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [4] | `text`; `json`; `image` | `Conditionally Required` [5] |  |
|
||||
| [`gen_ai.conversation.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [4] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | `Conditionally Required` when available |  |
|
||||
| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [5] | `text`; `json`; `image` | `Conditionally Required` [6] |  |
|
||||
| [`gen_ai.request.choice.count`](/docs/attributes-registry/gen-ai.md) | int | The target number of candidate completions to return. | `3` | `Conditionally Required` if available, in the request, and !=1 |  |
|
||||
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [6] | `gpt-4` | `Conditionally Required` If available. |  |
|
||||
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [7] | `gpt-4` | `Conditionally Required` If available. |  |
|
||||
| [`gen_ai.request.seed`](/docs/attributes-registry/gen-ai.md) | int | Requests with same seed value more likely to return same result. | `100` | `Conditionally Required` if applicable and if the request includes a seed |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [7] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [8] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
|
||||
| [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
|
||||
| [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` |  |
|
||||
| [`gen_ai.request.presence_penalty`](/docs/attributes-registry/gen-ai.md) | double | The presence penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
|
||||
|
|
@ -61,10 +62,10 @@ client or when the GenAI call happens over instrumented protocol such as HTTP.
|
|||
| [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` |  |
|
||||
| [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` |  |
|
||||
| [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` |  |
|
||||
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [8] | `gpt-4-0613` | `Recommended` |  |
|
||||
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [9] | `gpt-4-0613` | `Recommended` |  |
|
||||
| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI input (prompt). | `100` | `Recommended` |  |
|
||||
| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the GenAI response (completion). | `180` | `Recommended` |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [9] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
|
||||
**[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.
|
||||
|
||||
|
|
@ -84,19 +85,33 @@ If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`.
|
|||
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.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.
|
||||
**[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have it readily available
|
||||
for a given operation, for example:
|
||||
|
||||
- when client framework being instrumented manages conversation history
|
||||
(see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
|
||||
|
||||
- when instrumenting GenAI client libraries that maintain conversation on the backend side
|
||||
(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))
|
||||
|
||||
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.
|
||||
|
||||
**[5] `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.
|
||||
|
||||
**[5] `gen_ai.output.type`:** when applicable and if the request includes an output format.
|
||||
**[6] `gen_ai.output.type`:** when applicable and if the request includes an output format.
|
||||
|
||||
**[6] `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.
|
||||
**[7] `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.
|
||||
|
||||
**[7] `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.
|
||||
**[8] `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.
|
||||
|
||||
**[8] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. 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.
|
||||
**[9] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. 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.
|
||||
|
||||
**[9] `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.
|
||||
**[10] `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.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -143,9 +158,9 @@ Additional output format details may be recorded in the future in the `gen_ai.ou
|
|||
| `az.ai.openai` | Azure OpenAI |  |
|
||||
| `cohere` | Cohere |  |
|
||||
| `deepseek` | DeepSeek |  |
|
||||
| `gcp.gemini` | Gemini [10] |  |
|
||||
| `gcp.gen_ai` | Any Google generative AI endpoint [11] |  |
|
||||
| `gcp.vertex_ai` | Vertex AI [12] |  |
|
||||
| `gcp.gemini` | Gemini [11] |  |
|
||||
| `gcp.gen_ai` | Any Google generative AI endpoint [12] |  |
|
||||
| `gcp.vertex_ai` | Vertex AI [13] |  |
|
||||
| `groq` | Groq |  |
|
||||
| `ibm.watsonx.ai` | IBM Watsonx AI |  |
|
||||
| `mistral_ai` | Mistral AI |  |
|
||||
|
|
@ -153,11 +168,11 @@ Additional output format details may be recorded in the future in the `gen_ai.ou
|
|||
| `perplexity` | Perplexity |  |
|
||||
| `xai` | xAI |  |
|
||||
|
||||
**[10]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
**[11]:** This refers to the 'generativelanguage.googleapis.com' endpoint. Also known as the AI Studio API. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
|
||||
**[11]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
**[12]:** May be used when specific backend is unknown. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
|
||||
**[12]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
**[13]:** This refers to the 'aiplatform.googleapis.com' endpoint. May use common attributes prefixed with 'gcp.gen_ai.'.
|
||||
|
||||
<!-- markdownlint-restore -->
|
||||
<!-- prettier-ignore-end -->
|
||||
|
|
|
|||
|
|
@ -47,12 +47,13 @@ Semantic Conventions for [OpenAI](https://openai.com/) client spans extend and o
|
|||
| [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `generate_content`; `text_completion` | `Required` |  |
|
||||
| [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [2] | `gpt-4` | `Required` |  |
|
||||
| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [3] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error |  |
|
||||
| [`gen_ai.openai.request.service_tier`](/docs/attributes-registry/gen-ai.md) | string | The service tier requested. May be a specific tier, default, or auto. | `auto`; `default` | `Conditionally Required` [4] |  |
|
||||
| [`gen_ai.openai.response.service_tier`](/docs/attributes-registry/gen-ai.md) | string | The service tier used for the response. | `scale`; `default` | `Conditionally Required` [5] |  |
|
||||
| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [6] | `text`; `json`; `image` | `Conditionally Required` [7] |  |
|
||||
| [`gen_ai.conversation.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation. [4] | `conv_5j66UpCpwteGg4YSxUnt7lPY` | `Conditionally Required` when available |  |
|
||||
| [`gen_ai.openai.request.service_tier`](/docs/attributes-registry/gen-ai.md) | string | The service tier requested. May be a specific tier, default, or auto. | `auto`; `default` | `Conditionally Required` [5] |  |
|
||||
| [`gen_ai.openai.response.service_tier`](/docs/attributes-registry/gen-ai.md) | string | The service tier used for the response. | `scale`; `default` | `Conditionally Required` [6] |  |
|
||||
| [`gen_ai.output.type`](/docs/attributes-registry/gen-ai.md) | string | Represents the content type requested by the client. [7] | `text`; `json`; `image` | `Conditionally Required` [8] |  |
|
||||
| [`gen_ai.request.choice.count`](/docs/attributes-registry/gen-ai.md) | int | The target number of candidate completions to return. | `3` | `Conditionally Required` if available, in the request, and !=1 |  |
|
||||
| [`gen_ai.request.seed`](/docs/attributes-registry/gen-ai.md) | int | Requests with same seed value more likely to return same result. | `100` | `Conditionally Required` if applicable and if the request includes a seed |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [8] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
|
||||
| [`server.port`](/docs/attributes-registry/server.md) | int | GenAI server port. [9] | `80`; `8080`; `443` | `Conditionally Required` If `server.address` is set. |  |
|
||||
| [`gen_ai.openai.response.system_fingerprint`](/docs/attributes-registry/gen-ai.md) | string | A fingerprint to track any eventual change in the Generative AI environment. | `fp_44709d6fcb` | `Recommended` |  |
|
||||
| [`gen_ai.request.frequency_penalty`](/docs/attributes-registry/gen-ai.md) | double | The frequency penalty setting for the GenAI request. | `0.1` | `Recommended` |  |
|
||||
| [`gen_ai.request.max_tokens`](/docs/attributes-registry/gen-ai.md) | int | The maximum number of tokens the model generates for a request. | `100` | `Recommended` |  |
|
||||
|
|
@ -62,10 +63,10 @@ Semantic Conventions for [OpenAI](https://openai.com/) client spans extend and o
|
|||
| [`gen_ai.request.top_p`](/docs/attributes-registry/gen-ai.md) | double | The top_p sampling setting for the GenAI request. | `1.0` | `Recommended` |  |
|
||||
| [`gen_ai.response.finish_reasons`](/docs/attributes-registry/gen-ai.md) | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` | `Recommended` |  |
|
||||
| [`gen_ai.response.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier for the completion. | `chatcmpl-123` | `Recommended` |  |
|
||||
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [9] | `gpt-4-0613` | `Recommended` |  |
|
||||
| [`gen_ai.response.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the model that generated the response. [10] | `gpt-4-0613` | `Recommended` |  |
|
||||
| [`gen_ai.usage.input_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the prompt sent to OpenAI. | `100` | `Recommended` |  |
|
||||
| [`gen_ai.usage.output_tokens`](/docs/attributes-registry/gen-ai.md) | int | The number of tokens used in the completions from OpenAI. | `180` | `Recommended` |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [10] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
| [`server.address`](/docs/attributes-registry/server.md) | string | GenAI server address. [11] | `example.com`; `10.1.2.80`; `/tmp/my.sock` | `Recommended` |  |
|
||||
|
||||
**[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.
|
||||
|
||||
|
|
@ -75,11 +76,25 @@ Semantic Conventions for [OpenAI](https://openai.com/) client spans extend and o
|
|||
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.openai.request.service_tier`:** if the request includes a service_tier and the value is not 'auto'
|
||||
**[4] `gen_ai.conversation.id`:** Instrumentations SHOULD populate conversation id when they have it readily available
|
||||
for a given operation, for example:
|
||||
|
||||
**[5] `gen_ai.openai.response.service_tier`:** if the response was received and includes a service_tier
|
||||
- when client framework being instrumented manages conversation history
|
||||
(see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
|
||||
|
||||
**[6] `gen_ai.output.type`:** This attribute SHOULD be set to the output type requested by the client:
|
||||
- when instrumenting GenAI client libraries that maintain conversation on the backend side
|
||||
(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))
|
||||
|
||||
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.
|
||||
|
||||
**[5] `gen_ai.openai.request.service_tier`:** if the request includes a service_tier and the value is not 'auto'
|
||||
|
||||
**[6] `gen_ai.openai.response.service_tier`:** if the response was received and includes a service_tier
|
||||
|
||||
**[7] `gen_ai.output.type`:** This attribute SHOULD be set to the output type requested by the client:
|
||||
- `json` for structured outputs with defined or undefined schema
|
||||
- `image` for image output
|
||||
- `speech` for speech output
|
||||
|
|
@ -92,13 +107,13 @@ URL pointing to an image file.
|
|||
Additional output format details may be recorded in the future in the
|
||||
`gen_ai.output.{type}.*` attributes.
|
||||
|
||||
**[7] `gen_ai.output.type`:** when applicable and if the request includes an output format.
|
||||
**[8] `gen_ai.output.type`:** when applicable and if the request includes an output format.
|
||||
|
||||
**[8] `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.
|
||||
**[9] `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.
|
||||
|
||||
**[9] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. 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.
|
||||
**[10] `gen_ai.response.model`:** If available. The name of the GenAI model that provided the response. If the model is supplied by a vendor, then the value must be the exact name of the model actually used. 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.
|
||||
|
||||
**[10] `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.
|
||||
**[11] `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.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -211,6 +211,11 @@ groups:
|
|||
brief: 'Output tokens (completion, response, etc.)'
|
||||
brief: The type of token being counted.
|
||||
examples: ['input', 'output']
|
||||
- id: gen_ai.conversation.id
|
||||
stability: development
|
||||
type: string
|
||||
brief: The unique identifier for a conversation (session, thread), used to store and correlate messages within this conversation.
|
||||
examples: ["conv_5j66UpCpwteGg4YSxUnt7lPY"]
|
||||
- id: gen_ai.agent.id # alternatives: assistant (openai)
|
||||
stability: development
|
||||
type: string
|
||||
|
|
|
|||
|
|
@ -71,6 +71,23 @@ groups:
|
|||
requirement_level: recommended
|
||||
- ref: gen_ai.usage.output_tokens
|
||||
requirement_level: recommended
|
||||
- ref: gen_ai.conversation.id
|
||||
requirement_level:
|
||||
conditionally_required: when available
|
||||
note: |
|
||||
Instrumentations SHOULD populate conversation id when they have it readily available
|
||||
for a given operation, for example:
|
||||
|
||||
- when client framework being instrumented manages conversation history
|
||||
(see [LlamaIndex chat store](https://docs.llamaindex.ai/en/stable/module_guides/storing/chat_stores/))
|
||||
|
||||
- when instrumenting GenAI client libraries that maintain conversation on the backend side
|
||||
(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))
|
||||
|
||||
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.
|
||||
|
||||
- id: span.gen_ai.inference.client
|
||||
type: span
|
||||
|
|
|
|||
Loading…
Reference in New Issue