1st round review from @lmolkova

open-telemetry · Jan 17, 2025 · 419916f · 419916f
1 parent f4c961a
commit 419916f
Showing 6 changed files with 26 additions and 54 deletions.
diff --git 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
@@ -22,9 +22,6 @@ This document defines the attributes used to describe telemetry in the context o
 | <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` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="gen-ai-agent-status" href="#gen-ai-agent-status">`gen_ai.agent.status`</a> | string | The status of the agent. | `completed`; `failed` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="gen-ai-agent-tool-call-id" href="#gen-ai-agent-tool-call-id">`gen_ai.agent.tool.call.id`</a> | string | The tool call identifier. | `call_mszuSIzqtI65i1wAUOE8w5H4` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| <a id="gen-ai-agent-tool-datastore-name" href="#gen-ai-agent-tool-datastore-name">`gen_ai.agent.tool.datastore.name`</a> | string | Name of the datastore of the tool utilized by the agent. | `pdf dstore`; `website dstore` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| <a id="gen-ai-agent-tool-extension-name" href="#gen-ai-agent-tool-extension-name">`gen_ai.agent.tool.extension.name`</a> | string | Name of the extension of the tool utilized by the agent. | `Code Interpreter` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
-| <a id="gen-ai-agent-tool-function-name" href="#gen-ai-agent-tool-function-name">`gen_ai.agent.tool.function.name`</a> | string | Name of the function of the tool utilized by the agent. | `getFlights`; `getWeather` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="gen-ai-agent-tool-name" href="#gen-ai-agent-tool-name">`gen_ai.agent.tool.name`</a> | string | Name of the tool utilized by the agent. | `Flights` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="gen-ai-agent-tool-type" href="#gen-ai-agent-tool-type">`gen_ai.agent.tool.type`</a> | string | Type of the tool utilized by the agent. | `function`; `extension`; `datastore` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 | <a id="gen-ai-agent-tools" href="#gen-ai-agent-tools">`gen_ai.agent.tools`</a> | string[] | List of tool names available to the agent. | `["Flights", "Search", "Code"]`; `["calc"]` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |

diff --git 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
 
 <!-- toc -->
 
-- [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)
 
 <!-- tocstop -->
 
@@ -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.
@@ -153,26 +150,8 @@ Instrumentations SHOULD document the list of errors they report.
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Execute Tool Span
-
-<!-- semconv span.gen_ai.client.execute_tool -->
-<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
-<!-- see templates/registry/markdown/snippet.md.j2 -->
-<!-- prettier-ignore-start -->
-<!-- markdownlint-capture -->
-<!-- markdownlint-disable -->
-
-| 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
 
-<!-- markdownlint-restore -->
-<!-- prettier-ignore-end -->
-<!-- END AUTOGENERATED TEXT -->
-<!-- endsemconv -->
+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
@@ -12,6 +12,7 @@ linkTitle: Generative AI traces
 
 - [Name](#name)
 - [GenAI attributes](#genai-attributes)
+- [Execute Tool Span](#execute-tool-span)
 - [Capturing inputs and outputs](#capturing-inputs-and-outputs)
 
 <!-- tocstop -->
@@ -139,6 +140,25 @@ Instrumentations SHOULD document the list of errors they report.
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
+## Execute Tool Span
+
+<!-- semconv span.gen_ai.client.execute_tool -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`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) |
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
 ## 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
@@ -227,21 +227,6 @@ groups:
         type: string
         brief: Type of the tool utilized by the agent.
         examples: ['function', 'extension', 'datastore']
-      - id: gen_ai.agent.tool.function.name
-        stability: experimental
-        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
-        type: string
-        brief: Name of the extension of the tool utilized by the agent.
-        examples: ['Code Interpreter']
-      - id: gen_ai.agent.tool.datastore.name
-        stability: experimental
-        type: string
-        brief: Name of the datastore of the tool utilized by the agent.
-        examples: ['pdf dstore', 'website dstore']
       - id: gen_ai.operation.name
         stability: experimental
         type:

diff --git a/model/gen-ai/spans.yaml b/model/gen-ai/spans.yaml
@@ -182,12 +182,3 @@ groups:
       - ref: gen_ai.agent.tool.call.id
         requirement_level:
           recommended: if available
-      - ref: gen_ai.agent.tool.function.name
-        requirement_level:
-          conditionally_required: If provided by the tool.
-      - ref: gen_ai.agent.tool.extension.name
-        requirement_level:
-          conditionally_required: If provided by the tool.
-      - ref: gen_ai.agent.tool.datastore.name
-        requirement_level:
-          conditionally_required: If provided by the tool.