214 lines
22 KiB
Markdown
214 lines
22 KiB
Markdown
<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
|
|
<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
|
|
|
|
# Gen AI
|
|
|
|
- [GenAI Attributes](#genai-attributes)
|
|
- [Deprecated GenAI Attributes](#deprecated-genai-attributes)
|
|
- [Deprecated OpenAI GenAI Attributes](#deprecated-openai-genai-attributes)
|
|
|
|
## GenAI Attributes
|
|
|
|
This document defines the attributes used to describe telemetry in the context of Generative Artificial Intelligence (GenAI) Models requests and responses.
|
|
|
|
| Attribute | Type | Description | Examples | Stability |
|
|
|---|---|---|---|---|
|
|
| <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` |  |
|
|
| <a id="gen-ai-provider-name" href="#gen-ai-provider-name">`gen_ai.provider.name`</a> | string | The Generative AI provider as identified by the client or server instrumentation. [4] | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` |  |
|
|
| <a id="gen-ai-request-choice-count" href="#gen-ai-request-choice-count">`gen_ai.request.choice.count`</a> | int | The target number of candidate completions to return. | `3` |  |
|
|
| <a id="gen-ai-request-encoding-formats" href="#gen-ai-request-encoding-formats">`gen_ai.request.encoding_formats`</a> | string[] | The encoding formats requested in an embeddings operation, if specified. [5] | `["base64"]`; `["float", "binary"]` |  |
|
|
| <a id="gen-ai-request-frequency-penalty" href="#gen-ai-request-frequency-penalty">`gen_ai.request.frequency_penalty`</a> | double | The frequency penalty setting for the GenAI request. | `0.1` |  |
|
|
| <a id="gen-ai-request-max-tokens" href="#gen-ai-request-max-tokens">`gen_ai.request.max_tokens`</a> | int | The maximum number of tokens the model generates for a request. | `100` |  |
|
|
| <a id="gen-ai-request-model" href="#gen-ai-request-model">`gen_ai.request.model`</a> | string | The name of the GenAI model a request is being made to. | `gpt-4` |  |
|
|
| <a id="gen-ai-request-presence-penalty" href="#gen-ai-request-presence-penalty">`gen_ai.request.presence_penalty`</a> | double | The presence penalty setting for the GenAI request. | `0.1` |  |
|
|
| <a id="gen-ai-request-seed" href="#gen-ai-request-seed">`gen_ai.request.seed`</a> | int | Requests with same seed value more likely to return same result. | `100` |  |
|
|
| <a id="gen-ai-request-stop-sequences" href="#gen-ai-request-stop-sequences">`gen_ai.request.stop_sequences`</a> | string[] | List of sequences that the model will use to stop generating further tokens. | `["forest", "lived"]` |  |
|
|
| <a id="gen-ai-request-temperature" href="#gen-ai-request-temperature">`gen_ai.request.temperature`</a> | double | The temperature setting for the GenAI request. | `0.0` |  |
|
|
| <a id="gen-ai-request-top-k" href="#gen-ai-request-top-k">`gen_ai.request.top_k`</a> | double | The top_k sampling setting for the GenAI request. | `1.0` |  |
|
|
| <a id="gen-ai-request-top-p" href="#gen-ai-request-top-p">`gen_ai.request.top_p`</a> | double | The top_p sampling setting for the GenAI request. | `1.0` |  |
|
|
| <a id="gen-ai-response-finish-reasons" href="#gen-ai-response-finish-reasons">`gen_ai.response.finish_reasons`</a> | string[] | Array of reasons the model stopped generating tokens, corresponding to each generation received. | `["stop"]`; `["stop", "length"]` |  |
|
|
| <a id="gen-ai-response-id" href="#gen-ai-response-id">`gen_ai.response.id`</a> | string | The unique identifier for the completion. | `chatcmpl-123` |  |
|
|
| <a id="gen-ai-response-model" href="#gen-ai-response-model">`gen_ai.response.model`</a> | string | The name of the model that generated the response. | `gpt-4-0613` |  |
|
|
| <a id="gen-ai-token-type" href="#gen-ai-token-type">`gen_ai.token.type`</a> | string | The type of token being counted. | `input`; `output` |  |
|
|
| <a id="gen-ai-tool-call-id" href="#gen-ai-tool-call-id">`gen_ai.tool.call.id`</a> | string | The tool call identifier. | `call_mszuSIzqtI65i1wAUOE8w5H4` |  |
|
|
| <a id="gen-ai-tool-description" href="#gen-ai-tool-description">`gen_ai.tool.description`</a> | string | The tool description. | `Multiply two numbers` |  |
|
|
| <a id="gen-ai-tool-name" href="#gen-ai-tool-name">`gen_ai.tool.name`</a> | string | Name of the tool utilized by the agent. | `Flights` |  |
|
|
| <a id="gen-ai-tool-type" href="#gen-ai-tool-type">`gen_ai.tool.type`</a> | string | Type of the tool utilized by the agent [6] | `function`; `extension`; `datastore` |  |
|
|
| <a id="gen-ai-usage-input-tokens" href="#gen-ai-usage-input-tokens">`gen_ai.usage.input_tokens`</a> | int | The number of tokens used in the GenAI input (prompt). | `100` |  |
|
|
| <a id="gen-ai-usage-output-tokens" href="#gen-ai-usage-output-tokens">`gen_ai.usage.output_tokens`</a> | int | The number of tokens used in the GenAI response (completion). | `180` |  |
|
|
|
|
**[1] `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.
|
|
|
|
**[2] `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.
|
|
|
|
**[3] `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.
|
|
|
|
**[4] `gen_ai.provider.name`:** The attribute SHOULD be set based on the instrumentation's best
|
|
knowledge and may differ from the actual model provider.
|
|
|
|
Multiple providers, including Azure OpenAI, Gemini, and AI hosting platforms
|
|
are accessible using the OpenAI REST API and corresponding client libraries,
|
|
but may proxy or host models from different providers.
|
|
|
|
The `gen_ai.request.model`, `gen_ai.response.model`, and `server.address`
|
|
attributes may help identify the actual system in use.
|
|
|
|
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.encoding_formats`:** In some GenAI systems the encoding formats are called embedding types. Also, some GenAI systems only accept a single format per request.
|
|
|
|
**[6] `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.
|
|
|
|
---
|
|
|
|
`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 |  |
|
|
| `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 |  |
|
|
| `text_completion` | Text completions operation such as [OpenAI Completions API (Legacy)](https://platform.openai.com/docs/api-reference/completions) |  |
|
|
|
|
---
|
|
|
|
`gen_ai.output.type` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
|
|
|
|
| Value | Description | Stability |
|
|
|---|---|---|
|
|
| `image` | Image |  |
|
|
| `json` | JSON object with known or unknown schema |  |
|
|
| `speech` | Speech |  |
|
|
| `text` | Plain text |  |
|
|
|
|
---
|
|
|
|
`gen_ai.provider.name` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
|
|
|
|
| Value | Description | Stability |
|
|
|---|---|---|
|
|
| `anthropic` | [Anthropic](https://www.anthropic.com/) |  |
|
|
| `aws.bedrock` | [AWS Bedrock](https://aws.amazon.com/bedrock) |  |
|
|
| `azure.ai.inference` | Azure AI Inference |  |
|
|
| `azure.ai.openai` | [Azure OpenAI](https://azure.microsoft.com/products/ai-services/openai-service/) |  |
|
|
| `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/) |  |
|
|
| `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.
|
|
|
|
---
|
|
|
|
`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.) |  |
|
|
|
|
## Deprecated GenAI Attributes
|
|
|
|
Describes deprecated `gen_ai` attributes.
|
|
|
|
| Attribute | Type | Description | Examples | Stability |
|
|
|---|---|---|---|---|
|
|
| <a id="gen-ai-completion" href="#gen-ai-completion">`gen_ai.completion`</a> | string | Deprecated, use Event API to report completions contents. | `[{'role': 'assistant', 'content': 'The capital of France is Paris.'}]` | <br>Removed, no replacement at this time. |
|
|
| <a id="gen-ai-prompt" href="#gen-ai-prompt">`gen_ai.prompt`</a> | string | Deprecated, use Event API to report prompt contents. | `[{'role': 'user', 'content': 'What is the capital of France?'}]` | <br>Removed, no replacement at this time. |
|
|
| <a id="gen-ai-system" href="#gen-ai-system">`gen_ai.system`</a> | string | Deprecated, use `gen_ai.provider.name` instead. | `openai`; `gcp.gen_ai`; `gcp.vertex_ai` | <br>Replaced by `gen_ai.provider.name`. |
|
|
| <a id="gen-ai-usage-completion-tokens" href="#gen-ai-usage-completion-tokens">`gen_ai.usage.completion_tokens`</a> | int | Deprecated, use `gen_ai.usage.output_tokens` instead. | `42` | <br>Replaced by `gen_ai.usage.output_tokens`. |
|
|
| <a id="gen-ai-usage-prompt-tokens" href="#gen-ai-usage-prompt-tokens">`gen_ai.usage.prompt_tokens`</a> | int | Deprecated, use `gen_ai.usage.input_tokens` instead. | `42` | <br>Replaced by `gen_ai.usage.input_tokens`. |
|
|
|
|
---
|
|
|
|
`gen_ai.system` 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 |  |
|
|
| `aws.bedrock` | AWS Bedrock |  |
|
|
| `az.ai.inference` | Azure AI Inference |  |
|
|
| `az.ai.openai` | Azure OpenAI |  |
|
|
| `azure.ai.inference` | Azure AI Inference |  |
|
|
| `azure.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] |  |
|
|
| `groq` | Groq |  |
|
|
| `ibm.watsonx.ai` | IBM Watsonx AI |  |
|
|
| `mistral_ai` | Mistral AI |  |
|
|
| `openai` | OpenAI |  |
|
|
| `perplexity` | Perplexity |  |
|
|
|
|
**[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]:** 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.'.
|
|
|
|
## Deprecated OpenAI GenAI Attributes
|
|
|
|
Describes deprecated `gen_ai.openai` attributes.
|
|
|
|
| Attribute | Type | Description | Examples | Stability |
|
|
|---|---|---|---|---|
|
|
| <a id="gen-ai-openai-request-response-format" href="#gen-ai-openai-request-response-format">`gen_ai.openai.request.response_format`</a> | string | Deprecated, use `gen_ai.output.type`. | `text`; `json_object`; `json_schema` | <br>Replaced by `gen_ai.output.type`. |
|
|
| <a id="gen-ai-openai-request-seed" href="#gen-ai-openai-request-seed">`gen_ai.openai.request.seed`</a> | int | Deprecated, use `gen_ai.request.seed`. | `100` | <br>Replaced by `gen_ai.request.seed`. |
|
|
| <a id="gen-ai-openai-request-service-tier" href="#gen-ai-openai-request-service-tier">`gen_ai.openai.request.service_tier`</a> | string | Deprecated, use `openai.request.service_tier`. | `auto`; `default` | <br>Replaced by `openai.request.service_tier`. |
|
|
| <a id="gen-ai-openai-response-service-tier" href="#gen-ai-openai-response-service-tier">`gen_ai.openai.response.service_tier`</a> | string | Deprecated, use `openai.response.service_tier`. | `scale`; `default` | <br>Replaced by `openai.response.service_tier`. |
|
|
| <a id="gen-ai-openai-response-system-fingerprint" href="#gen-ai-openai-response-system-fingerprint">`gen_ai.openai.response.system_fingerprint`</a> | string | Deprecated, use `openai.response.system_fingerprint`. | `fp_44709d6fcb` | <br>Replaced by `openai.response.system_fingerprint`. |
|
|
|
|
---
|
|
|
|
`gen_ai.openai.request.response_format` 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 |
|
|
|---|---|---|
|
|
| `json_object` | JSON object response format |  |
|
|
| `json_schema` | JSON schema response format |  |
|
|
| `text` | Text response format |  |
|
|
|
|
---
|
|
|
|
`gen_ai.openai.request.service_tier` 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 |
|
|
|---|---|---|
|
|
| `auto` | The system will utilize scale tier credits until they are exhausted. |  |
|
|
| `default` | The system will utilize the default scale tier. |  |
|