Skip to content
Published on

集めたあと — Langfuseのダッシュボード、メトリクスAPI、そしてトレースに付く評価

🇰🇷KO🇺🇸EN🇯🇵JA🇨🇳ZH
Split View필사 모드
シェア
Authors

はじめに — 収集は始まりで、問いが目的

ここまで来ればデータは集まります。データモデルを知り、計測を入れ、保存層を理解し、システムを立て、量を調整しました。しかしそのすべての目的は問いに答えることです。

問題は、ダッシュボードを先に開くと答えるべき問いが浮かばないことです。グラフがすでに描かれていると、そのグラフが答える問いしかしなくなります。答えるべき問いを先に書き出し、その問いがどの測定値をどの次元で切るのかを確認する順序に反転させる必要があります。

構成と設定名は2026-08-15に公式ドキュメントで確認しました。Langfuseはバージョンによってアーキテクチャが変わるため、利用中のバージョンのドキュメントを再確認してください。本記事で扱うメトリクスAPIはv4で導入されたv2の形です。

ダッシュボードが見せる三つの軸

メトリクス概要のドキュメントが整理する指標は三つに分かれます。

  • 品質です。利用者のフィードバック、モデルによる採点、人が介在した標本の採点、そしてSDKとAPIで入れたカスタムscoreで測ります。時間、プロンプトのバージョン、モデル、利用者にわたって評価できます。
  • コストと遅延です。ドキュメントは、これを利用者、セッション、地域、機能、モデル、プロンプトのバージョンで分けて見られると述べています。
  • ボリュームです。取り込まれたトレースと使用トークンを基準に計算されます。

大事なのは、この三つが互いを説明することです。品質が落ちた区間があるなら、その区間の遅延とコストがどう動いたかを併せて見て初めて原因が絞れます。遅延だけを見ても、モデルが遅くなったのか、プロンプトが長くなったのか、検索段階が増えたのかは分かりません。

何で切って見るか

測定値より大事なのは次元です。ドキュメントが明示する分析次元は、トレース名、利用者の識別子、タグ、そしてリリースとバージョンの番号です。これにコストと遅延の側で言及されるモデルとプロンプトのバージョンが加わります。

実務で出てくる問いをこの次元に移すと、次のようになります。

問い測定値切る次元
どの機能がコストを最も使うかコストトレース名、タグ
前回の配備以降に遅くなったか遅延リリースまたはバージョン
特定のモデルだけ失敗率が高いか失敗件数モデル
ヘビーユーザーのコスト構造は違うかコスト、トークン利用者の識別子
新しいプロンプトは品質を上げたかscoreプロンプトのバージョン

ここで第一回の話が戻ってきます。これらの次元は計測の時点で値が入っていて初めて存在します。user_idを入れていなければ利用者別のコスト問い合わせはそもそも不可能ですし、タグを付けていなければ機能別の分解もできません。ダッシュボード作りが止まる理由のほとんどがここにあります。

メトリクスAPI — 問い合わせをコードで書く

画面でクリックして作るダッシュボードとは別に、指標をプログラムから取得する経路があります。メトリクスAPIのドキュメントが定義するエンドポイントはGET /api/public/v2/metricsです。

問い合わせは一つのオブジェクトとして表現されます。ドキュメントに出てくるフィールドは次のとおりです。

  • view — どのデータを見るか
  • metrics — measureとaggregationの組の配列
  • dimensions — fieldを持つ配列
  • filters — フィルタ条件の配列
  • fromTimestampとtoTimestamp — ISO 8601 形式の期間
  • orderBy — fieldとdirectionを持つ配列
  • config — row_limitを持つオブジェクトで、既定値100、最大1,000

ドキュメントが示すリクエストの例は次の形です。

{
  "view": "observations",
  "metrics": [{ "measure": "totalCost", "aggregation": "sum" }],
  "dimensions": [{ "field": "providedModelName" }],
  "filters": [],
  "fromTimestamp": "2025-12-01T00:00:00Z",
  "toTimestamp": "2025-12-16T00:00:00Z",
  "orderBy": [{ "field": "sum_totalCost", "direction": "desc" }],
  "config": { "row_limit": 1000 }
}

orderByのフィールド名に注目してください。集計関数と測定値をつないだ形です。つまり結果の列名が問い合わせの構造によって決まります。

呼び出しは公開APIの認証をそのまま使います。

# 例: 問い合わせオブジェクトをクエリパラメータで渡す
curl -sS -u "${LANGFUSE_PUBLIC_KEY}:${LANGFUSE_SECRET_KEY}" \
  --get "https://cloud.langfuse.com/api/public/v2/metrics" \
  --data-urlencode "query@./query.json"

正確なパラメータの渡し方と、利用できる測定値、次元、集計関数の一覧は、利用中のバージョンのAPIドキュメントで確認してください。この一覧はバージョンによって増えたり名前が変わったりします。

v2で変わったこと — tracesビューがない

ここがバージョン差のもっとも目立つ地点です。ドキュメントはv2で利用できるビューを四つ挙げています。observations、scores-numeric、scores-categorical、scores-booleanです。そしてtracesビューはv2ではもう提供されないと明示しています。

この変化は第三回で見た保存形式と正確に噛み合います。Langfuseは概念的に一つのobservationsテーブルを置き、各行にtraceレベル属性の複製を持ちます。traceレベルの属性がobservationの行にすでにあるので、observationsビュー一つでtraceの軸の問いにも答えられます。

