OpenTelemetry GenAI トレースを結果イベントに接続する
OpenTelemetry トレースと Telemetry 構造化イベントは、AI エージェント調査のさまざまな部分を解決します。詳細なモデル、エージェント、ツール スパンを OTLP 互換の可観測性バックエンドに保持します。成功、コスト、レイテンシー、リリース、アカウント、ハンドオフ、またはレビューされた製品の価値について SQL を検査可能にしたい場合は、より小さいターミナル結果イベントを Telemetry に送信します。
Telemetry は OTLP エンドポイントを公開せず、OpenTelemetry トレース バックエンドではありません。接続はアプリケーションが所有する相関識別子であり、すべてのスパンの 2 番目のエクスポートではありません。
各システムを目的の業務に使用する
OpenTelemetry トレースは、次の質問に答えるのに適しています。
- どのスパンまたはツールが 1 回の低速ランを支配したか。
- エージェント、モデル、検索、およびツール操作の間で制御がどのように移動するか。
- どの例外または依存関係が個々の失敗を説明するか。
- 承認された痕跡保持境界内にどのような詳細な属性が存在するか。
コンパクトな結果イベントは、次のことに答えるのに適しています。
- どのリリースが端末タスクの成功率が最も高いか。
- 受け入れられた結果ごとにどのワークフローに最もコストがかかるか。
- 今週はツールの再試行または人間によるハンドオフが増加したかどうか。
- どの顧客層が制限付きエラー カテゴリの影響を受けたか。
- プロンプトまたはモデルのバージョン後に評価スコアが変更されたかどうか。
すべてのスパン属性をイベントにコピーしないでください。どの集計質問に永続的な列が必要かを決定し、それらのフィールドを許可リストに登録します。
セマンティクスを意図的にマップする
の OpenTelemetry 生成 AI のセマンティック規則 モデル、エージェント、ツール操作の進化する属性とスパン規則を定義します。サービスで使用される semantic-convention および instrumentation-library のバージョンを固定し、アップグレード中にマッピングを確認します。
| OpenTelemetry コンセプト | Telemetry イベントフィールド | ガイダンス |
|---|---|---|
| アクティブ スパン トレース ID | trace_id |
承認された場合の安全な相関ポインタ。アカウント ID として使用しないでください |
| アプリケーションの実行または操作 ID | run_id または operation_id |
再試行やその後のレビューでの結合にはアプリケーション識別子を優先します |
gen_ai.operation.name |
operation_name |
制限された操作カテゴリを維持する |
gen_ai.provider.name |
provider |
ピン留めされたインスツルメンテーションによって発行されたプロバイダー値を使用する |
| リクエストまたはレスポンスモデル | model |
1 つの意味を選択して文書化するか、そのままにしておく requested_model そして response_model 別途 |
| 入出力の使用法 | input_tokens, output_tokens |
数値の使用状況を 1 回記録します。推論トークンの詳細を二重にカウントしないでください |
| エージェントのアイデンティティ | agent_name または agent_version |
生成されたインスタンス識別子ではなく安定した論理名を使用する |
| スパンステータスまたは例外 | status, error_type |
制限されていないメッセージを許可リストに登録されたアプリケーション カテゴリに変換する |
意味上の規則は、成熟するにつれて変更される可能性があります。 1 つの SDK またはフレームワークで観察される属性が、どこでも同じ安定性または可用性を持っていると想定しないでください。正確なマッピングをバージョン管理されたアプリケーション コードとして扱います。
トレースの横に 1 つの最終結果を出力します
この JavaScript ラッパーは、現在のトレース ID を読み取り、エージェントの実行後にアプリケーションの結果を記録します。トレースは、構成された OpenTelemetry SDK によって引き続きエクスポートされます。選択したフィールドのみが Telemetry に移動します。
import { trace } from "@opentelemetry/api";
import telemetry from "telemetry-sh";
telemetry.init(process.env.TELEMETRY_API_KEY);
export async function runSupportAgent({
agent,
input,
operationId,
accountId,
release,
}) {
const startedAt = Date.now();
let status = "success";
let errorType;
let result;
try {
result = await agent.run(input);
return result;
} catch (error) {
status = "failed";
errorType = classifyAgentError(error);
throw error;
} finally {
const activeSpan = trace.getActiveSpan();
const traceId = activeSpan?.spanContext().traceId;
await telemetry.log("agent_run_completed", {
operation_id: operationId,
trace_id: traceId,
workflow: "support_resolution",
account_id: accountId,
status,
error_type: errorType,
duration_ms: Date.now() - startedAt,
human_handoff: result?.handoffRequired ?? false,
tool_call_count: result?.toolCallCount ?? 0,
release,
});
}
}
ビジネス ワークフローで明示的に要求されない限り、イベント配信の失敗は致命的ではありません。短いタイムアウト、制限付き再試行、正常なシャットダウン、および配信ガイダンスを使用します。 バッチ処理、バックプレッシャー、シャットダウン.
モデルの使用法を 1 回だけ追加する
OpenTelemetry インスツルメンテーションがすでにプロバイダー リクエストを監視している場合、リクエストの使用状況は Telemetry に自動的に設定されません。 SQL の集合的な質問に別の質問が必要かどうかを決定します。 llm_request_completed イベント。
その場合は、次のようにして、請求可能なリクエストごとに 1 つのイベントを発行します。
operation_id,run_id、およびオプションの承認済みtrace_id;provider,requested_model,response_model、そしてservice_tier;- 入力、キャッシュされた入力、出力、およびその他の個別に定義されたトークン カテゴリ。
estimated_cost_usdバージョン管理された価格設定ソース。latency_ms,status,attempt,feature、そしてrelease.
スパン期間からコストを導出しないでください。プロバイダーから報告された使用量とレビューされた料金表を使用して、見積もりをプロバイダーの請求書と調整します。の OpenAI リクエストコストガイド そのパターンを示しています。
データ境界を保護する
生成 AI テレメトリには、非常に機密性の高いデータが含まれる可能性があります。デフォルトでは、これらのフィールドを Telemetry に送信しません。
- プロンプトまたは完了コンテンツ。
- システムの指示または思考連鎖のコンテンツ。
- 取得されたドキュメントのテキストまたは埋め込み。
- ツールの引数、ツールの応答、シェル出力、またはファイルの内容。
- 認証ヘッダー、Cookie、API キー、データベース資格情報、または接続文字列。
- 無制限の例外メッセージまたは OpenTelemetry 荷物。
- 製品の収集および保持のレビューに合格していない個人データ。
次のようなカテゴリを優先します input_category, output_category, tool_name, error_type, policy_result、そして review_outcome。いずれかのエクスポータを呼び出す前に、ホワイトリストを適用します。ダッシュボードからフィールドを削除しても、保存されているデータからは削除されません。
結果をクエリし、トレース リンクを保存する
レスポンダが必要とする相関ポインタを保持しながら、集計比較には SQL を使用します。
SELECT
release,
workflow,
COUNT(*) AS completed_runs,
SUM(CASE WHEN status = 'success' THEN 1 ELSE 0 END) AS successful_runs,
SUM(CASE WHEN human_handoff THEN 1 ELSE 0 END) AS handoffs,
ROUND(AVG(duration_ms), 0) AS average_duration_ms,
MAX(trace_id) AS example_trace_id
FROM agent_run_completed
WHERE timestamp_utc >= now() - INTERVAL '7 days'
GROUP BY release, workflow
ORDER BY completed_runs DESC;
MAX(trace_id) これはグループからのポインタの例にすぎず、代表的なトレースではありません。調査の場合は、基になる行を開き、関連する実行を選択して、その実行を貼り付けます。 trace_id トレースバックエンドに。バックエンドが安定した URL テンプレートをサポートしている場合は、ベンダー資格情報やプライベート ホスト名をイベント フィールドとして送信するのではなく、アクセス制御された内部ツールでリンクを構築します。
接続を検証する
実稼働展開前:
- 実行の成功が 1 回、ツールの失敗が 1 回、回復された再試行が 1 回、端末の失敗が 1 回生成されます。
- トレース バックエンドに予期したスパン ツリーが含まれていることを確認します。
- Telemetry に、実行ごとに 1 つのターミナル イベントと、意図したリクエストまたはツール イベントが含まれていることを確認します。
- トレース相関識別子とイベント相関識別子を比較します。
- プロンプト、補完、引数、資格情報、およびプライベート コンテンツが存在しないことを確認します。
- いずれかのエクスポーターが遅いか使用できない場合の動作をテストします。
- ドキュメントの所有者、保持、意味規則のバージョン、サンプリング、および調査の引き継ぎ。
一般的なアーキテクチャと SDK の例については、以下を参照してください。 Telemetry と OpenTelemetry。エージェント固有の結果デザインの場合は、次の手順に進みます。 SQL で AI エージェントを評価する そして 製品境界を監視する AI エージェント.