Quickstart and Installation
Relevant source files
The following files were used as context for generating this wiki page:
Pydantic Logfire is an observability platform built on OpenTelemetry that provides simplified, Python-centric insights into application behavior. It is designed to be powerful yet easy to use, offering deep integration with Pydantic validation models and standard SQL querying capabilities.
The installation and setup process involves installing the Python SDK, authenticating with the Logfire backend, and configuring the global instance to begin exporting traces, metrics, and logs. Logfire acts as an opinionated wrapper around OpenTelemetry, allowing developers to leverage existing infrastructure while benefiting from a more streamlined API.
Sources: README.md:1-25, CLAUDE.md:1-10
Installation
Logfire is distributed via PyPI and can be installed using standard Python package managers. The primary package is logfire, which includes the full SDK.
Basic Installation
To install the core SDK, use pip:
pip install logfire
Sources: README.md:33-35
Optional Dependencies
Logfire supports several optional dependency groups (extras) for specific integrations, defined in the project configuration:
| Extra | Description |
|---|---|
system-metrics | Instrumentation for system-level metrics. |
fastapi | Integration for the FastAPI web framework. |
sqlalchemy | Tracing for SQLAlchemy database queries. |
openai | Monitoring for OpenAI API calls. |
pydantic-ai | Instrumentation for Pydantic AI agents. |
aws-lambda | Specialized instrumentation for AWS Lambda environments. |
Sources: pyproject.toml:59-86
logfire-api Shim
For library authors who want to provide Logfire support without requiring users to install the full SDK, the project provides a no-op shim package called logfire-api. This package contains the same public API but performs no actions unless the full logfire package is also installed.
Sources: CLAUDE.md:46-51, logfire-api/pyproject.toml:1-20
Authentication
Before sending telemetry data to the Logfire platform, the SDK must be authenticated. This is typically handled via the Command Line Interface (CLI).
CLI Authentication Flow
The command logfire auth initiates a device-based authentication flow.
The CLI saves authenticated tokens to a local configuration file, typically located in a .logfire directory or a system-specific configuration path.
Sources: logfire/_internal/cli/init.py:236-245, logfire/_internal/cli/auth.py (referenced in __init__.py)
Managing Projects
Once authenticated, users can manage projects through the CLI:
logfire projects list: Lists projects the user has write access to.logfire projects new: Creates a new project under an organization.logfire projects use: Selects an existing project and saves its credentials tologfire_credentials.json.
Sources: logfire/_internal/cli/init.py:108-145
Initial Configuration
To start capturing telemetry, the SDK must be initialized using the logfire.configure() function. This setup configures the OpenTelemetry TracerProvider, MeterProvider, and LoggerProvider.
Global Setup
The most common usage is configuring the global Logfire instance at the entry point of the application:
import logfire
logfire.configure(
service_name='my-app',
environment='production',
token='your-project-token' # Or use LOGFIRE_TOKEN env var
)
Sources: logfire/_internal/config.py:321-360, README.md:46-55
Configuration Parameters
The configure function accepts numerous parameters, which can also be set via environment variables:
| Parameter | Env Variable | Default | Description |
|---|---|---|---|
service_name | LOGFIRE_SERVICE_NAME | unknown_service | Name of the service for grouping telemetry. |
send_to_logfire | LOGFIRE_SEND_TO_LOGFIRE | True | Whether to export data to the Logfire backend. |
token | LOGFIRE_TOKEN | None | The project write token. |
console | LOGFIRE_CONSOLE | True | Whether to enable rich console output. |
min_level | LOGFIRE_MIN_LEVEL | 0 (all) | Minimum log level to capture. |
Sources: logfire/_internal/config.py:321-410, logfire/_internal/config.py:650-680
Automated Instrumentation
Logfire provides a run command via the CLI that can automatically instrument Python scripts or modules without manual code changes for common libraries.
The logfire run Command
When executing a script with logfire run, the SDK inspects the environment and applies instrumentation for supported packages found in the environment.
logfire run my_script.py
# OR
logfire run -m my_module
Instrumentation Logic
The run command follows this internal flow:
- Configure Logfire: Calls
logfire.configure()automatically. - Collect Context: Identifies installed packages and compares them against
OTEL_INSTRUMENTATION_MAP. - Apply Instrumentation: Dynamically calls
logfire.instrument_<package>()for detected libraries (e.g.,requests,fastapi,sqlalchemy). - Execute: Runs the target script using
runpy.
Verification and Inspection
After installation and configuration, the CLI provides tools to verify the setup:
logfire whoami: Displays the currently authenticated user and the URL of the active project.logfire inspect: Analyzes the current environment and recommends additional instrumentation packages that could be installed to increase visibility.
Sources: logfire/_internal/cli/init.py:45-75, logfire/_internal/cli/init.py:98-105
Conclusion
Quickstart and Installation of Logfire is centered around the logfire Python package and its companion CLI. By combining a simple pip install with the logfire auth and logfire.configure() workflow, developers can quickly establish a robust observability pipeline. For even faster onboarding, the logfire run utility provides zero-code instrumentation for many of the most popular Python frameworks and libraries.