Skip to content
Pydantic Docs

pydantic_ai.models.instrumented

InstrumentationSettings

Options for instrumenting models and agents with OpenTelemetry.

Used in:

See the Debugging and Monitoring guide for more info.

Methods

__init__ 
def __init__(
    tracer_provider: TracerProvider | None = None,
    meter_provider: MeterProvider | None = None,
    include_binary_content: bool = True,
    include_content: bool = True,
    version: Literal[1, 2, 3, 4, 5] = DEFAULT_INSTRUMENTATION_VERSION,
    event_mode: Literal['attributes', 'logs'] = 'attributes',
    logger_provider: LoggerProvider | None = None,
    use_aggregated_usage_attribute_names: bool = False,
)

Create instrumentation options.

Parameters

tracer_provider : TracerProvider | None Default: None

The OpenTelemetry tracer provider to use. If not provided, the global tracer provider is used. Calling logfire.configure() sets the global tracer provider, so most users don’t need this.

meter_provider : MeterProvider | None Default: None

The OpenTelemetry meter provider to use. If not provided, the global meter provider is used. Calling logfire.configure() sets the global meter provider, so most users don’t need this.

include_binary_content : bool Default: True

Whether to include binary content in the instrumentation events.

include_content : bool Default: True

Whether to include prompts, completions, and tool call arguments and responses in the instrumentation events.

version : Literal[1, 2, 3, 4, 5] Default: DEFAULT_INSTRUMENTATION_VERSION

Version of the data format. This is unrelated to the Pydantic AI package version. Version 1 is based on the legacy event-based OpenTelemetry GenAI spec and will be removed in a future release. The parameters event_mode and logger_provider are only relevant for version 1. Version 2 uses the newer OpenTelemetry GenAI spec and stores messages in the following attributes:

  • gen_ai.system_instructions for instructions passed to the agent.
  • gen_ai.input.messages and gen_ai.output.messages on model request spans.
  • pydantic_ai.all_messages on agent run spans. Version 3 is the same as version 2, with additional support for thinking tokens. Version 4 is the same as version 3, with GenAI semantic conventions for multimodal content: URL-based media uses type=‘uri’ with uri and mime_type fields (and modality for image/audio/video). Inline binary content uses type=‘blob’ with mime_type and content fields (and modality for image/audio/video). https://opentelemetry.io/docs/specs/semconv/gen-ai/non-normative/examples-llm-calls/#multimodal-inputs-example Version 5 is the same as version 4, but CallDeferred and ApprovalRequired exceptions no longer record an exception event or set the span status to ERROR — the span is left as UNSET, since deferrals are control flow, not errors.

event_mode : Literal[‘attributes’, ‘logs’] Default: 'attributes'

The mode for emitting events in version 1. If 'attributes', events are attached to the span as attributes. If 'logs', events are emitted as OpenTelemetry log-based events.

logger_provider : LoggerProvider | None Default: None

The OpenTelemetry logger provider to use. If not provided, the global logger provider is used. Calling logfire.configure() sets the global logger provider, so most users don’t need this. This is only used if event_mode='logs' and version=1.

use_aggregated_usage_attribute_names : bool Default: False

Whether to use gen_ai.aggregated_usage.* attribute names for token usage on agent run spans instead of the standard gen_ai.usage.* names. Enable this to prevent double-counting in observability backends that aggregate span attributes across parent and child spans. Defaults to False. Note: gen_ai.aggregated_usage.* is a custom namespace, not part of the OpenTelemetry Semantic Conventions. It may be updated if OTel introduces an official convention.

messages_to_otel_events 
def messages_to_otel_events(
    messages: list[ModelMessage],
    parameters: ModelRequestParameters | None = None,
) -> list[LogRecord]

Convert a list of model messages to OpenTelemetry events.

Returns

list[LogRecord] — A list of OpenTelemetry events.

Parameters

messages : list[ModelMessage]

The messages to convert.

parameters : ModelRequestParameters | None Default: None

The model request parameters.

InstrumentedModel

Bases: WrapperModel

Model which wraps another model so that requests are instrumented with OpenTelemetry.

See the Debugging and Monitoring guide for more info.

Attributes

instrumentation_settings

Instrumentation settings for this model.

Type: InstrumentationSettings Default: options or InstrumentationSettings()

CostCalculationFailedWarning

Bases: Warning

Warning raised when cost calculation fails.

instrument_model 

def instrument_model(model: Model, instrument: InstrumentationSettings | bool) -> Model

Instrument a model with OpenTelemetry/logfire.

Returns

Model