Logfire でインストルメント化

このスキルを使用するタイミング

以下の場合にこのスキルを実行します：

• ユーザーが「add logfire」「add observability」「add tracing」「add monitoring」を依頼した場合
• ユーザーがアプリをストラクチャードロギングやトレーシングでインストルメント化したい場合（Python、JS/TS、または Rust）
• ユーザーが Logfire に言及している場合
• ユーザーが「add logging」またはアプリの動作を「see what my app is doing」したい場合
• ユーザーが AI/LLM 呼び出しを監視したい場合（PydanticAI、OpenAI、Anthropic）
• ユーザーが AI エージェントまたは LLM パイプラインにオブザーバビリティを追加したい場合

Logfire の仕組み

Logfire は OpenTelemetry 上に構築されたオブザーバビリティプラットフォームです。アプリケーションからトレース、ログ、メトリクスをキャプチャします。Logfire は Python、JavaScript/TypeScript、Rust ネイティブ SDK を持ち、OpenTelemetry を介した任意の言語のサポートもあります。

このスキルが存在する理由は、Claude が Logfire で微妙に間違えやすい点があるためです。特に configure() と instrument_*() 呼び出しの順序、ストラクチャードロギングの構文、インストールするべきエクストラの選択などです。これらは重要です。なぜなら、設定を間違えるとトレースが静かにドロップされるからです。

ステップ 1：言語とフレームワークを検出

プロジェクトの言語とインストルメント化可能なライブラリを特定します：

• Python：pyproject.toml または requirements.txt を読みます。インストルメント化可能な一般的なライブラリ：FastAPI、httpx、asyncpg、SQLAlchemy、psycopg、Redis、Celery、Django、Flask、requests、PydanticAI。
• JavaScript/TypeScript：package.json を読みます。一般的なフレームワーク：Express、Next.js、Fastify。また Cloudflare Workers または Deno もチェックします。
• Rust：Cargo.toml を読みます。

その後、以下の言語固有のステップに従います。

---

Python

エクストラ付きでインストール

検出されたフレームワークに対応するエクストラを付けて logfire をインストールします。インストルメント化されたライブラリごとに対応するエクストラが必要です。なければ、instrument_*() 呼び出しは実行時に欠落依存エラーで失敗します。

uv add 'logfire[fastapi,httpx,asyncpg]'

利用可能なエクストラの完全なリスト：fastapi, starlette, django, flask, httpx, requests, asyncpg, psycopg, psycopg2, sqlalchemy, redis, pymongo, mysql, sqlite3, celery, aiohttp, aws-lambda, system-metrics, litellm, dspy, google-genai。

設定とインストルメント化

ここで順序が重要です。logfire.configure() は SDK を初期化し、他のすべてより前に来る必要があります。instrument_*() 呼び出しは各ライブラリへのフックを登録します。configure() より前に instrument_*() を呼び出すと、フックは登録されますがトレースはどこにも行きません。

from fastapi import FastAPI

import logfire

app = FastAPI()

# 1. 最初に設定 - 常に
logfire.configure()

# 2. ライブラリをインストルメント化 - configure の後、アプリ起動前
logfire.instrument_fastapi(app)
logfire.instrument_httpx()
logfire.instrument_asyncpg()

配置ルール：

• logfire.configure() はアプリケーションエントリーポイント（main.py またはアプリを作成するモジュール）に記述します
• プロセスごとに 1 回 呼び出します。リクエストハンドラ内やライブラリコード内ではありません
• instrument_*() 呼び出しは configure() のすぐ後に記述します
• Web フレームワークインストルメンタ（instrument_fastapi, instrument_flask, instrument_django）はアプリインスタンスを引数として必要とします。HTTP クライアントとデータベースインストルメンタ（instrument_httpx, instrument_asyncpg）はグローバルで引数を取りません。
• Gunicorn デプロイメントの場合、モジュールレベルではなく post_fork フック内で logfire.configure() を呼び出します。各ワーカーは別のプロセスです

ストラクチャードロギング

print() と logging.*() 呼び出しを Logfire のストラクチャードロギングに置き換えます。重要なパターン：f-string を使わずに、キーワード引数で {key} プレースホルダを使用します。

import logfire

uid = 123

# 正しい - 各 {key} は Logfire UI で検索可能な属性になります
logfire.info('Created user {user_id}', user_id=uid)
logfire.error('Payment failed {amount} {currency}', amount=100, currency='USD')

# 間違い - フラットな文字列を作成し、何も検索可能ではありません
logfire.info(f'Created user {uid}')

関連操作をグループ化し期間を測定するには、スパンを使用します：

import logfire


async def process_order(order_id: int):
    ...


