Logfire

一行サマリ

logfire.configure() + logfire.instrument_pydantic_ai() の 2 行を main の頭 に書くだけで、Agent run / モデル呼び出し / tool 実行 / トークン消費が OpenTelemetry トレース として記録され、Logfire ダッシュボード (または任意の OTel バックエンド) でフローを時系列に可視化できる。

ヒーロー: Agent の中身を「見える化」する

Agent が複数の tool を呼び、子 Agent に委譲し、retry がかかる ── このとき 「どこで遅い」「どれが何 token 食った」「どの tool で失敗した」 を print デバッグで追うのは現実的ではありません。Logfire は OpenTelemetry ベースで Agent の内部を可視化する標準ソリューションです。

概念: 計装ポイント 3 段階

最低限は instrument_pydantic_ai() の 1 行 で OK。HTTP レイヤまで詳しく見たいときに instrument_httpx を追加します。

コード: 3 つのパターン

パターン 1: Logfire を最小構成でセットアップ

import logfire
from pydantic_ai import Agent
from pydantic_ai.models.google import GoogleModel
 
# main.py の冒頭で 1 度だけ
logfire.configure()  # トークンは LOGFIRE_TOKEN 環境変数 or `logfire auth` で設定済み
logfire.instrument_pydantic_ai()
 
agent = Agent(GoogleModel('gemini-3-flash-preview'))
print(agent.run_sync('こんにちは').output)
# → Logfire ダッシュボードに run のトレースが届く

ポイント:

• logfire.configure() → 接続情報を読み込み、SDK を初期化
• logfire.instrument_pydantic_ai() → PydanticAI 用フックを登録
• これだけで run_sync の 入出力 / モデル名 / usage / tool 呼出 が見える

パターン 2: tool 呼出 + 子 Agent も自動的に記録される

import logfire
from pydantic_ai import Agent, RunContext
from pydantic_ai.models.google import GoogleModel
 
logfire.configure()
logfire.instrument_pydantic_ai()
 
model = GoogleModel('gemini-3-flash-preview')
child = Agent(model, instructions='短く日本語で答えて。')
 
parent = Agent(model)
 
@parent.tool
async def ask_child(ctx: RunContext, question: str) -> str:
    return (await child.run(question, usage=ctx.usage)).output
 
print(parent.run_sync('Pydantic AI の特徴を 1 文で?').output)
# → Logfire にネスト構造でトレースが届く: parent → tool ask_child → child run

特別な計装は不要。Delegation (Ch8-L01) のネスト がそのまま トレースの親子関係 として記録されます。

パターン 3: 機密データを含めない設定 + 別 OTel バックエンドへ送る

import logfire
from pydantic_ai import Agent
from pydantic_ai.models.instrumented import InstrumentationSettings
 
# プロンプト・応答を Logfire に送らない (PII 対策)
settings = InstrumentationSettings(
    include_content=False,       # prompt / completion を送らない
    include_binary_content=False, # 画像・PDF の bytes を送らない
)
Agent.instrument_all(settings)
 
# Logfire ではなく別の OTel コレクタに送りたいとき
# OTEL_EXPORTER_OTLP_ENDPOINT 環境変数 + send_to_logfire=False
logfire.configure(send_to_logfire=False)

include_content=False で 本文は送らず構造とメトリクスだけ 送る運用が、PII / 営業秘密を含むプロダクションでの定石。

観察: 何が見えるようになるか

Logfire ダッシュボードで run を開くと、典型的に以下が確認できます:

• 総レイテンシ と 各 span の所要時間 (どのモデル呼び出しが遅いか一目で判る)
• input_tokens / output_tokens の累積と内訳
• tool name / 引数 / 戻り値 (構造化された JSON 表示)
• 失敗・retry の発生 (例外スタックトレース付き)
• モデル名・プロバイダ (混在運用時に有用)

数値だけでなく、「Agent がどう考えてどの tool を呼び、どんな引数で呼んだか」 という意思決定プロセスが時系列で追えるのが最大の価値。

まとめ

• logfire.configure() + logfire.instrument_pydantic_ai() の 2 行で計装が始まる
• Agent run / モデル呼び出し / tool 実行 / Delegation のネストが トレース として可視化
• InstrumentationSettings(include_content=False) で本文を送らない PII 安全設定
• OpenTelemetry 準拠なので Datadog / Langfuse / Grafana 等にも OTEL_EXPORTER_OTLP_ENDPOINT で送れる
• 計装はプロセス起動時に 1 回だけ

次レッスンでは Pydantic Evals — Agent の品質を Case / Dataset / Evaluator で 再現可能なテストとして回す 仕組みを扱います。