v3当時の資料で作った連携がv4で壊れる理由もここにあります。バージョンポリシーのドキュメントは、v3からv4への移行で旧来の読み取りAPIが削除され、Observations API v2とメトリクスAPI v2が導入されたと述べています。ダッシュボードやレポートのパイプラインをAPIの上に作っているなら、この項目をアップグレード計画に必ず入れてください。

そして第三回で強調した原則がここで効いてきます。アプリケーションが依存する指標はClickHouseを直接叩かず、このAPIから取ってください。スキーマは安定した契約ではありませんが、公開APIはバージョンポリシーの対象です。

scoreを付ける流れ

品質の軸は勝手には生まれません。scoreを作って付ける必要があります。スコアのドキュメントが挙げる生成経路は五つです。

  1. LLM審査による自動評価器
  2. コード評価器（PythonとTypeScript）
  3. 画面で人が直接採点
  4. 注釈キュー
  5. APIまたはSDKからプログラムで追加

付く場所は第一回で見た四か所です。trace、observation、session、データセット実行です。セッションのドキュメントは、セッションに人の評価を注釈として付けられること、セッションレベルのscoreをSDKやAPIからプログラムで追加できることを述べています。複数ターンにわたる会話の品質は一つのターンでは判定できないので、この軸が必要になります。

データ型の選択は、後で何を集計できるかを決めます。NUMERIC、CATEGORICAL、BOOLEANはメトリクスAPIのビュー名にそのまま対応します。一方でTEXTのscoreは実験、LLM審査の評価器、分析で使えないとドキュメントが明示しています。自由記述を残したいなら、scoreのcommentフィールドを使い、集計の軸は別のCATEGORICALとして持つほうが安全です。

scoreを作るSDKメソッドの正確な名前と引数は、利用中のSDKバージョンのリファレンスで確認してください。Python SDK v4とJS/TS SDK v5がサーバーv4の正式サポート対象です。

評価器がobservationレベルへ降りたこと

v4の変化のうち実務にもっとも大きく効くのがこれです。バージョンポリシーのドキュメントは、v3からv4への移行で評価器がtraceレベルからobservationレベルへ移ったと述べています。

何が変わるのかは第一回のRAGツリーを見ると明確です。traceレベルの評価しかできなかった時代は「この回答は良いか」しか問えませんでしたが、observationレベルの評価ができれば「検索は適切な文書を取ってきたか」を検索段階だけに問えます。

診断で大きな差が出ます。最終回答の品質だけが落ちて検索段階のscoreが変わらないなら、問題は生成の側です。検索段階のscoreも一緒に落ちているなら、インデックスや埋め込みの側を見ます。一つの数字ではこの区別が出ません。

評価の設計そのものをさらに深く見たいなら、LLM評価と可観測性の完全ガイドが評価ハーネスとLLM審査、回帰防止を扱っています。

コード評価器をセルフホストで有効にする

コード評価器は利用者が書いたコードをサーバーが実行する機能なので、セルフホストでは実行環境を決める必要があります。設定のドキュメントに出てくる関連変数は次のとおりです。

# 実行方式の選択
LANGFUSE_CODE_EVAL_DISPATCHER=aws-lambda          # aws-lambda または insecure-local

# ワーカーが実行キューを消費するよう有効化（既定 false）
QUEUE_CONSUMER_CODE_EVAL_EXECUTION_QUEUE_IS_ENABLED=true

# Lambda 関数名（ドキュメント基準の既定値）
LANGFUSE_CODE_EVAL_AWS_LAMBDA_NODE_FUNCTION_NAME=code-based-eval-executor-node
LANGFUSE_CODE_EVAL_AWS_LAMBDA_PYTHON_FUNCTION_NAME=code-based-eval-executor-python

insecure-localという名前そのものが警告です。ドキュメントが示す二つの選択肢のうち、一方は隔離されたLambdaで、もう一方はローカル実行です。本番でどちらを選ぶべきかは名前がすでに語っています。このほかにキューのシャード数、ワーカーの同時実行数、ローカル実行のタイムアウトを調整する変数がそれぞれあります。

問いから始めるダッシュボード設計

まとめると設計の順序はこうなります。

  1. 前四半期に実際に受けた問いを書き出します。想像した問いではなく受けた問いです。
  2. それぞれを測定値と次元の組み合わせに移します。移せない問いは計測が足りていません。
  3. 必要な次元がトレースに入っているかを確認します。なければ第二回に戻って計測を直します。
  4. その組み合わせをダッシュボードにするか、メトリクスAPIの問い合わせとして書きます。
  5. 品質の軸が必要な問いには、scoreを付ける経路を一つ選びます。

この順序を守れば、誰も見ないグラフが減ります。ダッシュボードは増えるのに障害の振り返りでは相変わらずログを漁っているなら、順序が反転しているという合図です。

おわりに — 六本を貫く一文

このシリーズを一文に縮めるとこうなります。あとで投げる問いが、いま残すデータの形を決める。

データモデルは何を残せるかを、計測は実際に何を残すかを、保存層はそれをどんな問い合わせで取り出せるかを、保持とサンプリングはどれだけ長く残るかを決めました。最終回の問い合わせと評価は、その決定すべての結果を確認する場です。

最後の点検は最初と同じです。答えるべき問いを三つ書き出し、いまの構造で答えられるかを確認してください。答えられないなら、直す場所は本記事ではなく第二回です。

試してみる

シリーズ

参考資料

Discuss on Twitter • View on GitHub