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,
    include_model_request_parameters: 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.

include_model_request_parameters : bool Default: True

Whether to emit the model_request_parameters span attribute on model request spans. This serializes the full ModelRequestParameters (output configuration and every tool definition, including fields that are not sent to the model such as tool metadata and, when not requested, return_schema). Defaults to True. Set to False to omit it entirely, which is useful when large tool output schemas make the attribute big enough to strain span export. The OpenTelemetry gen_ai.tool.definitions attribute (tool name, description, and parameters) is always emitted regardless of this setting.

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