async def handle_order(order_id: int):
    with logfire.span('Processing order {order_id}', order_id=order_id):
        total = 100
        logfire.info('Calculated total {total}', total=total)

例外の場合は logfire.exception() を使用します。これは自動的にトレースバックをキャプチャします：

import logfire


async def process_order(order_id: int):
    ...


async def handle_order(order_id: int):
    try:
        await process_order(order_id)
    except Exception:
        logfire.exception('Failed to process order {order_id}', order_id=order_id)
        raise

AI/LLM インストルメント化（Python）

Logfire は AI ライブラリを自動的にインストルメント化し、LLM 呼び出し、トークン使用量、ツール呼び出し、エージェント実行をキャプチャします。

uv add 'logfire[pydantic-ai]'
# または: uv add 'logfire[openai]' / uv add 'logfire[anthropic]'

利用可能な AI エクストラ：pydantic-ai, openai, anthropic, litellm, dspy, google-genai。

import logfire

logfire.configure()
logfire.instrument_pydantic_ai()  # エージェント実行、ツール呼び出し、LLM リクエスト/レスポンスをキャプチャ
# または:
logfire.instrument_openai()       # チャット補完、埋め込み、トークン数をキャプチャ
logfire.instrument_anthropic()    # メッセージ、トークン使用量をキャプチャ

PydanticAI では、各エージェント実行は親スパンになり、すべてのツール呼び出しと LLM リクエストの子スパンが含まれます。

---

JavaScript / TypeScript

インストール

# Node.js
npm install @pydantic/logfire-node

# Cloudflare Workers
npm install @pydantic/logfire-cf-workers logfire

# Next.js / 汎用
npm install logfire

設定

Node.js (Express, Fastify など) - アプリの前にロードされる instrumentation.ts を作成します：

import * as logfire from '@pydantic/logfire-node'
logfire.configure()

起動コマンド：node --require ./instrumentation.js app.js

SDK は、アプリの前にロードされると一般的なライブラリを自動的にインストルメント化します。環境内で LOGFIRE_TOKEN を設定するか、configure() に token を渡します。

Cloudflare Workers - ハンドラを instrument() でラップします：

import { instrument } from '@pydantic/logfire-cf-workers'

export default instrument(handler, {
  service: { name: 'my-worker', version: '1.0.0' }
})

Next.js - OpenTelemetry エクスポート用に環境変数を設定します：

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://logfire-api.pydantic.dev/v1/traces
OTEL_EXPORTER_OTLP_HEADERS=Authorization=<your-write-token>

ストラクチャードロギング（JS/TS）

// 第 2 引数としてストラクチャード属性
logfire.info('Created user', { user_id: uid })
logfire.error('Payment failed', { amount: 100, currency: 'USD' })

// スパン
logfire.span('Processing order', { order_id }, {}, async () => {
  logfire.info('Processing step completed')
})

// エラーレポート
logfire.reportError('order processing', error)

ログレベル：trace, debug, info, notice, warn, error, fatal。

---

Rust

インストール

[dependencies]
logfire = "0.6"

設定

let shutdown_handler = logfire::configure()
    .install_panic_handler()
    .finish()?;

環境内で LOGFIRE_TOKEN を設定するか、Logfire CLI を使用してプロジェクトを選択します。

ストラクチャードロギング（Rust）

Rust SDK は tracing と opentelemetry 上に構築されています。既存の tracing マクロは自動的に機能します。

// スパン
logfire::span!("processing order", order_id = order_id).in_scope(|| {
    // トレースされたコード
});

// イベント
logfire::info!("Created user {user_id}", user_id = uid);

プログラム終了前に shutdown_handler.shutdown() を必ず呼び出してデータをフラッシュします。

---

検証

インストルメント化後、セットアップが機能することを検証します：

1. logfire auth を実行して認証を確認します（または LOGFIRE_TOKEN を設定します）
2. アプリを起動してリクエストをトリガーします
3. https://logfire.pydantic.dev/ でトレースをチェックします

トレースが表示されない場合：configure() が instrument_*() より前に呼び出されているか確認し（Python）、LOGFIRE_TOKEN が設定されているか確認し、正しいパッケージ/エクストラがインストールされているか確認します。

リファレンス

言語別に整理された詳細なパターンと統合テーブル：

• Python: ロギングパターン（ログレベル、スパン、標準ライブラリ統合、メトリクス、capfire テスト）および 統合（エクストラ付き完全なインストルメンタテーブル）
• JavaScript/TypeScript: パターン（ログレベル、スパン、エラーハンドリング、設定）および フレームワーク（Node.js、Cloudflare Workers、Next.js、Deno セットアップ）
• Rust: パターン（マクロ、スパン、tracing/log クレート統合、非同期、シャットダウン）