deepeval-otel

DeepEval OpenTelemetry エクスポート

このスキルを使って、AI アプリケーション（LLM アプリ、エージェント、RAG パイプライン、チャットボット）に 生の OpenTelemetry を計装し、トレースを Confident AI の Observatory に送信します。deepeval パッケージは不要で、OTLP に対応する任意の OpenTelemetry SDK で動作します。作業は次の2つだけです。適切な Confident AI OTLP エンドポイントにエクスポートすることと、Confident AI が各スパンから読み取る confident.* 属性を設定することです。

対象範囲：AI アプリケーションのみ

このスキルの対象はAI アプリケーションのみです。confident.* 属性とスパンの種類である agent、llm、retriever、tool は AI コンポーネントを表し、Confident AI の Observatory は AI の動作を評価および監視するために構築されています。

システムの AI 関連部分のみを計装してください。エージェントのループと計画、LLM 呼び出し、検索／ベクトル検索、ツール呼び出しが該当します。AI 以外のソフトウェア（Web サーバー、CRUD バックエンド、データベースレイヤー、インフラストラクチャ）や、AI アプリ内の AI 以外のスパンに confident.* 属性を適用しないでください。そのデータは Confident AI の対象ではなく、意味のある形で表示されません。対象に LLM、エージェント、検索、またはツール呼び出しのコンポーネントがない場合、このスキルは適用されません。

deepeval スキルとの使い分け

Confident AI へのベンダーに依存しない OTLP エクスポート（OpenTelemetry エクスポーターを Confident AI に向け、confident.* 属性を設定する場合）には、このスキルを使ってください。

Python の pytest 評価スイートの構築、データセットやゴールデンデータの生成、メトリクスの記述、deepeval test run の実行、または deepeval SDK の @observe デコレーターによる計装を希望する場合は、deepeval スキルを使ってください。2つのスキルは相互補完的であり、どちらか一方を選ぶものではありません。

前提条件

• Confident AI アカウントと CONFIDENT_API_KEY。
• アプリケーションの言語に対応する OpenTelemetry SDK。Python の場合は、opentelemetry-sdk と opentelemetry-exporter-otlp-proto-http。
• Confident AI の OTLP エンドポイントが受け付けるのは HTTP のみです。gRPC は使用しないでください。

仕組み

Confident AI は OTLP/HTTP トレースエンドポイントを公開しています。x-confident-api-key ヘッダーを指定して、任意の OpenTelemetry スパンエクスポーターをこのエンドポイントに向けてください。Confident AI のエクスポーターは各スパンの confident.* 属性を読み取り、トレースとスパンの構造を構築します。親子関係のネストには、属性ではなくネイティブの OpenTelemetry スパンコンテキストが使われます。

ワークフロー

1. 対象が AI アプリケーション（LLM 呼び出し、エージェントループ、検索、またはツール呼び出しを含む）であることを確認します。これらが1つもない場合は、このスキルは適用されないため中止します。次に、既存の OpenTelemetry 設定（TracerProvider、スパンエクスポーター、または OpenTelemetry Collector）を確認し、並行するパイプラインを追加するより、既存の設定の送信先を変更することを優先します。
2. API キーのリージョンプレフィックスからエンドポイントを選びます。references/endpoint-and-exporter.md を読みます。
3. x-confident-api-key ヘッダーを指定した OTLP/HTTP スパンエクスポーターを設定するか、既存の設定の送信先を変更します。Python の場合は、templates/confident_otel_setup.py を使ってください。
4. プロセスでほかの OpenTelemetry 計装や APM エージェント（HTTP／DB の自動計装、Datadog など）を実行している場合は、Confident AI へのエクスポートを分離し、AI スパンのみが送信されるようにします。専用のパイプラインを使うか、スパンフィルターを設定してください。references/endpoint-and-exporter.md の「AI スパンのみをエクスポートする」を読みます。
5. スパンに confident.span.* 属性を設定し、トレース全体に関するフィールドには confident.trace.* を設定します。references/span-attributes.md と references/trace-attributes.md を読みます。
6. OTLP のデータ型ルールに従います。辞書／メタデータは JSON にエンコードし、文字列リストにはネイティブ配列を使います。span-attributes.md の「データ型ルール」を参照してください。
7. アプリがすでに OpenTelemetry GenAI セマンティック規約を出力している場合は、属性の重複を追加する前に references/gen-ai-fallbacks.md を読みます。
8. トレースが Confident AI Observatory に表示されることを確認します。

基本原則

1. AI コンポーネントのみを計装します。対象はエージェント、LLM、リトリーバー、ツールのスパンです。 AI 以外のソフトウェアや AI 以外のスパンに confident.* 属性を適用しないでください。
2. AI スパンのみをエクスポートします。プロセスにほかの OpenTelemetry 計装や APM エージェントがある場合は、非 AI スパン（HTTP リクエスト、DB クエリ、インフラストラクチャ）が Confident AI にエクスポートされないよう、Confident AI パイプラインを分離してください（専用のプロバイダーまたはスパンフィルターを使用します）。
3. 並行してエクスポーターを追加するのではなく、既存の OTLP エクスポーターの接続先を変更する方法を優先してください。
4. confident.* 属性キーが契約のすべてです。どの言語でも同じなので、言語の選択は関係ありません。
5. 必ず OTLP/HTTP を使用してください。Confident AI のエンドポイントは gRPC を受け付けません。
6. OTLP のデータ型ルールを守ってください。属性値にはプリミティブ型または同じ型のプリミティブ値のリストを指定し、辞書とメタデータは JSON エンコードしてください。
7. 値が分かっている場合は confident.span.type を明示的に設定し、gen_ai.* による推論はフォールバックとしてのみ使用してください。
8. シークレット、認証情報、または機密データの生データをスパン属性に含めないでください。

参考資料

トピック	ファイル
エンドポイント、リージョンの選択、認証、エクスポーターの接続	references/endpoint-and-exporter.md
トレースレベルの confident.trace.* 属性	references/trace-attributes.md
スパンレベルの confident.span.* 属性とデータ型ルール	references/span-attributes.md
標準 OTel の gen_ai.* フォールバック動作	references/gen-ai-fallbacks.md

テンプレート

用途	テンプレート
最小限の Python OTLP エクスポーター設定とトレースの例	templates/confident_otel_setup.py