Telemetry
The AI SDK uses OpenTelemetry to collect telemetry data. OpenTelemetry is an open-source observability framework designed to provide standardized instrumentation for collecting telemetry data.
Check out the AI SDK Observability Integrations to see providers that offer monitoring and tracing for AI SDK applications.
Enabling telemetry
Step 1: Register the OpenTelemetry integration
OpenTelemetry collection requires the @ai-sdk/otel package. Install it and register the integration once at application startup:
Next.js
For Next.js applications, create an instrumentation.ts file in your project root and register the AI SDK telemetry integration alongside your OpenTelemetry provider setup:
See the Next.js OpenTelemetry guide for more details on setting up OpenTelemetry in Next.js.
For Node.js applications (without Next.js), register the integration at the top level of your entry file.
Step 2: Enabling Telemetry
Once a telemetry integration is registered, supported AI SDK calls emit
telemetry events by default. This includes text and object generation,
embeddings, reranking, speech generation, and both non-streaming and streaming
transcription.
You can still pass telemetry to attach metadata (like functionId) or to opt out of a specific call:
By default, both inputs and outputs are recorded. You can disable them by setting the recordInputs and recordOutputs options to false.
Disabling the recording of inputs and outputs can be useful for privacy, data transfer, and performance reasons. You might for example want to disable recording inputs if they contain sensitive information.
These settings filter content before lifecycle events reach telemetry integrations
and Node.js ai:telemetry subscribers. Raw provider bodies and provider metadata
are omitted when either recording option is disabled. Raw tracing span results
are also omitted in that case because they can contain both inputs and outputs.
Tracing span errors use a generic failure message.
Application lifecycle callbacks and returned results retain their full content.
OpenAI Code Interpreter and shell domain secrets, and MCP authorization and
header values, are redacted from tool definitions and object request/response
bodies before they reach telemetry integrations or tracing-channel subscribers,
including when recording is enabled. Redaction uses telemetry-only copies;
provider requests and application results retain their original values.
The OpenAI provider supplies these rules, so update @ai-sdk/openai together
with ai to use this protection. Older provider versions do not supply these
telemetry views.
For generateSpeech, input telemetry contains the source text and output
telemetry contains the generated audio byte length, media type, and format.
For transcribe and experimental_streamTranscribe, telemetry contains the
input audio byte length and media type plus the output transcript. Raw audio is
never included in telemetry events. Streaming transcription reports its final
byte length when the audio stream has been consumed and the transcription
finishes.
Custom integrations receive stable generateSpeech and transcribe
operations through onStart and onEnd. To keep the experimental API isolated,
experimental_streamTranscribe uses
experimental_onStreamTranscriptionStart and
experimental_onStreamTranscriptionEnd; all three operations report failures
through onError.
An integration that wraps or delegates to another integration must explicitly
forward the experimental streaming transcription callbacks. Forwarding only
the stable onStart and onEnd callbacks does not observe
experimental_streamTranscribe.
The built-in OpenTelemetry integrations record numeric provider usage by
default, preserving each reported unit. The modern integration uses attributes
such as gen_ai.usage.characters, gen_ai.usage.seconds, and
gen_ai.usage.input_tokens; LegacyOpenTelemetry uses the corresponding
ai.usage.* attributes. The provider-native usage object remains available to
callbacks, and can also be included as the supplemental ai.response.usage
attribute by enabling usage: true.
Provider endpoints
For completed language-model calls, providers can report the known HTTP request
endpoint. OpenTelemetry records its host as server.address and its port as
server.port on the chat span. This includes default ports (443 for HTTPS and
80 for HTTP) and works when input and output recording are disabled.
OpenAI Chat reports this information for both generateText and streamText,
including custom baseURL settings. Azure Chat and Bedrock Mantle Chat reuse
this adapter and also report their configured endpoint. Other providers leave these attributes
unset until they report their endpoint; no destination is inferred from the
provider or model name, including an unknown backend behind an intermediary.
The model-call end event's optional request.url contains only the HTTP origin.
Credentials, paths, queries, and fragments are removed before telemetry events
are emitted. The OpenTelemetry attributes contain only host and port.
Opting out
Telemetry is opt-out. To disable telemetry for a specific call, set isEnabled: false:
Not registering integrations with registerTelemetry() prevents delivery to globally registered integrations, but does not disable per-call integrations or Node.js tracing-channel subscribers. To disable telemetry events for a call, including tracing-channel events, pass telemetry: { isEnabled: false }. Apply this setting to every call if you want to opt out throughout your application.
Telemetry Metadata
You can provide a functionId to identify the function that the telemetry data is for,
and runtimeContext to include additional information in the telemetry data.
For the broader context model, see
Runtime and Tool Context.
Runtime context telemetry inclusion
runtimeContext can contain values that are useful inside your application but should not be sent to telemetry providers, such as user identifiers, tenant IDs, or credentials. Use telemetry.includeRuntimeContext to mark the top-level runtimeContext properties that should be included in telemetry:
In this example, telemetry integrations receive runtimeContext as { requestId: 'req_abc' }. Properties set to false or omitted are excluded. If telemetry.includeRuntimeContext is omitted, no runtime context properties are included. telemetry.includeRuntimeContext is supported by generateText, streamText, ToolLoopAgent, embed, embedMany, rerank, and experimental_decide.
telemetry.includeRuntimeContext only filters telemetry integrations,
including OpenTelemetry integrations. Lifecycle callbacks and returned results
still receive the full runtimeContext.
Tool context
Tool-specific context can also contain values that are useful during execution but should not be sent to telemetry providers, such as API keys or access tokens.
Use telemetry.includeToolsContext to include selected top-level properties from a tool's context in telemetry:
In this example, telemetry integrations receive toolsContext.weather and tool execution telemetry event toolContext as { defaultUnit: 'fahrenheit' }.
Properties set to false or omitted are excluded. If telemetry.includeToolsContext is omitted, no tool context properties are included. telemetry.includeToolsContext is supported by generateText, streamText, and ToolLoopAgent.
telemetry.includeToolsContext only filters telemetry integrations, including
OpenTelemetry integrations. Tool execution, lifecycle callbacks, and returned
results still receive the full tool context. See Runtime and Tool
Context for the difference
between tool execution context and telemetry event context.
Agent span names
agentSpanName controls root text/object generation span names. The strings
'modelId' (default) and 'functionId' select a naming strategy, producing
invoke_agent {modelId} or invoke_agent {telemetry.functionId}:
For a literal custom name, use a callback returning the complete span name:
The callback receives { modelId, functionId } for dynamic names. If it returns
undefined or throws, the default name is used. The 'functionId' strategy also
falls back to modelId when functionId is absent. Child span names and
attributes are unchanged.
Custom Tracer
If you want your traces to use a TracerProvider other than the one provided by the @opentelemetry/api singleton, pass a custom Tracer to the OpenTelemetry constructor:
Durable WorkflowAgent runs
The steps of a durable WorkflowAgent run (@ai-sdk/workflow) can execute in
different processes. To report the run as one invoke_agent span tree, use the
same OpenTelemetryIdGenerator instance as your tracer provider's ID generator
and sampler, and pass it to the globally registered OpenTelemetry integration:
Model calls are reported live from their durable steps, so spans started by the
provider call (for example auto-instrumented HTTP spans) nest under their chat
span. The root, step, and tool spans appear when the run ends or suspends (for
example on a tool approval), using the original event timestamps. The root
includes the run's prompt and final output, subject to recordInputs and
recordOutputs.
A preparation step captures the active parent trace and makes the run's sampling
decision once. That context is carried to subsequent steps, preserving the trace
ID, sampling decision, and trace state. By default, the bridge uses parent-based
sampling with roots enabled. To use another sampler, pass it through
new OpenTelemetryIdGenerator({ sampler: yourSampler }) and keep the bridge as
the provider's sampler. Unrelated spans use random IDs and the configured sampler.
Install this setup in every process that executes workflow steps, with integrations
registered in the same order. Without the bridge, OpenTelemetry preserves live
per-model operation traces. Other globally registered telemetry integrations receive
the recorded run lifecycle when it ends or suspends.
Telemetry Integrations
Telemetry integrations let you hook into the generation lifecycle to build custom observability — logging, analytics, DevTools, or any other monitoring system. Instead of wiring up individual callbacks on every call, you implement a Telemetry once and register it globally or pass it via telemetry.integrations.
The OpenTelemetry and LegacyOpenTelemetry from @ai-sdk/otel are the built-in integrations for collecting OpenTelemetry spans (see Enabling telemetry above).
Registering integrations globally
Use registerTelemetry to register an integration once for all AI SDK calls:
You can also register multiple integrations in a single call by passing them as additional arguments. They all receive the same lifecycle events:
Per-call integrations
You can also pass one or more integrations to individual generateText or streamText calls. When per-call integrations are provided, they replace the globally registered integrations for that call:
You can combine multiple integrations — they all receive the same lifecycle events:
Errors inside integrations are caught and do not break the generation flow.
Tracing channel
In Node.js, AI SDK telemetry lifecycle and execution events are also traced on
the ai:telemetry tracing channel.
This lets observability providers subscribe to AI SDK telemetry events without
requiring users to register a separate telemetry integration, and bind async
context across provider calls and tool executions.
Tracing-channel events follow the same per-call telemetry settings as other
telemetry integrations. Setting telemetry: { isEnabled: false } disables both
registered integrations and tracing-channel events for that call.
Building a custom integration
Implement the Telemetry interface from the ai package. All methods are optional — implement only the lifecycle events you care about:
For durable workflows, integrations normally receive recorded events after the
run ends. Events can include timestamp (Unix milliseconds); use it for span
start and end times instead of the current time. Integrations that can reconstruct
traces across processes can implement the experimental
experimental_durable.captureContext(event) hook. It runs in a preparation step
and returns a serializable DurableTelemetryContext. Live model-start events
then carry that context in event.durableContext with phase: 'live'; the
recorded operation-start event carries it with phase: 'replay'. Such integrations
should skip replayed model events to avoid duplicate spans. Returning undefined
selects live per-model operations instead, with no deferred replay to that
integration.
Available lifecycle methods
onError.Experimental decision events use the four experimental_* callbacks above.
They are not included in the stable onStart and onEnd event unions.
The event types for each method are the same as the corresponding lifecycle callbacks. See the lifecycle callbacks documentation for the full property reference of each event.
Collected Data
The @ai-sdk/otel package provides two integrations that emit different span formats.
The OpenTelemetry follows the OpenTelemetry GenAI Semantic Conventions and is the recommended integration.
The LegacyOpenTelemetry integration emits legacy AI SDK-specific spans.
GenAI Semantic Conventions
The OpenTelemetry emits spans that follow the OpenTelemetry Semantic Conventions for GenAI.
By default, attributes use the gen_ai.* prefix. Provider names are mapped to well-known values (e.g. openai, anthropic, gcp.vertex_ai).
Inference duration metric
For generateText and streamText, OpenTelemetry also records the
gen_ai.client.inference.duration
histogram in seconds, following the development GenAI semantic conventions.
Configure a global OpenTelemetry MeterProvider with a metric reader and exporter
to collect it. A TracerProvider alone does not export metrics.
Each language model call contributes one observation, including calls that fail or are cancelled. Streaming calls record the full response duration. In a workflow with multiple model calls, each call is recorded separately; local tool execution time is excluded. Each attempt of a retried model stream contributes its own observation, including failed attempts that close without a finish chunk.
The histogram includes these attributes:
gen_ai.operation.name:"chat"gen_ai.provider.name: the normalized provider namegen_ai.request.model: the requested model IDgen_ai.response.model: the response model ID, when availableerror.type: the error name for thrown errors,"AbortError"for cancellation, or"_OTHER"when a call ends with an error finish reason or an unknown error
The default bucket boundary advice is [0.01, 0.02, 0.04, 0.08, 0.16, 0.32, 0.64, 1.28, 2.56, 5.12, 10.24, 20.48, 40.96, 81.92] seconds. Your OpenTelemetry SDK
configuration can override aggregation and bucket boundaries.
Setting telemetry.isEnabled to false disables these metrics for a call.
Setting recordInputs or recordOutputs to false does not disable duration
metrics. The LegacyOpenTelemetry integration does not emit this histogram.
generateText / streamText
For generateText and streamText, the integration records 4 types of spans:
-
invoke_agent {modelId}(default root span name,INTERNAL): covers the full operation including all steps and tool calls. UseagentSpanNameto customize the name.Initial attributes:
gen_ai.operation.name:"invoke_agent"gen_ai.provider.name: the provider (e.g."openai","anthropic")gen_ai.request.model: the requested model IDgen_ai.agent.name: thefunctionIdfrom telemetry settingsgen_ai.system_instructions: system instructions formatted as a JSON array of parts (whenrecordInputsis enabled)gen_ai.input.messages: the input messages in GenAI SemConv message format (whenrecordInputsis enabled)gen_ai.request.temperature: the temperature settinggen_ai.request.max_tokens: the maximum output tokensgen_ai.request.top_p: the topP settinggen_ai.request.top_k: the topK settinggen_ai.request.frequency_penalty: the frequency penaltygen_ai.request.presence_penalty: the presence penaltygen_ai.request.stop_sequences: the stop sequencesgen_ai.request.seed: the seed value
Attributes set on finish:
gen_ai.response.finish_reasons: array of finish reasons (e.g.["stop"],["tool_call"])gen_ai.usage.input_tokens: the number of input tokens usedgen_ai.usage.output_tokens: the number of output tokens usedgen_ai.usage.cache_read.input_tokens: cached input tokens readgen_ai.usage.cache_creation.input_tokens: cached input tokens createdgen_ai.output.messages: the output in GenAI SemConv message format (whenrecordOutputsis enabled)
-
step {n}(step span,INTERNAL): one span per step, nested under the root span.nis the step number, starting at 1. It contains the model call and tool spans of that step.Initial attributes:
gen_ai.operation.name:"agent_step"
agent_stepis an AI SDK-defined custom operation name, not a well-known OpenTelemetry GenAI operation. It marks an orchestration step, while the nestedchatspan marks the model call. -
chat {modelId}(model call span,CLIENT): one span per LLM provider call, nested under the step span.Initial attributes:
gen_ai.operation.name:"chat"gen_ai.provider.name: the providergen_ai.request.model: the requested model IDgen_ai.request.temperature,gen_ai.request.max_tokens,gen_ai.request.top_p,gen_ai.request.top_k,gen_ai.request.frequency_penalty,gen_ai.request.presence_penalty,gen_ai.request.stop_sequences: request parametersgen_ai.system_instructions: instructions supplied separately from the chat history, formatted as a JSON array of parts (whenrecordInputsis enabled)gen_ai.input.messages: the prompt messages in GenAI SemConv message format, including system messages that are part of the chat history in their original order (whenrecordInputsis enabled)gen_ai.tool.definitions: the tool definitions as stringified JSON (whenrecordInputsis enabled)
Attributes set on finish:
gen_ai.response.finish_reasons: array of finish reasonsgen_ai.response.id: the response ID from the providergen_ai.response.model: the model that generated the response (may differ from the requested model)gen_ai.usage.input_tokens: input tokens used in this stepgen_ai.usage.output_tokens: output tokens used in this stepgen_ai.usage.cache_read.input_tokens: cached input tokens readgen_ai.usage.cache_creation.input_tokens: cached input tokens createdgen_ai.client.operation.duration: provider call duration, in secondsgen_ai.client.operation.time_to_first_chunk: time to the first streamed output chunk, in seconds (streaming calls only)gen_ai.client.operation.time_per_output_chunk: average time between streamed output chunks, in seconds (streaming calls with multiple output chunks only)gen_ai.output.messages: the output in GenAI SemConv message format (whenrecordOutputsis enabled)
-
execute_tool {toolName}(tool span,INTERNAL): one span per tool execution, nested under the step span. See GenAI tool call spans for details.
Deprecated object APIs (generateObject / streamObject)
generateObject and streamObject are deprecated. Use generateText and
streamText with the output property instead.
The deprecated object APIs emit the same spans as generateText/streamText, except that there is no step {n} span: the chat {modelId} span is nested directly under the root span. The root span has these additional attributes:
gen_ai.output.type:"json"
The chat {modelId} spans also include gen_ai.output.type: "json", and gen_ai.output.messages contains the generated object as a text part.
embed / embedMany
For embed and embedMany, the integration records spans with CLIENT kind:
-
embeddings {modelId}(root span): covers the full embedding operation.Initial attributes:
gen_ai.operation.name:"embeddings"gen_ai.provider.name: the providergen_ai.request.model: the requested model ID
-
embeddings {modelId}(inner span): one span per provider request, nested under the root span.embedcreates one inner span.embedManycreates one inner span per provider batch call.Initial attributes:
gen_ai.operation.name:"embeddings"gen_ai.provider.name: the providergen_ai.request.model: the model ID
Attributes set on finish:
gen_ai.usage.input_tokens: the number of tokens used
Usage is recorded only on inner provider-request spans. For embedMany, sum
the usage from the inner spans to get the total usage for the operation.
rerank
For rerank, the integration records spans with CLIENT kind:
-
rerank {modelId}(root span): covers the full rerank operation.Initial attributes:
gen_ai.operation.name:"rerank"gen_ai.provider.name: the providergen_ai.request.model: the requested model ID
-
rerank {modelId}(inner span): one span per provider rerank call, nested under the root span.Initial attributes:
gen_ai.operation.name:"rerank"gen_ai.provider.name: the providergen_ai.request.model: the model ID
generateSpeech / transcribe / experimental_streamTranscribe
Each call records a single CLIENT span named {operationId} {modelId}, where
operationId is ai.generateSpeech, ai.transcribe, or ai.streamTranscribe.
gen_ai.output.type:"speech"for speech generation and"text"for transcription.gen_ai.request.stream:truefor streaming transcription andfalseotherwise.gen_ai.input.messages: speech generation input text as a user message with a text part, whenrecordInputsis enabled.gen_ai.output.messages: the completed transcript as an assistant message with a text part, whenrecordOutputsis enabled. Streaming transcription records this once on completion.
The existing ai.request.text and ai.response.text attributes are also retained.
Audio byte length, media type, and output format remain in the
ai.request.audio.* and ai.response.audio.* attributes, subject to the
corresponding input/output recording controls. Raw audio is not captured, so
transcription input and speech output do not populate message attributes with
audio content or placeholder audio parts.
experimental_decide
For experimental_decide, the integration records two spans with CLIENT
kind: a decide {modelId} root span for the whole operation and one
decide {modelId} child span for decision model work, including
retries. Both include the provider and requested model with
gen_ai.operation.name: "decide". Token
usage is recorded on the child span. When decision attributes are enabled,
answers are recorded on both spans so the operation span contains its output.
decide is an AI SDK-defined custom operation name, not a well-known
OpenTelemetry GenAI operation. OpenTelemetry permits custom operation names
when no well-known value describes the operation.
OpenTelemetry's gen_ai.evaluation.result event describes the result of
evaluating a GenAI output for quality or other characteristics. In contrast,
experimental_decide can use arbitrary JSON state for classification,
routing, scoring, and similar tasks. The integration therefore does not emit a
gen_ai.evaluation.result event.
Decision state, questions, and answers also do not have applicable GenAI
semantic-convention attributes. Enable the experimental_decision
supplemental option to record them under AI SDK-specific
ai.decision.* attributes.
GenAI span details
GenAI message format
The gen_ai.input.messages and gen_ai.output.messages attributes follow the OpenTelemetry GenAI Semantic Conventions message format.
Messages are JSON arrays of objects with a role and a parts array. Each part has a type and type-specific fields:
text:{ type: "text", content: "..." }reasoning:{ type: "reasoning", content: "..." }tool_call:{ type: "tool_call", id: "...", name: "...", arguments: ... }tool_call_response:{ type: "tool_call_response", id: "...", response: ... }blob:{ type: "blob", modality: "image"|"video"|"audio", mime_type: "...", content: "..." }(base64-encoded)uri:{ type: "uri", modality: "image"|"video"|"audio", mime_type: "...", uri: "..." }(for URL-based files)
Output messages also include a finish_reason field (e.g. "stop", "tool_call", "length", "content_filter").
Instructions supplied through instructions (or the deprecated system option) are recorded separately in gen_ai.system_instructions as a JSON array of { type: "text", content: "..." } parts. System messages supplied as chat history with allowSystemInMessages remain in gen_ai.input.messages in their original positions.
GenAI tool call spans
Tool call spans (execute_tool {toolName}) are nested under the step span and contain:
gen_ai.operation.name:"execute_tool"gen_ai.tool.name: the name of the toolgen_ai.tool.call.id: the tool call IDgen_ai.tool.type:"function"gen_ai.tool.call.arguments: the input arguments (stringified JSON, whenrecordInputsis enabled)gen_ai.execute_tool.duration: the tool execution duration, in secondsgen_ai.tool.call.result: the output result (stringified JSON, whenrecordOutputsis enabled). Only set when the tool call succeeds.
Custom OpenTelemetry span attributes
Use enrichSpan to add custom attributes to spans created by the
OpenTelemetry integration. This is useful when an observability backend needs
vendor-specific attributes that are not AI SDK-owned semantics.
The callback runs when each span is created and receives:
spanType: the type of span being created (operation,step,languageModel,tool,embedding,reranking, orexperimental_decision).operationId: the AI SDK operation ID for the current call, such asai.generateTextorai.streamText.callId: the unique ID for the current AI SDK call.runtimeContext: the telemetry-filtered runtime context for text generation, embedding, reranking, and decision spans. Text generation spans also reflect updates fromprepareStep.
Custom attributes are merged with AI SDK attributes on the span. AI SDK-owned attributes take precedence when a custom attribute uses the same key.
telemetry.includeRuntimeContext is applied before telemetry integrations receive
runtimeContext, so custom span enrichment only receives top-level runtime context
properties explicitly set to true. If the option is omitted, no runtime context
properties are included.
Embedding and reranking operations can share the same runtime context with text generation to attribute their spans to the same application request:
A globally registered OpenTelemetry({ enrichSpan }) integration receives
{ requestId: 'req_abc' } for the operation span and its embedding model span.
The same applies to every chunk in embedMany and to the operation and model
spans in rerank. The onStart and onEnd callbacks receive the full context.
Supplemental AI SDK attributes on OpenTelemetry spans
The GenAI semantic conventions cover the core model, prompt, response, tool call, and usage data. You can opt into additional AI SDK-specific attributes for data that is not represented by GenAI semantics:
This does not create additional AI SDK-specific spans such as ai.generateText, ai.generateText.doGenerate, or ai.toolCall. Instead, it adds only the selected supplemental attributes to the spans emitted by OpenTelemetry, such as the default root span invoke_agent {modelId}, step {n}, chat {modelId}, and execute_tool {toolName}.
All supplemental attributes are disabled by default. Enable only the data you want to collect:
The available options are:
usage: detailed usage attributes that are not covered by GenAI usage attributes, such as uncached input tokens and output text/reasoning token details.providerMetadata:ai.response.providerMetadataon operation, step, and model-call spans.embedding: embedding inputs and outputs.reranking: rerank input documents and ranking output.experimental_decision: experimental decision state, questions, and answers.runtimeContext:ai.settings.context.*.headers:ai.request.headers.*.toolChoice:ai.prompt.toolChoice.schema: object generation schema and output mode attributes.
The recordInputs and recordOutputs telemetry options are still respected for supplemental input and output attributes.
Legacy AI SDK Spans (LegacyOpenTelemetry)
The LegacyOpenTelemetry integration emits spans using AI SDK-specific ai.* prefixed attributes.
This is the legacy format. Consider migrating to the OpenTelemetry for better compatibility with observability platforms.
generateText function
generateText records 3 types of spans:
-
ai.generateText(span): the full length of the generateText call. It contains 1 or moreai.generateText.doGeneratespans. It contains the basic LLM span information and the following attributes:operation.name:ai.generateTextand the functionId that was set throughtelemetry.functionIdai.operationId:"ai.generateText"ai.prompt: the prompt that was used when callinggenerateTextai.response.text: the text that was generatedai.response.toolCalls: the tool calls that were made as part of the generation (stringified JSON)ai.response.finishReason: the reason why the generation finishedai.settings.maxOutputTokens: the maximum number of output tokens that were set
-
ai.generateText.doGenerate(span): a provider doGenerate call. It can containai.toolCallspans. It contains the call LLM span information and the following attributes:operation.name:ai.generateText.doGenerateand the functionId that was set throughtelemetry.functionIdai.operationId:"ai.generateText.doGenerate"ai.prompt.messages: the messages that were passed into the providerai.prompt.tools: array of stringified tool definitions. The serialized tools can be of typefunctionorprovider. Function tools includeFunctionToolandDynamicTooldefinitions and have aname,description(optional), andinputSchema(JSON schema). Provider tools includeProviderDefinedToolandProviderExecutedTooldefinitions and have aname,id, andargs(Record).ai.prompt.toolChoice: the stringified tool choice setting (JSON). It has atypeproperty (auto,none,required,tool), and if the type istool, atoolNameproperty with the specific tool.ai.response.text: the text that was generatedai.response.toolCalls: the tool calls that were made as part of the generation (stringified JSON)ai.response.finishReason: the reason why the generation finished
-
ai.toolCall(span): a tool call that is made as part of the generateText call. See Legacy tool call spans for more details.
streamText function
streamText records 3 types of spans and 2 types of events:
-
ai.streamText(span): the full length of the streamText call. It contains aai.streamText.doStreamspan. It contains the basic LLM span information and the following attributes:operation.name:ai.streamTextand the functionId that was set throughtelemetry.functionIdai.operationId:"ai.streamText"ai.prompt: the prompt that was used when callingstreamTextai.response.text: the text that was generatedai.response.toolCalls: the tool calls that were made as part of the generation (stringified JSON)ai.response.finishReason: the reason why the generation finishedai.settings.maxOutputTokens: the maximum number of output tokens that were set
-
ai.streamText.doStream(span): a provider doStream call. This span contains anai.stream.firstChunkevent andai.toolCallspans. It contains the call LLM span information and the following attributes:operation.name:ai.streamText.doStreamand the functionId that was set throughtelemetry.functionIdai.operationId:"ai.streamText.doStream"ai.prompt.messages: the messages that were passed into the providerai.prompt.tools: array of stringified tool definitions. The serialized tools can be of typefunctionorprovider. Function tools includeFunctionToolandDynamicTooldefinitions and have aname,description(optional), andinputSchema(JSON schema). Provider tools includeProviderDefinedToolandProviderExecutedTooldefinitions and have aname,id, andargs(Record).ai.prompt.toolChoice: the stringified tool choice setting (JSON). It has atypeproperty (auto,none,required,tool), and if the type istool, atoolNameproperty with the specific tool.ai.response.text: the text that was generatedai.response.toolCalls: the tool calls that were made as part of the generation (stringified JSON)ai.response.msToFirstChunk: the time it took to receive the first chunk in millisecondsai.response.msToFinish: the time it took to receive the finish part of the LLM stream in millisecondsai.response.avgCompletionTokensPerSecond: the average number of completion tokens per secondai.response.finishReason: the reason why the generation finished
-
ai.toolCall(span): a tool call that is made as part of the streamText call. See Legacy tool call spans for more details. -
ai.stream.firstChunk(event): an event that is emitted when the first chunk of the stream is received.ai.response.msToFirstChunk: the time it took to receive the first chunk
-
ai.stream.finish(event): an event that is emitted when the finish part of the LLM stream is received.
Deprecated object APIs
generateObject and streamObject are deprecated. Use generateText and
streamText with the output property instead.
If you still run deprecated object APIs, you will see legacy span names:
generateObject:ai.generateObject,ai.generateObject.doGeneratestreamObject:ai.streamObject,ai.streamObject.doStream,ai.stream.firstChunk
Legacy object spans include the same core metadata as other LLM spans, plus
object-specific attributes such as ai.schema.*, ai.response.object, and
ai.settings.output.
embed function
embed records 2 types of spans:
-
ai.embed(span): the full length of the embed call. It contains 1ai.embed.doEmbedspans. It contains the basic embedding span information and the following attributes:operation.name:ai.embedand the functionId that was set throughtelemetry.functionIdai.operationId:"ai.embed"ai.value: the value that was passed into theembedfunctionai.embedding: a JSON-stringified embedding
-
ai.embed.doEmbed(span): a provider doEmbed call. It contains the basic embedding span information and the following attributes:operation.name:ai.embed.doEmbedand the functionId that was set throughtelemetry.functionIdai.operationId:"ai.embed.doEmbed"ai.values: the values that were passed into the provider (array)ai.embeddings: an array of JSON-stringified embeddings
embedMany function
embedMany records 2 types of spans:
-
ai.embedMany(span): the full length of the embedMany call. It contains 1 or moreai.embedMany.doEmbedspans. It contains the basic embedding span information and the following attributes:operation.name:ai.embedManyand the functionId that was set throughtelemetry.functionIdai.operationId:"ai.embedMany"ai.values: the values that were passed into theembedManyfunctionai.embeddings: an array of JSON-stringified embedding
-
ai.embedMany.doEmbed(span): a provider doEmbed call. It contains the basic embedding span information and the following attributes:operation.name:ai.embedMany.doEmbedand the functionId that was set throughtelemetry.functionIdai.operationId:"ai.embedMany.doEmbed"ai.values: the values that were sent to the providerai.embeddings: an array of JSON-stringified embeddings for each value
Legacy span details
Basic LLM span information
Many spans that use LLMs (ai.generateText, ai.generateText.doGenerate, ai.streamText, ai.streamText.doStream) contain the following attributes:
resource.name: the functionId that was set throughtelemetry.functionIdai.model.id: the id of the modelai.model.provider: the provider of the modelai.request.headers.*: the request headers that were passed in throughheadersai.response.providerMetadata: provider specific metadata returned with the generation responseai.settings.maxRetries: the maximum number of retries that were setai.telemetry.functionId: the functionId that was set throughtelemetry.functionIdai.settings.runtimeContext.*: the runtime context that was passed in through theruntimeContextoption, filtered to top-level properties marked withtelemetry.includeRuntimeContextwhen configuredai.usage.completionTokens: the number of completion tokens that were usedai.usage.promptTokens: the number of prompt tokens that were used
Call LLM span information
Spans that correspond to individual LLM calls (ai.generateText.doGenerate, ai.streamText.doStream) contain
basic LLM span information and the following attributes:
ai.response.model: the model that was used to generate the response. This can be different from the model that was requested if the provider supports aliases.ai.response.id: the id of the response. Uses the ID from the provider when available.ai.response.timestamp: the timestamp of the response. Uses the timestamp from the provider when available.- Semantic Conventions for GenAI operations
gen_ai.system: the provider that was usedgen_ai.request.model: the model that was requestedgen_ai.request.temperature: the temperature that was setgen_ai.request.max_tokens: the maximum number of tokens that were setgen_ai.request.frequency_penalty: the frequency penalty that was setgen_ai.request.presence_penalty: the presence penalty that was setgen_ai.request.top_k: the topK parameter value that was setgen_ai.request.top_p: the topP parameter value that was setgen_ai.request.stop_sequences: the stop sequencesgen_ai.response.finish_reasons: the finish reasons that were returned by the providergen_ai.response.model: the model that was used to generate the response. This can be different from the model that was requested if the provider supports aliases.gen_ai.response.id: the id of the response. Uses the ID from the provider when available.gen_ai.usage.input_tokens: the number of prompt tokens that were usedgen_ai.usage.output_tokens: the number of completion tokens that were used
Basic embedding span information
Many spans that use embedding models (ai.embed, ai.embed.doEmbed, ai.embedMany, ai.embedMany.doEmbed) contain the following attributes:
ai.model.id: the id of the modelai.model.provider: the provider of the modelai.request.headers.*: the request headers that were passed in throughheadersai.settings.maxRetries: the maximum number of retries that were setai.telemetry.functionId: the functionId that was set throughtelemetry.functionIdai.settings.runtimeContext.*: the runtime context that was passed in through theruntimeContextoptionai.usage.tokens: the number of tokens that were usedresource.name: the functionId that was set throughtelemetry.functionId
Legacy tool call spans
Tool call spans (ai.toolCall) contain the following attributes:
operation.name:"ai.toolCall"ai.operationId:"ai.toolCall"ai.toolCall.name: the name of the toolai.toolCall.id: the id of the tool callai.toolCall.args: the input parameters of the tool callai.toolCall.result: the output result of the tool call. Only available if the tool call is successful and the result is serializable.