diff --git a/.chloggen/1732.yaml b/.chloggen/1732.yaml index 55c8fc09d1..58b113489e 100644 --- a/.chloggen/1732.yaml +++ b/.chloggen/1732.yaml @@ -7,7 +7,7 @@ change_type: enhancement # The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) -component: genai +component: gen-ai # A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). note: Added AI Agent Semantic Convention diff --git a/docs/attributes-registry/gen-ai.md b/docs/attributes-registry/gen-ai.md index 1a83bf3f49..2a60f79439 100644 --- a/docs/attributes-registry/gen-ai.md +++ b/docs/attributes-registry/gen-ai.md @@ -20,14 +20,6 @@ This document defines the attributes used to describe telemetry in the context o | `gen_ai.agent.description` | string | Free-form description of the GenAI agent provided by the application. | `Helps with math problems`; `Generates fiction stories` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.agent.id` | string | The unique identifier of the GenAI agent. | `asst_5j66UpCpwteGg4YSxUnt7lPY` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.agent.name` | string | Human-readable name of the GenAI agent provided by the application. | `Math Tutor`; `Fiction Writer` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.agent.status` | string | The status of the agent. | `completed`; `failed` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.agent.tool.call.id` | string | The tool call identifier. | `call_mszuSIzqtI65i1wAUOE8w5H4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.agent.tool.datastore.name` | string | Name of the datastore of the tool utilized by the agent. | `pdf dstore`; `website dstore` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.agent.tool.extension.name` | string | Name of the extension of the tool utilized by the agent. | `Code Interpreter` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.agent.tool.function.name` | string | Name of the function of the tool utilized by the agent. | `getFlights`; `getWeather` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.agent.tool.name` | string | Name of the tool utilized by the agent. | `Flights` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.agent.tool.type` | string | Type of the tool utilized by the agent. | `function`; `extension`; `datastore` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `gen_ai.agent.tools` | string[] | List of tool names available to the agent. | `["Flights", "Search", "Code"]`; `["calc"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.operation.name` | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.encoding_formats` | string[] | The encoding formats requested in an embeddings operation, if specified. [2] | `["base64"]`; `["float", "binary"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.request.frequency_penalty` | double | The frequency penalty setting for the GenAI request. | `0.1` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -44,6 +36,12 @@ This document defines the attributes used to describe telemetry in the context o | `gen_ai.response.model` | string | The name of the model that generated the response. | `gpt-4-0613` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.system` | string | The Generative AI product as identified by the client or server instrumentation. [3] | `openai` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.token.type` | string | The type of token being counted. | `input`; `output` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.tool.call.id` | string | The tool call identifier. | `call_mszuSIzqtI65i1wAUOE8w5H4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.tool.datastore.name` | string | Name of the datastore of the tool utilized by the agent. | `pdf dstore`; `website dstore` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.tool.extension.name` | string | Name of the extension of the tool utilized by the agent. [4] | `Code Interpreter` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.tool.function.name` | string | Name of the function of the tool utilized by the agent. | `getFlights`; `getWeather` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.tool.name` | string | Name of the tool utilized by the agent. | `Flights` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| `gen_ai.tool.type` | string | Type of the tool utilized by the agent. [5] | `function`; `extension`; `datastore` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.usage.input_tokens` | int | The number of tokens used in the GenAI input (prompt). | `100` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | `gen_ai.usage.output_tokens` | int | The number of tokens used in the GenAI response (completion). | `180` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -63,14 +61,9 @@ attribute may help identify the actual system in use for `openai`. For custom model, a custom friendly name SHOULD be used. If none of these options apply, the `gen_ai.system` SHOULD be set to `_OTHER`. ---- - -`gen_ai.agent.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. +**[4] `gen_ai.tool.extension.name`:** You can refer to [langchain tools](https://python.langchain.com/docs/integrations/tools/) for more examples. -| Value | Description | Stability | -|---|---|---| -| `completed` | The agent has been completed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `failed` | The agent was unable to complete the task due to an error. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +**[5] `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. Function: A tool executed on the client-side, where the agent generates parameters for a predefined function, and the client executes the logic. Datastore: A tool used by the agent to access and query structured or unstructured external data for retrieval-augmented tasks or knowledge updates. --- diff --git a/docs/gen-ai/gen-ai-agent-spans.md b/docs/gen-ai/gen-ai-agent-spans.md index 6704471d86..30149f1a5f 100644 --- a/docs/gen-ai/gen-ai-agent-spans.md +++ b/docs/gen-ai/gen-ai-agent-spans.md @@ -10,9 +10,8 @@ linkTitle: Generative AI traces -- [Spans](#spans) - - [Create Agent Span](#create-agent-span) - - [Execute Tool Span](#execute-tool-span) +- [Create Agent Span](#create-agent-span) +- [Agent Execute Tool Span](#agent-execute-tool-span) @@ -24,9 +23,7 @@ It MAY be applicable to agent operations that are performed by the GenAI framewo The semantic conventions for GenAI agents extend and override the semantic conventions for [Gen AI Spans](gen-ai-spans.md). -## Spans - -### Create Agent Span +## Create Agent Span Describes GenAI agent creation and is usually applicable when working with remote agent services. @@ -45,14 +42,12 @@ Semantic conventions for individual GenAI systems and frameworks MAY specify dif | Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | |---|---|---|---|---|---| -| [`gen_ai.agent.status`](/docs/attributes-registry/gen-ai.md) | string | The status of the agent. | `completed`; `failed` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.operation.name`](/docs/attributes-registry/gen-ai.md) | string | The name of the operation being performed. [1] | `chat`; `text_completion`; `embeddings` | `Required` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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 | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | | [`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` If provided by the application. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.agent.id`](/docs/attributes-registry/gen-ai.md) | string | The unique identifier of the GenAI agent. | `asst_5j66UpCpwteGg4YSxUnt7lPY` | `Conditionally Required` if applicable. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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` If provided by the application. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.agent.tools`](/docs/attributes-registry/gen-ai.md) | string[] | List of tool names available to the agent. | `["Flights", "Search", "Code"]`; `["calc"]` | `Conditionally Required` If provided by the application. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.model`](/docs/attributes-registry/gen-ai.md) | string | The name of the GenAI model a request is being made to. [4] | `gpt-4` | `Conditionally Required` If provided by the application. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`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 appliable and if the request includes a seed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | | [`gen_ai.request.temperature`](/docs/attributes-registry/gen-ai.md) | double | The temperature setting for the GenAI request. | `0.0` | `Conditionally Required` If provided by the application. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | @@ -108,15 +103,6 @@ Instrumentations SHOULD document the list of errors they report. --- -`gen_ai.agent.status` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used. - -| Value | Description | Stability | -|---|---|---| -| `completed` | The agent has been completed | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| `failed` | The agent was unable to complete the task due to an error. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | - ---- - `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 | @@ -153,26 +139,8 @@ Instrumentations SHOULD document the list of errors they report. -### Execute Tool Span - - - - - - - - -| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | -|---|---|---|---|---|---| -| [`gen_ai.agent.tool.datastore.name`](/docs/attributes-registry/gen-ai.md) | string | Name of the datastore of the tool utilized by the agent. | `pdf dstore`; `website dstore` | `Conditionally Required` If provided by the tool. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.agent.tool.extension.name`](/docs/attributes-registry/gen-ai.md) | string | Name of the extension of the tool utilized by the agent. | `Code Interpreter` | `Conditionally Required` If provided by the tool. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.agent.tool.function.name`](/docs/attributes-registry/gen-ai.md) | string | Name of the function of the tool utilized by the agent. | `getFlights`; `getWeather` | `Conditionally Required` If provided by the tool. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.agent.tool.call.id`](/docs/attributes-registry/gen-ai.md) | string | The tool call identifier. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Recommended` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | -| [`gen_ai.agent.tool.name`](/docs/attributes-registry/gen-ai.md) | string | Name of the tool utilized by the agent. | `Flights` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +## Agent Execute Tool Span - - - - +If you are using some tools in your agent, refer to [Execute Tool Span](./gen-ai-spans.md#execute-tool-span). [DocumentStatus]: https://opentelemetry.io/docs/specs/otel/document-status diff --git a/docs/gen-ai/gen-ai-spans.md b/docs/gen-ai/gen-ai-spans.md index b0b27a46b1..d4babaac5e 100644 --- a/docs/gen-ai/gen-ai-spans.md +++ b/docs/gen-ai/gen-ai-spans.md @@ -13,6 +13,7 @@ linkTitle: Generative AI traces - [Name](#name) - [GenAI attributes](#genai-attributes) - [Capturing inputs and outputs](#capturing-inputs-and-outputs) +- [Execute Tool Span](#execute-tool-span) @@ -139,6 +140,43 @@ Instrumentations SHOULD document the list of errors they report. +## Execute Tool Span + + + + + + + + +| Attribute | Type | Description | Examples | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability | +|---|---|---|---|---|---| +| [`error.type`](/docs/attributes-registry/error.md) | string | Describes a class of error the operation ended with. [1] | `timeout`; `java.net.UnknownHostException`; `server_certificate_invalid`; `500` | `Conditionally Required` if the operation ended in an error | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | +| [`gen_ai.tool.datastore.name`](/docs/attributes-registry/gen-ai.md) | string | Name of the datastore of the tool utilized by the agent. | `pdf dstore`; `website dstore` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.tool.extension.name`](/docs/attributes-registry/gen-ai.md) | string | Name of the extension of the tool utilized by the agent. [2] | `Code Interpreter` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.tool.function.name`](/docs/attributes-registry/gen-ai.md) | string | Name of the function of the tool utilized by the agent. | `getFlights`; `getWeather` | `Conditionally Required` If available. | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.tool.call.id`](/docs/attributes-registry/gen-ai.md) | string | The tool call identifier. | `call_mszuSIzqtI65i1wAUOE8w5H4` | `Recommended` if available | ![Experimental](https://img.shields.io/badge/-experimental-blue) | +| [`gen_ai.tool.name`](/docs/attributes-registry/gen-ai.md) | string | Name of the tool utilized by the agent. | `Flights` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) | + +**[1] `error.type`:** The `error.type` SHOULD match the error code returned by the Generative AI tool 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.extension.name`:** You can refer to [langchain tools](https://python.langchain.com/docs/integrations/tools/) for more examples. + +--- + +`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. | ![Stable](https://img.shields.io/badge/-stable-lightgreen) | + + + + + + ## Capturing inputs and outputs User inputs and model responses may be recorded as events parented to GenAI operation span. See [Semantic Conventions for GenAI events](./gen-ai-events.md) for the details. diff --git a/model/gen-ai/registry.yaml b/model/gen-ai/registry.yaml index efb3294cd0..e165c1191c 100644 --- a/model/gen-ai/registry.yaml +++ b/model/gen-ai/registry.yaml @@ -178,67 +178,53 @@ groups: brief: The type of token being counted. examples: ['input', 'output'] - id: gen_ai.agent.id # alternatives: assistant (openai) - stability: experimental + stability: development type: string brief: The unique identifier of the GenAI agent. examples: ['asst_5j66UpCpwteGg4YSxUnt7lPY'] - id: gen_ai.agent.name - stability: experimental + stability: development type: string brief: Human-readable name of the GenAI agent provided by the application. examples: ["Math Tutor", "Fiction Writer"] - id: gen_ai.agent.description - stability: experimental + stability: development type: string brief: Free-form description of the GenAI agent provided by the application. examples: ["Helps with math problems", "Generates fiction stories"] - - id: gen_ai.agent.tools - stability: experimental - type: string[] - brief: List of tool names available to the agent. - examples: - - ["Flights", "Search", "Code"] - - ["calc"] - - id: gen_ai.agent.status - stability: experimental - type: - members: - - id: completed - value: "completed" - brief: 'The agent has been completed' - stability: experimental - - id: failed - value: "failed" - brief: 'The agent was unable to complete the task due to an error.' - stability: experimental - brief: The status of the agent. - - id: gen_ai.agent.tool.name - stability: experimental + - id: gen_ai.tool.name + stability: development type: string brief: Name of the tool utilized by the agent. examples: ["Flights"] - - id: gen_ai.agent.tool.call.id - stability: experimental + - id: gen_ai.tool.call.id + stability: development type: string brief: The tool call identifier. examples: ['call_mszuSIzqtI65i1wAUOE8w5H4'] - - id: gen_ai.agent.tool.type - stability: experimental + - id: gen_ai.tool.type + stability: development type: string brief: Type of the tool utilized by the agent. + note: > + Extension: A tool executed on the agent-side to directly call external APIs, bridging the gap between the agent and real-world systems. + Function: A tool executed on the client-side, where the agent generates parameters for a predefined function, and the client executes the logic. + Datastore: A tool used by the agent to access and query structured or unstructured external data for retrieval-augmented tasks or knowledge updates. examples: ['function', 'extension', 'datastore'] - - id: gen_ai.agent.tool.function.name - stability: experimental + - id: gen_ai.tool.function.name + stability: development type: string brief: Name of the function of the tool utilized by the agent. examples: ["getFlights", "getWeather"] - - id: gen_ai.agent.tool.extension.name - stability: experimental + - id: gen_ai.tool.extension.name + stability: development type: string brief: Name of the extension of the tool utilized by the agent. + note: > + You can refer to [langchain tools](https://python.langchain.com/docs/integrations/tools/) for more examples. examples: ['Code Interpreter'] - - id: gen_ai.agent.tool.datastore.name - stability: experimental + - id: gen_ai.tool.datastore.name + stability: development type: string brief: Name of the datastore of the tool utilized by the agent. examples: ['pdf dstore', 'website dstore'] diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml index 6f250e34eb..3b60b034cf 100644 --- a/model/gen-ai/spans.yaml +++ b/model/gen-ai/spans.yaml @@ -146,11 +146,6 @@ groups: - ref: gen_ai.agent.description requirement_level: conditionally_required: If provided by the application. - - ref: gen_ai.agent.tools - requirement_level: - conditionally_required: If provided by the application. - - ref: gen_ai.agent.status - requirement_level: required - ref: gen_ai.request.model requirement_level: conditionally_required: If provided by the application. @@ -177,17 +172,24 @@ groups: for the application developers to follow this semantic conventions for tool invoked by the application code. attributes: - - ref: gen_ai.agent.tool.name + - ref: gen_ai.tool.name requirement_level: recommended - - ref: gen_ai.agent.tool.call.id + - ref: gen_ai.tool.call.id requirement_level: recommended: if available - - ref: gen_ai.agent.tool.function.name + - ref: gen_ai.tool.function.name + requirement_level: + conditionally_required: If available. + - ref: gen_ai.tool.extension.name requirement_level: - conditionally_required: If provided by the tool. - - ref: gen_ai.agent.tool.extension.name + conditionally_required: If available. + - ref: gen_ai.tool.datastore.name requirement_level: - conditionally_required: If provided by the tool. - - ref: gen_ai.agent.tool.datastore.name + conditionally_required: If available. + - ref: error.type requirement_level: - conditionally_required: If provided by the tool. + conditionally_required: "if the operation ended in an error" + note: | + The `error.type` SHOULD match the error code returned by the Generative AI tool 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.