Web Framework Integrations
Relevant source files
The following files were used as context for generating this wiki page:
Pydantic Logfire provides extensive, automated instrumentation for popular Python web frameworks. These integrations allow developers to capture request-response cycles, database queries, and internal application logic as OpenTelemetry-compatible traces and metrics with minimal manual configuration. By wrapping standard OpenTelemetry instrumentation, Logfire offers a simplified API for frameworks like FastAPI, Django, Flask, and Starlette.
The primary goal of these integrations is to provide "Python-centric insights," including event-loop telemetry and rich display of Python objects, while maintaining compatibility with OTel-compatible backends. Integrations are typically activated via specific instrument_<framework_name> methods or through the Logfire CLI run command.
Sources: README.md:12-25, logfire/_internal/cli/run.py:73-86
Integration Architecture
Logfire's web framework integrations function as opinionated wrappers around the standard OpenTelemetry (OTel) instrumentation ecosystem. When an integration is activated, Logfire configures the underlying OTel instrumentation to capture signals (traces, metrics, and logs) and routes them through the Logfire SDK's processing pipeline, which includes scrubbing, sampling, and console output formatting.
Core Instrumentation Logic
The system maintains a mapping between target web frameworks and their corresponding OpenTelemetry instrumentation packages.
The diagram above illustrates how Logfire acts as a configuration layer between the user's application and the underlying OpenTelemetry instrumentation packages.
Sources: logfire/_internal/cli/run.py:21-55, logfire/_internal/config.py:441-480
Supported Frameworks and Packages
Logfire supports a wide array of frameworks and protocols through both direct API calls and CLI-based auto-instrumentation.
| Framework/Package | Instrumentation Package | Logfire API Method |
|---|---|---|
| FastAPI | opentelemetry-instrumentation-fastapi | instrument_fastapi() |
| Django | opentelemetry-instrumentation-django | instrument_django() |
| Flask | opentelemetry-instrumentation-flask | instrument_flask() |
| Starlette | opentelemetry-instrumentation-starlette | instrument_starlette() |
| ASGI | opentelemetry-instrumentation-asgi | instrument_asgi() |
| WSGI | opentelemetry-instrumentation-wsgi | instrument_wsgi() |
| AIOHTTP | opentelemetry-instrumentation-aiohttp-server | instrument_aiohttp_server() |
Sources: logfire/_internal/cli/run.py:21-55, pyproject.toml:72-83, tests/test_logfire_api.py:175-190
CLI Auto-Instrumentation
The Logfire CLI provides a run command that automatically detects installed web frameworks and applies the appropriate instrumentation. This process allows developers to add observability to existing applications without modifying source code.
Instrumentation Detection Flow
The CLI inspects the current environment to identify which supported frameworks are installed and recommends missing instrumentation packages.
The sequence diagram shows the automated detection and instrumentation lifecycle during a logfire run execution.
Sources: logfire/_internal/cli/run.py:65-114, logfire/_internal/cli/run.py:246-261
Instrumentation Checklist
When running via the CLI, Logfire displays a summary panel containing:
- Instrumented Packages: Packages found and successfully instrumented (marked with ✓).
- Missing Instrumentations: Packages installed but lacking the OTel instrumentation package (marked with ☐).
- Installation Command: A suggested command (e.g.,
uv addorpip install) to install all recommended instrumentation.
Sources: logfire/_internal/cli/run.py:199-244
Configuration and Initialization
Web framework integrations rely on the global Logfire configuration established via logfire.configure(). This configuration determines where telemetry is sent and how it is processed.
Global Configuration Parameters
Key configuration elements that affect web integrations include:
service_name: Identifies the application in the Logfire dashboard. Sources: logfire/_internal/config.py:346distributed_tracing: Controls whether the integration extracts incoming trace context from HTTP headers. Sources: logfire/_internal/config.py:382scrubbing: Redacts sensitive information (e.g., passwords in request bodies) before transmission. Sources: logfire/_internal/config.py:356min_level: Filters logs and spans below a certain threshold (e.g., 'info'). Sources: logfire/_internal/config.py:353
Integration-Specific API usage
For manual integration, developers call the respective instrument function after configuring Logfire.
from fastapi import FastAPI
import logfire
app = FastAPI()
logfire.configure()
logfire.instrument_fastapi(app)
Sources: README.md:104-122, tests/test_logfire_api.py:192-195
Dependency Management
Logfire defines optional dependencies in its pyproject.toml to allow users to install only the necessary instrumentation for their chosen framework.
| Extra Group | Dependencies |
|---|---|
fastapi | opentelemetry-instrumentation-fastapi |
django | opentelemetry-instrumentation-django, opentelemetry-instrumentation-asgi |
flask | opentelemetry-instrumentation-flask |
asgi | opentelemetry-instrumentation-asgi |
wsgi | opentelemetry-instrumentation-wsgi |
Sources: pyproject.toml:72-83
Summary of Key Classes and Functions
logfire.instrument_fastapi(app, ...): Instruments a FastAPI application.logfire.instrument_asgi(app, ...): Instruments any ASGI-compliant application.logfire.instrument_wsgi(app, ...): Instruments any WSGI-compliant application.logfire._internal.cli.run.collect_instrumentation_context(exclude): Internal logic for detecting environment packages and recommendations.logfire._internal.cli.run.instrument_packages(...): Maps detected packages to their respectivelogfire.instrument_xcalls.
Sources: tests/test_logfire_api.py:175-195, logfire/_internal/cli/run.py:127-147, logfire/_internal/cli/run.py:246-258
Integrating Logfire with web frameworks provides immediate visibility into application performance and errors by leveraging the mature OpenTelemetry ecosystem combined with Pydantic-aware data processing. Whether through the automated CLI or explicit SDK calls, these integrations ensure that every request is traced and every exception is captured with full context.