Claude Media
Claude CodeにLangfuseプラグインを入れてセッションをトレースする
Claude Codeチュートリアル

Claude CodeにLangfuseプラグインを入れてセッションをトレースする

Langfuse公式プラグインは、フックでプロンプト・モデル生成・トークンとコスト・ツール呼び出しをLangfuseへ送ります。導入、認証情報、手動のStopフックとの違い、動かないときの確認先まで。

読了目安 約11分

Langfuse公式のプラグインを入れると、Claude CodeのセッションがそのままトレースとしてLangfuseに届きます。プロンプト、エージェントのターン、モデル生成ごとのトークン使用量とコスト、ツール呼び出しまでが一つの画面で追えます。

導入は2コマンドと認証情報の設定だけです。ここでは手順に加えて、何が送られるか、従来の手動Stopフック方式との違い、動かないときの確認先を扱います。

2コマンドで入れて、キーを設定する

マーケットプレイスを追加してから、プラグインを入れます。

claude plugin marketplace add langfuse/Claude-Observability-Plugin
claude plugin install langfuse-observability@langfuse-observability

インストール後はClaude Codeを再起動します。再起動しないと、フックが読み込まれません。

認証情報は2通りの渡し方があります。一つは、セッション内でスラッシュコマンドを打つ方法です。シェルのコマンドではない点に注意してください。

/plugin configure langfuse-observability@langfuse-observability

もう一つは、インストール時に --config で値を渡す方法です。

claude plugin install langfuse-observability@langfuse-observability \
  --config LANGFUSE_PUBLIC_KEY=pk-lf-... \
  --config LANGFUSE_SECRET_KEY=sk-lf-... \
  --config LANGFUSE_BASE_URL=https://cloud.langfuse.com

必須なのは LANGFUSE_PUBLIC_KEY と LANGFUSE_SECRET_KEY の2つです。LANGFUSE_BASE_URL を省くとEUリージョンの https://cloud.langfuse.com が使われます。キーはLangfuseのプロジェクト設定にあるAPI Keysのページで発行します。シークレットキーはファイルではなくOSのキーチェーンに保存されます。

ユーザーID、デバッグログ、画像の取り込みといった任意設定は、/plugin configure の画面に既定値つきで並びます。この設定コマンドの挙動はclaude plugin configureの解説にまとめています。

何がトレースされるか

プラグインのREADMEによると、対象は次のとおりです。

トレース対象

プラグインが拾う範囲

  • 会話の流れ

    ユーザーのプロンプトと、エージェントのターン。

  • モデル生成

    生成ごとのトークン使用量とコスト、thinkingブロック。

  • 拡張機能

    ツール呼び出し、スキル、サブエージェント。

  • 画像

    貼り付けた画像と、返ってきた画像。

マーケットプレイスのページでは、同じ内容を「モデル呼び出し、トークン使用量、レイテンシ、エージェントの実行フローを見えるようにする」と説明しています。同ページにはインストール数575と、公開元がLangfuseである表記もあります。

対象の面には線引きがあります。READMEによれば、claude CLIと、デスクトップアプリのCodeモードは対象です。Claude DesktopのChatモードはClaude Codeのフックを走らせないため、トレースされません。

手動のStopフック方式とは何が違うか

プラグインが出る前から、Langfuseのドキュメントには自分でフックスクリプトを書く手順がありました。現在のドキュメントは、冒頭で「いちばん簡単な方法はプラグイン」と案内しつつ、手動手順も残しています。両者の違いを並べると次のようになります。

観点プラグイン手動のStopフック
導入プラグイン2コマンド手動のStopフックスクリプトを ~/.claude/hooks/ に置き、~/.claude/settings.json に登録
有効化の単位プラグインプラグインを有効にした範囲手動のStopフックプロジェクトごと（TRACE_TO_LANGFUSE が "true"のときだけ）
認証情報プラグイン/plugin configure。シークレットはキーチェーン手動のStopフックプロジェクトの .claude/settings.json の env に平文
更新プラグイン手動で plugin update手動のStopフックスクリプトを自分で書き換える

手動方式では、Stopフック（Claudeの応答が終わるたびに走るフック）がトランスクリプトを読み、ターンごとにトレースへ変換します。同じセッションのターンは共通の session_id で束ねられ、Langfuse側のSessionsタブで一続きに見られます。フックの仕組みはClaude Code Hooks完全ガイドで扱っています。

