Skip to content

chore(ai-sdks): Document embedding spans #20252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
alexander-alderman-webb wants to merge 4 commits into
base: master
Choose a base branch
from
Open

chore(ai-sdks): Document embedding spans #20252

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6c2396f
chore(ai-sdks): Remove requirement level from attributes
alexander-alderman-webb Oct 27, 2026
57523dd
chore(ai-sdks): Document embedding spans
alexander-alderman-webb Oct 27, 2026
f9ec3ae
Merge branch 'master' into webb/embedding-spans
alexander-alderman-webb Oct 27, 2026
2c451e4
only set what product uses
alexander-alderman-webb Oct 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion develop-docs/sdk/telemetry/traces/modules/ai-agents.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,7 +52,7 @@ This span represents a request to an AI model or service that generates a respon

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

## Embedding Span

This span represents a request to a provider to encode input into numeric vector embeddings.

- Span `op` **SHOULD** be `"gen_ai.embeddings"`.
- Span `name` **SHOULD** be `"embeddings {gen_ai.request.model}"`. (e.g. `"embeddings text-embedding-3-small"`)
- Attribute `gen_ai.operation.name` **MUST** be `"embeddings"`.
- Attribute `gen_ai.provider.name` **MUST** be the Generative AI product as identified by the client or server instrumentation. (e.g. `"openai"`)
- Attribute `gen_ai.request.model` **MUST** be the requested model. (e.g. `"text-embedding-3-small"`)
- Attribute `gen_ai.response.model` **MUST** be the concrete response model. (e.g. `"text-embedding-3-small-001"`)
Comment on lines +120 to +123

@szokeasaurusrex szokeasaurusrex Oct 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do these really need to be MUST-level requirements? E.g. what if the integration does not allow retrieving these values?

I would downgrade to SHOULD

- 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"`)
- 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"`)

Additional attributes on the span:

@szokeasaurusrex szokeasaurusrex Oct 27, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Are the MAY, SHOULD, or MUST?


| Attribute | Type | Description | Example |
| :-------------------------- | :----- | :-------------------------------------- | :--------------------------------------------- |
| `gen_ai.embeddings.input` | string | Input to embed. | `'{"type": "text", "value": "Hello, world!"}'` |
| `gen_ai.usage.input_tokens` | int | The number of tokens used in the input. | `60` |

## Execute Tool Span

Describes a tool execution.
Expand Down
Loading