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[2, 3, 4, 5] = DEFAULT_INSTRUMENTATION_VERSION,
    use_aggregated_usage_attribute_names: bool = True,
)

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[2, 3, 4, 5] Default: DEFAULT_INSTRUMENTATION_VERSION

Version of the data format. This is unrelated to the Pydantic AI package version. Defaults to version 5. Versions 2, 3, and 4 are deprecated compatibility formats and emit a PydanticAIDeprecationWarning when used. 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.

use_aggregated_usage_attribute_names : bool Default: True

Whether to use gen_ai.aggregated_usage.* attribute names for token usage on agent run spans instead of the standard gen_ai.usage.* names. Defaults to True to prevent double-counting in observability backends that aggregate span attributes across parent and child spans. 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.

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()

instrument_model 

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

Wrap model in an InstrumentedModel so OTel/Logfire spans are emitted around requests.

Returns

Model