logfire

Logfire

Pydantic Logfire を使用した、Python 向けの構造化オブザーバビリティです。すばやくセットアップでき、強力な機能を備え、OpenTelemetry に対応しています。

クイックスタート

uv pip install logfire

import logfire

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

基本パターン

1. サービス設定

起動時に必ずサービスのメタデータを設定します。

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. フレームワークの計装

クライアントやアプリを作成する前にフレームワークを計装します。

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. ログレベルと構造化ログ

# 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. 手動スパン

# 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. カスタムメトリクス

# 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 のオブザーバビリティ

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 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. 機密データのスクラブ

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. 高トラフィックのサービス向けサンプリング

import logfire

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

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

10. テスト

import logfire
from logfire.testing import CaptureLogfire

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

利用可能なインテグレーション

カテゴリ	インテグレーション	方法
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()
データベース	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()
タスク	Celery	logfire.instrument_celery()
	AWS Lambda	logfire.instrument_aws_lambda()
ロギング	標準ロギング	logfire.instrument_logging()
	Structlog	logfire.instrument_structlog()
	Loguru	logfire.instrument_loguru()
	Print	logfire.instrument_print()
その他	Pydantic	logfire.instrument_pydantic()
	システムメトリクス	logfire.instrument_system_metrics()

よくある落とし穴

問題	症状	対処法
サービス名が設定されていない	UI でスパンを見つけにくい	configure() で service_name を設定する
計装のタイミングが遅い	スパンが記録されない	クライアントを作成する前に configure() を呼び出す
カーディナリティの高い属性	ストレージの使用量が急増する	属性にはペイロード全体ではなく ID を使う
コンソールのノイズ	ログが stdout を汚す	本番環境では console=False を設定する

参考資料

• 設定オプション - configure() の全パラメーター
• インテグレーションガイド - フレームワーク別のセットアップ
• メトリクスガイド - カウンター、ゲージ、ヒストグラム、システムメトリクス
• 高度なパターン - サンプリング、スクラブ、抑制、テスト
• 落とし穴とトラブルシューティング - よくある問題と解決策
• 公式ドキュメント