Configuration & Environment Variables

Relevant source files

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

• logfire/_internal/config.py
• logfire/_internal/config_params.py
• logfire/_internal/cli/init.py
• logfire/_internal/cli/run.py
• tests/test_configure.py
• logfire/_internal/constants.py

The configuration system in Logfire is designed to provide a flexible and robust way to initialize the SDK, manage telemetry export settings, and handle environment-specific overrides. It centralizes the management of project tokens, service identification, console output styles, and advanced OpenTelemetry (OTel) integration parameters.

The system utilizes a hierarchical approach to loading settings, prioritizing explicit function arguments passed to logfire.configure(), followed by environment variables, and finally configuration files like pyproject.toml. This ensures that developers can easily switch between local development, testing, and production environments without changing code.

Sources: logfire/_internal/config.py:258-360, logfire/_internal/config_params.py:1-20

Configuration Architecture

The core of the configuration logic resides in the LogfireConfig class and the configure function. The system manages state through a global configuration instance (GLOBAL_CONFIG) but also supports local instances for isolated environments.

Data Flow and Prioritization

The configuration follows a specific order of precedence when resolving parameter values:

1. Function Arguments: Values passed directly to the logfire.configure() function.
2. Environment Variables: Variables prefixed with LOGFIRE_ (e.g., LOGFIRE_TOKEN).
3. Config Files: Settings defined in the [tool.logfire] section of a pyproject.toml file.
4. Credentials File: Cached credentials stored in .logfire/logfire_credentials.json.

The ParamManager class is responsible for the actual retrieval and normalization of these parameters from various sources.

Sources: logfire/_internal/config.py:365-410, logfire/_internal/config_params.py:10-50, tests/test_configure.py:440-460

Key Configuration Components

1. LogfireConfig Class

The LogfireConfig class stores the final resolved state of the SDK. It manages the lifecycle of the ProxyTracerProvider, ProxyMeterProvider, and ProxyLoggerProvider.

Field	Type	Description
send_to_logfire	bool | Literal['if-token-present']	Determines if telemetry is exported to the Logfire backend.
token	str | list[str] | None	Project write tokens. Supports multiple tokens for migration.
service_name	str	The identifier for the service in the dashboard.
console	ConsoleOptions | False	Configuration for terminal output and span visualization.
scrubbing	ScrubbingOptions	Settings for redacting sensitive data from logs and spans.

Sources: logfire/_internal/config.py:530-580, tests/test_configure.py:950-980

2. Console and Visualization Options

The ConsoleOptions dataclass controls how logs and spans appear in the terminal during development.

Logfire supports three distinct span styles: simple, indented, and show-parents. The show-parents style is the default for providing hierarchical context.

Sources: logfire/_internal/config.py:155-175, tests/test_configure.py:510-530

Environment Variables Reference

Logfire utilizes a wide range of environment variables for zero-config integration, especially when using the logfire run CLI command.

Environment Variable	Description	Source
LOGFIRE_TOKEN	Project write token(s). Comma-separated for multiple.	config_params.py
LOGFIRE_API_KEY	API key for managed variables and administrative tasks.	config.py
LOGFIRE_SERVICE_NAME	Overrides the default service name.	config_params.py
LOGFIRE_ENVIRONMENT	Sets the deployment.environment.name resource attribute.	config.py
LOGFIRE_CONSOLE	Set to false to disable terminal output.	config.py
LOGFIRE_MIN_LEVEL	Minimum log level (e.g., info, debug).	config.py
LOGFIRE_IGNORE_NO_CONFIG	Suppresses warnings if configure() isn't called.	config.py

Sources: logfire/_internal/config.py:310-350, logfire/_internal/config_params.py:80-120, logfire/_internal/cli/run.py:70-100

Project Initialization and Credentials

When send_to_logfire is enabled without an explicit token, the SDK attempts to locate a credentials file or interactively initialize a project.

Credentials Lifecycle

1. Load: Checks for .logfire/logfire_credentials.json.
2. Verify: Validates the token against the /v1/info endpoint of the Logfire API.
3. Discovery: If no token exists, the CLI helps the user select an organization and create a new project.

Advanced OTel Configuration

Logfire acts as an opinionated wrapper around OpenTelemetry. It respects standard OTel environment variables while providing its own defaults optimized for the Logfire backend.

• Endpoint Resolution: Logfire automatically determines the OTLP endpoint based on the token's region (e.g., us or eu).
• Resource Attributes: It automatically populates attributes such as process.pid, process.runtime.name, and service.instance.id.
• Metric Temporality: Logfire enforces specific temporality (e.g., DELTA for Counters) required by its backend.

# Internal mapping of OTel temporality for Logfire
METRICS_PREFERRED_TEMPORALITY = {
    Counter: AggregationTemporality.DELTA,
    UpDownCounter: AggregationTemporality.CUMULATIVE,
    Histogram: AggregationTemporality.DELTA,
    # ...
}

Sources: logfire/_internal/config.py:120-140, logfire/_internal/config.py:640-700, logfire/_internal/constants.py

Managed Variables Configuration

Managed variables (remote configuration) can be configured via VariablesOptions or LocalVariablesOptions. This system allows for dynamic adjustment of application behavior without redeployment.

Option	Default	Description
block_before_first_resolve	True	Ensures variables are fetched before the app proceeds.
polling_interval	60s	Fallback interval for fetching updates if SSE fails.
instrument	True	Creates spans for variable resolution events.

Sources: logfire/_internal/config.py:230-255, logfire/_internal/config.py:990-1020

Summary

The Logfire configuration system provides a robust bridge between standard OpenTelemetry practices and Pydantic-style developer experience. By combining strict typing through dataclasses with a flexible parameter resolution strategy, it ensures that observability can be added to any Python project with minimal friction while remaining highly tunable for complex production environments.