SDK Architecture & OpenTelemetry Core

Relevant source files

The following files were used as context for generating this wiki page:

• logfire/_internal/main.py
• logfire/_internal/tracer.py
• logfire/_internal/metrics.py
• logfire/_internal/config.py
• CLAUDE.md
• README.md

Pydantic Logfire is an observability platform built as an opinionated wrapper around the OpenTelemetry (OTel) ecosystem. The SDK architecture is designed to provide high-level, Python-centric insights while maintaining full compatibility with OTel standards for traces, metrics, and logs. By leveraging OTel's core components, Logfire ensures interoperability with existing tooling and infrastructure while simplifying the developer experience for Python applications.

The core architecture follows a proxy pattern where Logfire-specific providers wrap standard OpenTelemetry SDK providers. This allows Logfire to intercept telemetry data for enrichment—such as Pydantic model validation analytics or automatic argument inspection—before exporting it to the Logfire backend or other OTel-compatible sinks.

Sources: README.md:16-22, CLAUDE.md:1-10

System Architecture

The SDK is organized into a public API layer and an internal implementation layer that manages the lifecycle of OpenTelemetry providers.

The diagram shows the relationship between the Logfire public API and the underlying OpenTelemetry SDK components via Proxy providers.
Sources: CLAUDE.md:16-28, logfire/_internal/config.py:450-460

Configuration and Initialization

The entry point for the SDK is the configure() function, which initializes the GLOBAL_CONFIG and sets up the OpenTelemetry environment.

Key Configuration Parameters

Parameter	Type	Description
token	str | list[str]	Project write token(s) used for authentication.
service_name	str	Name of the service, defaults to environment variable or inferred.
send_to_logfire	bool | str	Controls whether data is exported to the Logfire backend.
console	ConsoleOptions	Settings for terminal output, including styling and verbosity.
scrubbing	ScrubbingOptions	Configuration for redacting sensitive data from telemetry.

Sources: logfire/_internal/config.py:284-335, logfire/_internal/config.py:382-415

Initialization Logic

When configure() is called, the LogfireConfig object builds an OTel Resource containing system metadata (PID, runtime version, etc.) and repository information if a CodeSource is provided. It then initializes the Tracer, Meter, and Logger providers.

The flow of initialization from user call to ready state.
Sources: logfire/_internal/config.py:530-580, logfire/_internal/config.py:615-630

Core Components

Proxy Providers

To enable dynamic reconfiguration and Logfire-specific behavior, the SDK uses proxy classes for the three main OTel signals:

• ProxyTracerProvider: Wraps an SDKTracerProvider. It manages PendingSpanProcessor to handle spans that haven't finished yet.
• ProxyMeterProvider: Wraps a MeterProvider. It supports "metrics in spans" features where metric values are aggregated within active span contexts.
• ProxyLoggerProvider: Wraps an SDKLoggerProvider to bridge standard Python logging with OTel logs.

Sources: logfire/_internal/config.py:450-465, logfire/_internal/config.py:760-785, CLAUDE.md:20-22

Span Management

Tracing in Logfire is handled by the LogfireSpan class, which provides a context manager interface for manual tracing.

Sequence of operations during a manual span lifecycle.
Sources: logfire/_internal/main.py:1-50, logfire/_internal/tracer.py:1-30

Data Export and Processing

Logfire uses a specialized export pipeline to ensure high performance and reliability, particularly for Python applications.

Span Processors

1. MainSpanProcessorWrapper: Enforces data scrubbing and redacts sensitive information before the span reaches the exporter.
2. PendingSpanProcessor: Periodically exports "pending" spans to provide a live view of long-running operations.
3. DynamicBatchSpanProcessor: An optimized version of the OTel BatchSpanProcessor that adjusts batch sizes based on network conditions.
4. RemovePendingSpansExporter: Ensures that when a span finally ends, it correctly replaces its previous "pending" version in the backend.

Sources: logfire/_internal/config.py:600-615, logfire/_internal/config.py:690-715, logfire/_internal/tracer.py:100-120

Metrics Temporality

Logfire uses specific AggregationTemporality settings to ensure metrics are correctly interpreted by the backend:

• DELTA: Used for Counter and Histogram.
• CUMULATIVE: Used for UpDownCounter and Observable instruments.

Sources: logfire/_internal/config.py:93-102

Summary

The SDK Architecture & OpenTelemetry Core of Logfire provides a robust bridge between high-level developer APIs and the complex OpenTelemetry ecosystem. By utilizing a proxy-based architecture, Logfire adds value through features like pending span visibility, automatic data scrubbing, and optimized OTLP exporting, while remaining fully compatible with the broader OTel standard.