手動方式で最も事故が起きやすいのは、認証情報を .claude/settings.json に書く点です。このファイルをgit管理に入れると、シークレットキーが漏れます。プラグインはキーチェーン保管なので、この経路が最初から無くなります。

前提条件の記述が2か所で違う

見落としやすいのが、必要なランタイムの書き方です。

  • プラグインのREADME: uv がPATHにあること。uv が無い環境ではPython 3.10以上の python3 と langfuse>=4.7,<5
  • Langfuseのドキュメントの冒頭: Python 3.9以上と pip install "langfuse>=4.0,<5"

後者は手動方式を想定した記述と読めますが、プラグインの案内文の直後に置かれているため、プラグインにも当てはまるように見えます。プラグインを入れるときはREADMEの条件を基準にしてください。READMEでは、uv ならフックがインラインのスクリプトメタデータからSDKを自分で入れると説明されています。

「Claude Codeを止めない」設計

READMEは、使えるランタイムが見つからないときの動きを明記しています。理由をログに書いて終了し、Claude Codeをブロックしたり遅くしたりしません。

つまりトレースが欠けても、気づかないうちに欠ける作りです。導入直後は、1メッセージ送ってLangfuseにトレースが出ることを確認しておくと安全です。

トレースが出ないときの確認順

フックの失敗理由は、ほぼすべて ~/.claude/state/langfuse_hook.log に書かれます。メッセージを1つ送ってから、末尾を読みます。

tail -n 50 ~/.claude/state/langfuse_hook.log

詳しい情報が要るときは、CC_LANGFUSE_DEBUG を有効にして冗長ログを出します。

切り分け

トレースが出ないときの切り分け

  1. Qログに新しい行が増えているか？
    答えがいいえのとき

    フックが起動していません。プラグインが無効か、使えるランタイムが無い状態です。作業しているディレクトリで claude plugin list を実行し、有効になっているかを見てください。uv は、Claude Codeを起動するアプリ側のPATHに通す必要があります。

    答えがはい
  2. Qログにエラーの理由が出ているか？
    答えがいいえのとき

    デバッグログを有効にして再現させます。キーの指定漏れや、Langfuseへの接続失敗はここで見分けられます。

    答えがはい

ログの理由に従って直す

認証エラーなら、キーとベースURLのリージョンを照らし合わせます。

claude plugin list --jsonによる棚卸しを使うと、複数のマシンで同じ確認を機械的に回せます。

更新は自分で実行する

自動更新はAnthropic以外のマーケットプレイスでは無効です。Langfuseのマーケットプレイスは該当するため、更新は手動です。

claude plugin marketplace update langfuse-observability
claude plugin update langfuse-observability@langfuse-observability

更新後はClaude Codeを再起動します。入っているバージョンは claude plugin list で確認できます。

他のトレース手段とどう使い分けるか

Claude Codeの観測には、向きの違う経路がいくつかあります。

プラグインとMCPは排他ではありません。プラグインで貯めたトレースを、MCP経由でClaude Code自身に読ませて、自分の過去セッションを分析させるという組み合わせも成り立ちます。ただし、この組み合わせを推奨する記述は、どちらの一次ソースにもありません。

トレースを見るときの着眼点

Langfuseのドキュメントは、トレースから改善点を見つける例を挙げています。

  • 同じファイルを何度も読んでいる: プロジェクト直下にCLAUDE.mdを置き、前提知識を先に渡す
  • ほぼ同じ入力のツール呼び出しが繰り返される: プロンプトや成功条件を絞る
  • コードを書く前に長いファイル読み込みが続く: タスクの指定が曖昧な可能性がある

これらは手動方式の節にある観点ですが、トレースの構造が似ているため、プラグインでも使える見方です。プラグイン側で Claude Code - Turn N のような名前でトレースが並ぶかどうかは、READMEに記載がありません。実際の画面で確かめてください。

まとめ

Langfuseを既に使っているチームなら、2コマンドと3つの値で、Claude Codeのコストとツール呼び出しを既存のダッシュボードに載せられます。手動のStopフックから移るなら、~/.claude/settings.json のフック登録と、プロジェクト側の env に置いたキーを片付けるかどうかも決めておくと整理しやすくなります。両方を残すと、同じセッションを2つの経路が送る形になります。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →