langfuse-observability

Langfuse のオブザーバビリティ

Langfuse のトレース機能を使って LLM アプリケーションを計測します。ベストプラクティスに従い、ユースケースに合わせて設定します。

使用するタイミング

• 新しいプロジェクトで Langfuse を設定するとき
• 既存の Langfuse 計測を監査するとき
• LLM 呼び出しにオブザーバビリティを追加するとき

ワークフロー

1. 現状を確認する

プロジェクトを確認します。

• Langfuse SDK はインストールされていますか？
• どの LLM フレームワークが使われていますか？（OpenAI SDK、LangChain、LlamaIndex、Vercel AI SDK など）
• すでに計測機能が導入されていますか？

まだ連携されていない場合： 利用できる場合は、フレームワーク連携を使って Langfuse を設定します。連携機能を使うと、より多くのコンテキストが自動的に記録され、手動で計測するよりもコードが少なくて済みます。

連携済みの場合： 以下の基本要件を満たしているか監査します。

2. 基本要件を確認する

すべてのトレースに、次の基本情報が含まれている必要があります。

要件	確認事項	理由
モデル名	LLM モデルが記録されていますか？	モデルの比較や絞り込みが可能になります
トークン使用量	入力／出力トークンが追跡されていますか？	コストを自動計算できます
わかりやすいトレース名	わかりやすい名前が付いていますか？（trace-1 ではなく chat-response など）	トレースを見つけやすく、絞り込みやすくなります
スパンの階層	複数ステップの処理が適切にネストされていますか？	どのステップが遅いか、失敗しているかがわかります
適切なオブザベーション種別	生成が生成としてマークされていますか？	モデル固有の分析が可能になります
機密データのマスキング	個人識別情報や機密データが除外またはマスキングされていますか？	データ漏えいを防ぎます
トレースの入力／出力	トレースには、処理対象の全データが入力として、結果が出力として記録されていますか？	デバッグや処理内容の把握が可能になります

フレームワーク連携（OpenAI、LangChain など）を使うと、モデル名、トークン、オブザベーション種別が自動的に処理されます。手動で計測するよりも連携機能を優先してください。

ドキュメント：https://langfuse.com/docs/tracing

3. まずトレースを確認する

基本的な計測が機能したら、さらにコンテキストを追加する前に、Langfuse UI でトレースを確認するようユーザーに促します。

「トレースが Langfuse に表示されるようになりました。いくつか確認して、どのようなデータが記録されているか、何が役立つか、何が不足しているかを見てみましょう。追加するコンテキストを決めるのに役立ちます。」

これにより、ユーザーは次のことができるようになります。

• すでに得られている情報を把握する
• 不足している情報について考える
• 必要なものについて、より適切な質問をする

4. 追加のコンテキストの必要性を特定する

どのような追加の計測が有用かを判断します。可能であればコードから推測し、不明な場合にのみ質問してください。

コードから推測する場合：

コード内で見られるもの	推測される内容	提案
会話履歴、チャットエンドポイント、メッセージ配列	マルチターンアプリ	session_id
ユーザー認証、user_id 変数	ユーザー対応アプリ	トレースへの user_id
複数の異なるエンドポイント／機能	マルチ機能アプリ	feature タグ
顧客／テナント識別子	マルチテナントアプリ	customer_id またはティアタグ
フィードバック収集、評価	ユーザーフィードバックあり	スコアとして記録

コードから明らかでない場合にのみ質問する：

• 「応答の良し悪しはどのように判断していますか？」→ スコアリング方法を決定します
• 「ダッシュボードでどの項目を使って絞り込みたいですか？」→ 見落とされがちなタグを明らかにします
• 「比較したいユーザーセグメントはありますか？」→ 顧客ティア、プランなど

追加項目とその価値：

追加項目	理由	ドキュメント
session_id	会話をまとめてグループ化できます	https://langfuse.com/docs/tracing-features/sessions
user_id	ユーザーによる絞り込みとコストの割り当てが可能になります	https://langfuse.com/docs/tracing-features/users
ユーザーフィードバックスコア	品質による絞り込みと傾向の把握が可能になります	https://langfuse.com/docs/scores/overview
feature タグ	機能ごとの分析	https://langfuse.com/docs/tracing-features/tags
customer_tier タグ	セグメントごとのコスト／品質の内訳	https://langfuse.com/docs/tracing-features/tags

これらは必須要件ではありません。推測またはユーザーの入力に基づき、関連する項目のみを追加してください。

5. UI を案内する

コンテキストを追加した後、関連する UI 機能を案内します。

• トレースビュー：個々のリクエストを確認できます
• セッションビュー：グループ化された会話を確認できます（session_id を追加した場合）
• ダッシュボード：タグを使って表示を絞り込めます
• スコア：品質指標で絞り込めます

フレームワークのインテグレーション

手動で計測するより、次のインテグレーションを優先してください。

フレームワーク	インテグレーション	ドキュメント
OpenAI SDK	ドロップイン置き換え	https://langfuse.com/docs/integrations/openai
LangChain	コールバックハンドラー	https://langfuse.com/docs/integrations/langchain
LlamaIndex	コールバックハンドラー	https://langfuse.com/docs/integrations/llama-index
Vercel AI SDK	OpenTelemetry エクスポーター	https://langfuse.com/docs/integrations/vercel-ai-sdk
LiteLLM	コールバックまたはプロキシ	https://langfuse.com/docs/integrations/litellm

一覧はこちら：https://langfuse.com/docs/integrations

必ず理由を説明する

追加項目を提案する際は、ユーザーにとってのメリットを説明してください。

"I recommend adding session_id to your traces.

Why: This groups messages from the same conversation together.
You'll be able to see full conversation flows in the Sessions view,
making it much easier to debug multi-turn interactions.

Learn more: https://langfuse.com/docs/tracing-features/sessions"

よくある間違い

間違い	問題	修正
スクリプトで flush() を呼び出さない	トレースが送信されません	終了前に langfuse.flush() を呼び出します
フラットなトレース	どのステップで失敗したか分かりません	個別のステップにはネストしたスパンを使用します
汎用的なトレース名	フィルタリングが困難です	chat-response、doc-summary など、内容が分かる名前を使用します
機密データのログ記録	データ漏えいのリスクがあります	トレースを記録する前に PII をマスキングします
統合機能があるのに手動でインストルメンテーションを行う	コードが増え、コンテキストが減ります	フレームワークの統合機能を使用します
環境変数の読み込み前に Langfuse をインポートする	Langfuse が認証情報の欠落や誤りを含む状態で初期化されます	環境変数の読み込み後（例：load_dotenv() の後）に Langfuse をインポートします
OpenAI とのインポート順序が誤っている	Langfuse が OpenAI クライアントにパッチを適用できません	OpenAI クライアントをインポートする前に Langfuse をインポートし、そのセットアップを呼び出します