instrumentModules config required.
Install
- AI SDK 7
- AI SDK 6 (legacy)
Set up
- AI SDK 7
- AI SDK 6 (legacy)
Call
TraceRoot.initialize() and register the AI SDK’s OpenTelemetry integration before your first model call:Usage
Once initialized, everygenerateText / streamText call, model call, and tool execution is captured automatically:
- AI SDK 7
- AI SDK 6 (legacy)
Verify
Run your code and confirm the trace arrives:- In the traceroot UI: Navigate to Tracing > Traces in traceroot Cloud. You should see a trace with root span
ai.generateText.functionIdsets a telemetry attribute on the span; it does not rename it. - Via the CLI: Run
traceroot traces listto inspect your recent traces from the terminal.
What gets captured
Limitations
- AI SDK 7 requires Node >= 22.
- On AI SDK 6 (legacy), each model call must explicitly set
experimental_telemetry: { isEnabled: true }.
Embedding usage
embed and embedMany record reported input-token usage on their provider-call spans. Cost is calculated when the model matches an entry in traceroot’s pricing table; otherwise, cost remains unset. The current standard pricing table has no embedding models. The operation wrapper remains in the trace, but its aggregate legacy usage is not counted again. This also applies when a batch is split across multiple provider calls.
Embedding spans without reported usage keep their token counts unset. traceroot does not estimate embedding tokens from input text or output vectors, avoiding duplicate estimates on orchestration spans whose provider-call children report the actual usage.
For AI SDK 7’s OpenTelemetry integration, use @ai-sdk/otel version 1.0.76 or newer. If you use an older version, upgrade @ai-sdk/otel: older semconv emitters can repeat usage on both the embedding wrapper and its provider calls, while the fixed emitter reports usage only on provider calls.
AI SDK 6’s built-in telemetry and AI SDK 7’s LegacyOpenTelemetry integration report raw embedding usage as ai.usage.tokens. traceroot reads this field only on provider calls identified by ai.operationId or operation.name as ai.embed.doEmbed or ai.embedMany.doEmbed. Preserve these operation attributes in custom span processors so usage can be distinguished from wrapper aggregates. If your emitter omits them, use an emitter that supplies them or switch to the current AI SDK 7 OpenTelemetry integration. Normalized OpenInference or GenAI usage fields continue to be supported independently.
Run the example
Clone the repo and run a complete agent end-to-end.TypeScript
Run the TypeScript example
Next steps
TypeScript SDK Reference
Explore the full TypeScript SDK reference and configuration options.
Cost Tracking
Learn how traceroot calculates token costs and tracks model spend.