logfire

name	logfire
description	Structured observability with Pydantic Logfire and OpenTelemetry. Use when: (1) Adding traces/logs to Python APIs, (2) Instrumenting FastAPI, HTTPX, SQLAlchemy, or LLMs, (3) Setting up service metadata, (4) Configuring sampling or scrubbing sensitive data, (5) Testing observability code.

Logfire

Structured observability for Python using Pydantic Logfire - fast setup, powerful features, OpenTelemetry-compatible.

Quick Start

uv pip install logfire

import logfire

logfire.configure(service_name="my-api", service_version="1.0.0")
logfire.info("Application started")

Core Patterns

1. Service Configuration

Always set service metadata at startup:

import logfire

logfire.configure(
    service_name="backend",
    service_version="1.0.0",
    environment="production",
    console=False,           # Disable console output in production
    send_to_logfire=True,    # Send to Logfire platform
)

2. Framework Instrumentation

Instrument frameworks before creating clients/apps:

import logfire
from fastapi import FastAPI

# Configure FIRST
logfire.configure(service_name="backend")

# Then instrument
logfire.instrument_fastapi()
logfire.instrument_httpx()
logfire.instrument_sqlalchemy()

# Then create app
app = FastAPI()

3. Log Levels and Structured Logging

# All log levels (trace → fatal)
logfire.trace("Detailed trace", step=1)
logfire.debug("Debug context", variable=locals())
logfire.info("User action", action="login", success=True)
logfire.notice("Important event", event_type="milestone")
logfire.warn("Potential issue", threshold_exceeded=True)
logfire.error("Operation failed", error_code=500)
logfire.fatal("Critical failure", component="database")

# Python 3.11+ f-string magic (auto-extracts variables)
user_id = 123
status = "active"
logfire.info(f"User {user_id} status: {status}")
# Equivalent to: logfire.info("User {user_id}...", user_id=user_id, status=status)

# Exception logging with automatic traceback
try:
    risky_operation()
except Exception:
    logfire.exception("Operation failed", context="extra_info")

4. Manual Spans

# Spans for tracing operations
with logfire.span("Process order {order_id}", order_id="ORD-123"):
    logfire.info("Validating cart")
    # ... processing logic
    logfire.info("Order complete")

# Dynamic span attributes
with logfire.span("Database query") as span:
    results = execute_query()
    span.set_attribute("result_count", len(results))
    span.message = f"Query returned {len(results)} results"

5. Custom Metrics

# Counter - monotonically increasing
request_counter = logfire.metric_counter("http.requests", unit="1")
request_counter.add(1, {"endpoint": "/api/users", "method": "GET"})

# Gauge - current value
temperature = logfire.metric_gauge("temperature", unit="°C")
temperature.set(23.5)

# Histogram - distribution of values
latency = logfire.metric_histogram("request.duration", unit="ms")
latency.record(45.2, {"endpoint": "/api/data"})

6. LLM Observability

import logfire
from pydantic_ai import Agent

logfire.configure()
logfire.instrument_pydantic_ai()  # Traces all agent interactions

agent = Agent("openai:gpt-4o", system_prompt="You are helpful.")
result = agent.run_sync("Hello!")

7. Suppress Noisy Instrumentation

# Suppress entire scope (e.g., noisy library)
logfire.suppress_scopes("google.cloud.bigquery.opentelemetry_tracing")

# Suppress specific code block
with logfire.suppress_instrumentation():
    client.get("https://internal-healthcheck.local")  # Not traced

8. Sensitive Data Scrubbing

import logfire

# Add custom patterns to scrub
logfire.configure(
    scrubbing=logfire.ScrubbingOptions(
        extra_patterns=["api_key", "secret", "token"]
    )
)

# Custom callback for fine-grained control
def scrubbing_callback(match: logfire.ScrubMatch):
    if match.path == ("attributes", "safe_field"):
        return match.value  # Don't scrub this field
    return None  # Use default scrubbing

logfire.configure(
    scrubbing=logfire.ScrubbingOptions(callback=scrubbing_callback)
)

9. Sampling for High-Traffic Services

import logfire

# Sample 50% of traces
logfire.configure(sampling=logfire.SamplingOptions(head=0.5))

# Disable metrics to reduce volume
logfire.configure(metrics=False)

10. Testing

import logfire
from logfire.testing import CaptureLogfire

def test_user_creation(capfire: CaptureLogfire):
    create_user("Alice", "[e-mail]")
    
    spans = capfire.exporter.exported_spans
    assert len(spans) >= 1
    assert spans[0].attributes["user_name"] == "Alice"
    
    capfire.exporter.clear()  # Clean up for next test

Available Integrations

Category	Integration	Method
Web	FastAPI	logfire.instrument_fastapi(app)
	Starlette	logfire.instrument_starlette(app)
	Django	logfire.instrument_django()
	Flask	logfire.instrument_flask(app)
	AIOHTTP Server	logfire.instrument_aiohttp_server()
	ASGI	logfire.instrument_asgi(app)
	WSGI	logfire.instrument_wsgi(app)
HTTP	HTTPX	logfire.instrument_httpx()
	Requests	logfire.instrument_requests()
	AIOHTTP Client	logfire.instrument_aiohttp_client()
Database	SQLAlchemy	logfire.instrument_sqlalchemy(engine)
	Asyncpg	logfire.instrument_asyncpg()
	Psycopg	logfire.instrument_psycopg()
	Redis	logfire.instrument_redis()
	PyMongo	logfire.instrument_pymongo()
LLM	Pydantic AI	logfire.instrument_pydantic_ai()
	OpenAI	logfire.instrument_openai()
	Anthropic	logfire.instrument_anthropic()
	MCP	logfire.instrument_mcp()
Tasks	Celery	logfire.instrument_celery()
	AWS Lambda	logfire.instrument_aws_lambda()
Logging	Standard logging	logfire.instrument_logging()
	Structlog	logfire.instrument_structlog()
	Loguru	logfire.instrument_loguru()
	Print	logfire.instrument_print()
Other	Pydantic	logfire.instrument_pydantic()
	System Metrics	logfire.instrument_system_metrics()

Common Pitfalls

Issue	Symptom	Fix
Missing service name	Spans hard to find in UI	Set service_name in configure()
Late instrumentation	No spans captured	Call configure() before creating clients
High-cardinality attrs	Storage explosion	Use IDs, not full payloads as attributes
Console noise	Logs pollute stdout	Set console=False in production

References

• Configuration Options - All configure() parameters
• Integrations Guide - Framework-specific setup
• Metrics Guide - Counter, gauge, histogram, system metrics
• Advanced Patterns - Sampling, scrubbing, suppression, testing
• Pitfalls & Troubleshooting - Common issues and solutions
• Official Docs