instrumentation

Logfire で計装する

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

次の場合にこのスキルを呼び出してください：

• ユーザーが「logfire を追加」「可観測性を追加」「トレースを追加」「モニタリングを追加」と依頼した場合
• ユーザーがアプリに構造化ログまたはトレースを計装したい場合（Python、JS/TS、Rust）
• ユーザーがどのような文脈でも Logfire に言及した場合
• ユーザーが「ログを追加」または「アプリの動作を確認したい」と依頼した場合
• ユーザーが 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_*() を呼び出すと、フックは登録されますが、トレースはどこにも送られません。

import logfire

# 1. Configure first - always
logfire.configure()

# 2. Instrument libraries - after configure, before app starts
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 文字列を使わず、キーワード引数と {key} プレースホルダーを使うことです。

# Correct - each {key} becomes a searchable attribute in the Logfire UI
logfire.info("Created user {user_id}", user_id=uid)
logfire.error("Payment failed {amount} {currency}", amount=100, currency="USD")

# Wrong - creates a flat string, nothing is searchable
logfire.info(f"Created user {uid}")

関連する操作をまとめ、所要時間を計測するには、スパンを使用します。

with logfire.span("Processing order {order_id}", order_id=order_id):
    items = await fetch_items(order_id)
    total = calculate_total(items)
    logfire.info("Calculated total {total}", total=total)

例外には、トレースバックを自動的に取得する logfire.exception() を使用します。

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]'
# or: uv add 'logfire[openai]' / uv add 'logfire[anthropic]'

利用可能な AI 向け追加パッケージ：pydantic-ai、openai、anthropic、litellm、dspy、google-genai。

logfire.configure()
logfire.instrument_pydantic_ai()  # captures agent runs, tool calls, LLM request/response
# or:
logfire.instrument_openai()       # captures chat completions, embeddings, token counts
logfire.instrument_anthropic()    # captures messages, token usage

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

---

JavaScript / TypeScript

インストール

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

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

# Next.js / generic
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）

// Structured attributes as second argument
logfire.info('Created user', { user_id: uid })
logfire.error('Payment failed', { amount: 100, currency: 'USD' })

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

// Error reporting
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 マクロが自動的に機能します。

// Spans
logfire::span!("processing order", order_id = order_id).in_scope(|| {
    // traced code
});

// Events
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：${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/python/logging-patterns.md（ログレベル、スパン、標準ライブラリとの統合、メトリクス、capfire テスト）および ${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/python/integrations.md（追加機能を含むインストルメンターの完全な一覧）
• JavaScript/TypeScript：${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/javascript/patterns.md（ログレベル、スパン、エラー処理、設定）および ${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/javascript/frameworks.md（Node.js、Cloudflare Workers、Next.js、Deno のセットアップ）
• Rust：${CLAUDE_PLUGIN_ROOT}/skills/instrumentation/references/rust/patterns.md（マクロ、スパン、tracing／log クレートとの統合、非同期処理、シャットダウン）