Langfuse 学習ノート — LLM Observability¶

開始日: 2026-06-10 動機: AIE2026 の MNTSQ 講演（Langfuse セルフホスト実装記）。「リリース後にユーザーが何を聞きAIが何を返しているか見えない」問題を自分の手で解消できるようになる参考: Vault の findy_ai_engineering_summit_2026_summer.md §2-8、llm_product_clean_architecture_設計.md §5（eval駆動）写経教材: lectures/langfuse_basics/ — STEP 1〜4 に対応する 6 例（OpenAI ドロップイン・score・session/user メタデータ含む。このフォルダの s01/s02 は Anthropic SDK 版）

学習ロードマップ¶

[x] STEP 0: 環境 — Langfuse Cloud Hobby（無料・月5万units・2ユーザー・保持30日）でアカウント作成、pk-lf/sk-lf キーを .env へ
[x] STEP 1: 基本トレース（s01_basic_trace.py / lectures/langfuse_basics ex01〜03 で実施）— @observe でルートトレース、@observe(as_type="generation") でLLM呼び出し、update_current_generation で model/usage を付与、flush() で送信。OpenAI ドロップイン（from langfuse.openai import OpenAI）も確認
[x] STEP 2: ネスト構造（s02_pipeline_trace.py / lectures/langfuse_basics ex04 で実施）— 検索(span)→生成(generation)→検証(span) の階層トレース。「どの段で遅い/失敗した」が見える状態を作る。空振りトレースとの見比べも実施
[ ] STEP 3: ローカルセルフホスト — git clone https://github.com/langfuse/langfuse && docker compose up -d（MNTSQ講演のTips。本番AWS構成はEFSコスト12倍増の罠に注意 = ClickHouse は EBS か Cloud）
[x] STEP 4: スコア/フィードバック（lectures/langfuse_basics ex05・ex06 で実施）— score_current_trace()（内側）/ create_score(trace_id=)（外側）で👍👎を記録、propagate_attributes() で user_id / session_id / tags を刻んで「探せるトレース」にする。Users / Sessions / Scores 画面まで一周
[ ] STEP 5: LLM-as-a-Judge — オンライン評価で「デグレに最速で気づく守り」を作る（MNTSQの今後やりたいこと、を先回りで試す）
[ ] STEP 6: 自分のプロジェクトへ適用 — temporal-workflows の Claude API 呼び出しにトレースを仕込む

メモ¶

Langfuse Python SDK v3 の基本形¶

from langfuse import observe, get_client
@observe() = span、@observe(as_type="generation") = LLM呼び出し
デコレータのネスト = トレースの階層。関数構造がそのまま可視化される
スクリプトでは終了前に langfuse.flush() 必須（バッファ送信）

料金の要点（2026-06 時点）¶

Cloud Hobby: 無料、5万units/月、2ユーザー、30日保持 → 個人学習はこれで十分
Core $29/月（10万units込み、超過 $8/10万）
セルフホストは無料（OSS）。必須コンポーネントに ClickHouse

ハマりポイント（先人の知見）¶

EFS×ClickHouse はコスト爆発（MNTSQ: 1→4月で12倍、Read/Writeが96%）
IAM Identity Center は非対応 → Cognito を SAML→OIDC 変換で挟む
トレースIDは自動生成に任せず、アプリDB主キーを渡すと問い合わせ対応が一気に楽になる

作成: 2026-06-10 ／最終更新: 2026-06-12