Skip to content

Commit 57523dd

Browse files
chore(ai-sdks): Document embedding spans
1 parent 6c2396f commit 57523dd

1 file changed

Lines changed: 36 additions & 1 deletion

File tree

‎develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx‎

Lines changed: 36 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,7 +52,7 @@ This span represents a request to an AI model or service that generates a respon
5252

5353
- Span `op` **SHOULD** be `"gen_ai.{gen_ai.operation.name}"`. (e.g. `"gen_ai.chat"`)
5454
- Span `name` **SHOULD** be `"{gen_ai.operation.name} {gen_ai.request.model}"`. (e.g. `"chat o3-mini"`)
55-
- Attribute `gen_ai.operation.name` **MUST** be `"chat"`, `"embeddings"`, `"generate_content"` or `"text_completion"`.
55+
- Attribute `gen_ai.operation.name` **MUST** be `"chat"`, `"generate_content"` or `"text_completion"`.
5656
- Attribute `gen_ai.provider.name` **MUST** be the Generative AI product as identified by the client or server instrumentation. (e.g. `"openai"`)
5757
- Attribute `gen_ai.request.model` **MUST** be the requested model. (e.g. `"gpt-4o"`)
5858
- Attribute `gen_ai.response.model` **MUST** be the concrete response model. (e.g. `"gpt-4o-2024-08-06"`)
@@ -111,6 +111,41 @@ Additional attributes on the span:
111111
- **[2]:** Cached tokens are a subset of input tokens; `gen_ai.usage.input_tokens` includes `gen_ai.usage.cache_read.input_tokens`.
112112
- **[3]:** Reasoning tokens are a subset of output tokens; `gen_ai.usage.output_tokens` includes `gen_ai.usage.reasoning.output_tokens`.
113113

114+
## Embedding Span
115+
116+
This span represents a request to a provider to encode input into numeric vector embeddings.
117+
118+
- Span `op` **SHOULD** be `"gen_ai.embeddings"`.
119+
- Span `name` **SHOULD** be `"embeddings {gen_ai.request.model}"`. (e.g. `"embeddings text-embedding-3-small"`)
120+
- Attribute `gen_ai.operation.name` **MUST** be `"embeddings"`.
121+
- Attribute `gen_ai.provider.name` **MUST** be the Generative AI product as identified by the client or server instrumentation. (e.g. `"openai"`)
122+
- Attribute `gen_ai.request.model` **MUST** be the requested model. (e.g. `"text-embedding-3-small"`)
123+
- Attribute `gen_ai.response.model` **MUST** be the concrete response model. (e.g. `"text-embedding-3-small-001"`)
124+
- If the request originates from an agent, the `gen_ai.agent.name` attribute **SHOULD** be set to the name of the agent. (e.g. `"Weather Agent"`)
125+
- If relevant, the `gen_ai.pipeline.name` attribute **SHOULD** be set to the name of the AI workflow, pipeline or chain within which the agent operates. (e.g. `"weather-pipeline"`)
126+
127+
Additional attributes on the span:
128+
129+
### Request Data
130+
131+
| Attribute | Type | Description | Example |
132+
| :-------------------------------- | :----- | :------------------------------------------------ | :--------------------------------------------- |
133+
| `gen_ai.embeddings.input` | string | Input to embed. | `'{"type": "text", "value": "Hello, world!"}'` |
134+
| `gen_ai.request.encoding_formats` | string | The encoding format requested for the embeddings. | `"base64"` |
135+
136+
### Response Data
137+
138+
| Attribute | Type | Description | Example |
139+
| :---------------------------------- | :----- | :----------------------------------------- | :------------- |
140+
| `gen_ai.response.id` | string | Unique identifier for the completion. | `"emb_abc123"` |
141+
| `gen_ai.embeddings.dimension.count` | int[] | The dimensions of the returned embeddings. | `[1536]` |
142+
143+
### Token Usage Data
144+
145+
| Attribute | Type | Description | Example |
146+
| :-------------------------- | :--- | :-------------------------------------- | :------ |
147+
| `gen_ai.usage.input_tokens` | int | The number of tokens used in the input. | `60` |
148+
114149
## Execute Tool Span
115150

116151
Describes a tool execution.

0 commit comments

Comments
 (0)