langfuse

Langfuse

既存の LLM アプリケーションに、トレース可能で最小化されたオブザベーションとバージョン管理された評価入力を組み込みます。2026-09-05 に AAS のメンテナーによって変更され、混在したレガシー SDK の例を現行の範囲を限定したセットアップ手順に置き換えました。既存の出典表示は保持されています。

使用する場面

アプリケーションですでに Langfuse のトレーシング、プロンプト管理、または評価が必要な場合、あるいは欠落した/重複したスパンをデバッグする場合に使用します。LLM が存在するというだけの理由でオブザーバビリティサービスを追加しないでください。データが支えるべきインシデントまたはプロダクト上の意思決定から始めてください。

入力と前提条件

• インストール済みの Python または JS SDK のバージョン、フレームワーク、ランタイムのライフサイクル。
• 明示的に承認された Langfuse プロジェクト/エンドポイント、プロジェクトのシークレット機構を通じて提供される認証情報、およびデータの保持/アクセスポリシー。
• 監視可能なフィールドの許可リストと、プライベートな内容を含まない合成リクエスト。
• 定義された検証項目: 期待される親/子スパン、ステータス、タイミング、モデル/プロンプトのバージョン、フラッシュの挙動。

手順

1. 依存関係のロックファイルと既存のインストルメンテーションを確認します。古い langfuse.trace()、langfuse.decorators、langfuse.callback の例を、移行ガイドを確認せずに現行 SDK と混在させないでください。
2. 統合レイヤーを 1 つ選択します。直接の SDK スパン、フレームワークのコールバック、または OpenTelemetry インストルメンテーションです。重複するラッパーを通じて同じ呼び出しを二重にトレースすることは避けてください。
3. 承認されたエンドポイントと認証情報をソースコードの外で設定します。例を実行する前にエクスポートの権限を確認してください。インストルメンテーションは入力、出力、メタデータ、例外を外部へ送信する可能性があります。
4. 合成値または許可リストに載った値のみを含む明示的なオブザベーションから始めます。相関 ID は、そのスコープとプライバシー上の取り扱いが定義されている場合にのみ追加してください。
5. 成功リクエストと失敗リクエストを 1 回ずつ実行し、実際にエクスポートされたスパンツリーを検査して、ネストされたメタデータやサードパーティのインストルメンテーションを通じて機密フィールドが漏れていないことを確認します。
6. 短命なプロセスではフラッシュし、シャットダウン/タイムアウトをテストします。SDK 呼び出しが戻ったことだけでは、取り込みが行われたことの証明にはなりません。
7. プロンプト/評価のメタデータは、トレースの境界が機能した後にのみ追加します。プロンプトのバージョンを固定するか、解決された正確なバージョンを記録してください。可変の本番ラベルは不変の実験入力ではありません。

最小限の Python オブザベーション

現在の Python SDK の概要 では、get_client() とコンテキスト管理されたオブザベーションについて説明されています。インストール済みの SDK に一致する API を使用してください。設定とエクスポートの承認後、この合成例は 1 つのスパンを作成し、LLM 呼び出しは行いません:

from langfuse import get_client

client = get_client()
with client.start_as_current_observation(as_type="span", name="synthetic-health-check") as span:
    span.update(output={"status": "ok"})
client.flush()

期待されるオブザベーション: 意図したプロジェクト内に、固定されたステータス値を持つ完了済みの synthetic-health-check スパンが 1 つ。このスキルは、実際の取り込みチェックが実行されたとは主張しません。誤ったエンドポイント、認証情報の欠落、またはエクスポーターの失敗は、失敗した/未検証のチェックとして報告する必要があります。

プライバシーとマスキング

切り詰めをレダクションとして扱わないでください。生のプロンプト、ユーザーメッセージ、ツールのペイロードは省略することを優先し、設定されたすべてのエクスポーターを検査してください。現在の Python SDK はエクスポート時の変換用に mask_otel_spans を提供しています。レガシーの mask フックは、SDK が作成する属性のより狭い範囲のみをカバーします。マスキングのドキュメント を使用して、インストール済みバージョンの機構を選択し、ネストされたメタデータと例外の中にある合成シークレットをテストしてください。コレクター側のフィルタリングはデータがアプリケーションを離れた後に実行されるため、承認された信頼境界の内側に配置してください。

プロンプトの管理と評価

データセットのリビジョン、プロンプトのバージョン、モデル識別子、ツール設定、評価者の定義を記録します。評価者のエラーと低スコアは区別しておきます。ジャッジの応答は、上限付きのスキーマと有限範囲の検証を通過しなければなりません。任意のモデルテキストを float() で直接変換し、それを測定された品質と呼んではいけません。判断はレビュー済みの例と照らして校正し、不一致を報告します。ユーザーフィードバックと自動ジャッジのスコアは分けて扱います。

比較の実例: 同じ固定のサポート例をプロンプトバージョン A と B に対して実行し、各出力と検証結果を記録してから、リグレッションとコスト・レイテンシを確認します。期待されるのは、失敗を保持した再現可能な比較であり、最高平均スコアの後に本番ラベルを自動で変更することではありません。

制限事項

• SDK のメソッドと統合は進化します。サーバーのバージョン、Python SDK のバージョン、JS パッケージのバージョンは、それぞれ別個の互換性に関する事実です。
• トレースが明らかにするのは観測可能な操作であり、隠された思考の連鎖や回答の正しさの証明ではありません。
• 1 つのエクスポーターをマスクしても、アプリケーション内のすべてのログやエクスポーターがサニタイズされるわけではありません。
• サンプリング、キューの損失、シャットダウンの挙動はトレースの完全性に影響します。これらを明示的に評価してください。
• このスキルは、タスクの承認なしにアカウントの作成、本番プロンプトラベルの変更、データセットのアップロード、外部テレメトリの設定を行いません。

参考資料

• トレースのセットアップ
• SDK の概要
• SDK の高度な機能
• マスキング