Pydantic AI
Send Pydantic AI agent and model spans through native OpenTelemetry instrumentation.
Pydantic AI has built-in OpenTelemetry instrumentation. Turn it on with Agent.instrument_all(), or with logfire.instrument_pydantic_ai() if you already use Logfire, and export OTLP/HTTP to telemetry.dev. Each agent run becomes a trace with spans for model requests and tool calls, and telemetry.dev computes cost from the token usage on model spans.
This guide was checked with pydantic-ai 2.57.0 and logfire 5.2.0.
Install
Pydantic AI 2.57.0 needs Python 3.11 or later. Install Pydantic AI with the OpenAI extra, the OpenTelemetry SDK, and the OTLP/HTTP exporter:
python -m pip install "pydantic-ai-slim[openai]" opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
Set the API key and exporter
Get a project API key from telemetry.dev. Then configure the exporter:
export TELEMETRY_DEV_API_KEY="td_live_..."
export OPENAI_API_KEY="your-openai-api-key"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://api.telemetry.dev"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer%20$TELEMETRY_DEV_API_KEY"
export OTEL_SERVICE_NAME="your-service-name"
export OTEL_RESOURCE_ATTRIBUTES="deployment.environment.name=production"
The OTLP exporter reads these variables and sends traces to https://api.telemetry.dev/v1/traces.
Trace an agent
Set up an OpenTelemetry tracer provider with the OTLP exporter, then instrument every Pydantic AI agent. This example sends one request to OpenAI, so OpenAI charges apply.
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.trace import set_tracer_provider
from pydantic_ai import Agent
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
set_tracer_provider(provider)
Agent.instrument_all()
agent = Agent("openai:gpt-5.2")
result = agent.run_sync("What is the capital of France?")
print(result.output)
The OpenTelemetry SDK flushes the batch when the script exits, so short scripts send their spans too.
Use Logfire instead
If Logfire already sets up OpenTelemetry in your app, keep it and turn off sending to Logfire’s own backend:
import logfire
logfire.configure(send_to_logfire=False)
logfire.instrument_pydantic_ai()
Logfire’s exporter reads the same OTEL_EXPORTER_OTLP_* variables. Remove send_to_logfire=False to send data to both Logfire and telemetry.dev.
Already exporting OTLP/HTTP
If your app already has a tracer provider with an OTLP/HTTP exporter, keep that code and set only the environment variables above. Then call Agent.instrument_all() at startup, or keep logfire.instrument_pydantic_ai().
Check the trace
Run the script and open Traces in your project. An agent run contains:
| Span | What it is |
|---|---|
invoke_agent {agent name} |
The agent run |
chat {model} |
One span per model request, with model, provider, messages, and token usage |
execute_tool {tool name} |
One span per tool call |
The agent run span reports the run’s total usage under gen_ai.aggregated_usage.*, which telemetry.dev does not add to trace totals. Only the chat spans’ gen_ai.usage.* counts, so a run’s tokens are counted once. This is the default in Pydantic AI 2.57.0. If an earlier version puts the run total on the agent span under gen_ai.usage.*, pass InstrumentationSettings(use_aggregated_usage_attribute_names=True) to Agent.instrument_all() if your version has that option.
Control captured content
By default, Pydantic AI exports full content: prompts, responses, message history, tool arguments and results, final outputs, model request parameters, and any binary content in messages. To capture less, turn off message content and model request parameters:
from pydantic_ai import Agent, InstrumentationSettings
Agent.instrument_all(
InstrumentationSettings(
include_content=False,
include_model_request_parameters=False,
)
)
This captures less content, but it does not reduce spans to metadata only:
include_content=Falseleaves out prompts, responses, tool payloads, structured-output validation details, andModelRetryfeedback. Message structure, such as roles and part types, is kept.include_model_request_parameters=Falseleaves out themodel_request_parametersattribute.- With both off, tool definitions (
gen_ai.tool.definitions), agent descriptions, run metadata, standardgen_ai.request.*settings, and exception types can still be exported.
To keep text but drop inline binary data, use InstrumentationSettings(include_binary_content=False). Binary content nested inside your own Pydantic model or dataclass is still recorded in full.
What telemetry.dev reads
Pydantic AI follows the OpenTelemetry GenAI semantic conventions, which telemetry.dev reads directly:
- Operation from
gen_ai.operation.name:invoke_agent,chat, orexecute_tool - Tokens from
gen_ai.usage.input_tokensandgen_ai.usage.output_tokensonchatspans - Model from
gen_ai.request.modelandgen_ai.response.model, and provider fromgen_ai.provider.nameorgen_ai.system - Messages from
gen_ai.input.messagesandgen_ai.output.messages - Conversation from
gen_ai.conversation.id
Troubleshooting
- No trace appears. Check that
OTEL_EXPORTER_OTLP_ENDPOINTandOTEL_EXPORTER_OTLP_HEADERSare set in the process, that the header contains your key, and that your tracer provider has the OTLP exporter attached. - The trace has no cost. telemetry.dev computes cost only for models it has pricing for. Token counts still appear.