Pydantic Validation Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Pydantic Validation Integration allows Logfire to automatically instrument Pydantic models to provide deep visibility into data validation processes. By leveraging Pydantic's plugin system, Logfire captures detailed traces, metrics, and logs for every validation event, enabling developers to understand data flow and debug validation failures efficiently.
Sources: logfire/integrations/pydantic.py:1-15, README.md:18-20
Overview and Architecture
The integration operates as a Pydantic plugin that hooks into the creation of SchemaValidator objects. When a model is defined or a TypeAdapter is created, Logfire wraps the core validation methods (validate_python, validate_json, and validate_strings) with instrumentation logic. This instrumentation can record successful validations, failures due to invalid data, and unexpected exceptions.
Sources: logfire/integrations/pydantic.py:250-280, tests/test_pydantic_plugin.py:40-50
Key Components
| Component | Description |
|---|---|
LogfirePydanticPlugin | The entry point for the Pydantic plugin system, responsible for initializing validation wrappers. |
_ValidateWrapper | A decorator factory that wraps Pydantic validation methods with OpenTelemetry spans and metrics. |
PluginSettings | A TypedDict defining model-level configuration for the integration. |
validation_counter | An OpenTelemetry counter tracking the total number of validations, partitioned by success/failure and schema name. |
Sources: logfire/integrations/pydantic.py:25-35, logfire/integrations/pydantic.py:75-85, logfire/integrations/pydantic.py:245-255
Validation Data Flow
When a Pydantic model performs validation, the logic follows a specific path depending on the configured record mode.
The diagram illustrates the instrumentation branching logic based on the record setting.
Sources: logfire/integrations/pydantic.py:115-185
Configuration Options
The integration can be configured globally via logfire.configure() or on a per-model basis using plugin_settings.
Global Configuration
The PydanticPlugin dataclass holds global defaults for recording and filtering.
| Parameter | Type | Default | Description |
|---|---|---|---|
record | Literal | 'off' | Determines what to record: 'all', 'failure', 'metrics', or 'off'. |
include | set[str] | set() | Set of module/model names to specifically instrument. |
exclude | set[str] | set() | Set of module/model names to ignore. |
Sources: logfire/_internal/config.py:185-205, logfire/integrations/pydantic.py:280-290
Model-Level Settings
Specific models can override global settings using the plugin_settings argument in the class definition.
class User(BaseModel, plugin_settings={'logfire': {'record': 'all', 'tags': ['api']}}):
username: str
age: int
Sources: logfire/integrations/pydantic.py:40-50, tests/test_pydantic_plugin.py:70-80
Instrumentation Logic
Schema Name Resolution
Logfire uses a specialized function get_schema_name to identify the most relevant name for a span or metric. It prioritizes class names for models and dataclasses, and traverses recursive definitions or function-based validators to find the root type.
Sources: logfire/integrations/pydantic.py:215-240
Metrics and Spans
- Metrics: The
pydantic.validationscounter includes attributes forsuccess(bool),schema_name, andvalidation_method. - Spans: When
record='all', spans are created with the levelinfo. If aValidationErroroccurs, the span level is downgraded towarnto reflect a data issue rather than a system error. If an unexpectedExceptionoccurs, it is recorded as anerror.
Sources: logfire/integrations/pydantic.py:185-210, tests/test_pydantic_plugin.py:150-170
Implementation Details
The integration includes several internal "patches" to ensure compatibility across different Pydantic versions and to fix recursion bugs in Pydantic's PluggableSchemaValidator.
Plugin Compatibility
LogfirePydanticPlugin implements the Pydantic plugin protocol to intercept validator creation.
Sources: logfire/integrations/pydantic.py:250-275, logfire/integrations/pydantic.py:75-90
Version Handling
- For Pydantic versions
< 2.5.0, the plugin returns empty validator wrappers as the plugin API was not fully stabilized. - For versions
>= 2.5.0, it patchespydantic.plugin._schema_validator.build_wrapperto support a decorator-based API, allowing multiple plugins to coexist.
Sources: logfire/integrations/pydantic.py:255-265, logfire/integrations/pydantic.py:315-325
Summary
The Pydantic Validation Integration provides an automated way to monitor the integrity of data entering a Python application. By capturing the nuances of Pydantic validations—such as specific error counts and validation methods—into OpenTelemetry signals, it bridges the gap between raw data validation and application observability. This integration is essential for identifying patterns in invalid client requests or unexpected data transformations.
Sources: logfire/integrations/pydantic.py:1-20, README.md:18-22