configure-trace-metrics

Coval Trace メトリクスを設定する

対象エージェントの実際のトレースが少なくとも1つ存在してから、トレースデータを基にメトリクスを作成します。setup-tracing の検証実行が現在保留中の場合は、待ち時間を利用して既存のトレースを確認し、メトリクス定義を準備します。過去のトレースまたは進行中の実行によって、対象のスパンと属性の存在がすでに確認できている場合に限り、待機中にメトリクスを作成します。

品質基準：データ取り込みの証明だけを目的としたメトリクスは、ゴールではありません。一般的な呼び出し時間や生のスパン数など、トレースが到着したことだけを証明するメトリクスは、顧客の意思決定に役立たない限り、診断用にとどまります。ワークフローのボトルネック、ユーザーに影響する障害、依存関係の健全性の問題、レイテンシのテール、コスト要因、フォールバック、引き継ぎ、完了シグナルを明らかにするメトリクスを優先してください。

トレースデータが対応している場合、このスキルでは通常、次の2種類のメトリクスを作成します。

• 実際のスパン属性を使った数値の METRIC_CUSTOM_TRACE メトリクス
• トランスクリプトだけでは見落とす可能性のあるシーケンス、根拠付け、復旧動作の評価にトレースが役立つ場合、include_traces: true を指定したトレース対応の LLM ジャッジメトリクス（METRIC_LLM_BINARY、METRIC_CATEGORICAL、または METRIC_NUMERICAL_LLM_JUDGE）

トレーススパンが適切なデータソースである場合にのみ、トレースメトリクスを使用してください。1回の呼び出しあたりのターン数などのメトリクスは、トランスクリプト、シミュレーション出力、または評価メトリクスで扱うほうが適切な場合がよくあります。カート合計、注文合計、プロバイダーのフォールバック、ツールの失敗、下流のレイテンシなどのメトリクスは、エージェントが実際のスパンに安全な数値を出力する場合、トレースメトリクスに適しています。

最初に読む

以下を読み込みます。

• ../references/trace-metrics-playbook.md
• ../references/span-schema.md
• ../references/coval-tracing-reference.md
• エージェントが Vapi ウェブフックを使用する場合は ../references/vapi-artifact-tracing.md

フェーズ 0：棚卸し

認証情報と現在のリソースを確認します。

coval whoami
coval agents list --format json
coval metrics list --include-builtin --format json

CLI で必要なメトリクス形式を作成できない場合は、最新の OpenAPI を取得してから API を使用します。

curl -fsS https://api.coval.dev/v1/openapi

稼働中の対象 API を正としてください。api.coval.dev では、カスタムトレースメトリクスの検証結果がデプロイ環境によって異なる場合があります。作成時に集計方法の検証エラーが返された場合は、その環境で受け入れられる本番用の設定に切り替え、引き継ぎ時に公開 API／ドキュメントとの不整合を伝えてください。

以下を収集します。

• エージェント ID とタイプ
• トレースを含む最近の実行または会話、あるいは setup-tracing がポーリングしている進行中の検証実行
• Trace Search の候補、トレースビューアー、またはコピーしたトレースダンプから得られるスパン名と属性
• すでに紐付けられている既存の組み込みトレースメトリクス
• 既存の LLM ジャッジメトリクスと、include_traces がすでに有効になっているかどうか
• 顧客のユースケースまたは業種

フェーズ 1：メトリクス候補を決める

プレイブックを使って、少数の候補を提案します。ノイズの多い大量のメトリクスより、シグナルの強い3～6個のメトリクスを優先してください。

各候補について、答えとなる顧客の問いを記述します。その問いが「トレースは機能したか？」だけである場合は、そのメトリクスを削除するか、診断専用として明示してください。 同じ答えをトレース以外の Coval データから算出するほうが適切な場合も、そのメトリクスを削除してください。

基本的な推奨事項：

• 音声エージェント：LLM／TTS／STT の TTFB、トークン使用量、ツール呼び出し数、stt スパンに transcript が含まれる場合は STT WER
• リアルタイムまたは WebSocket エージェント：モデル／リアルタイムのレイテンシ、応答 TTFB、トークン使用量、ストリーム／エラースパン
• 会話モニタリング：p95／p99 レイテンシ、ツール／API エラー率、重大イベント数、本番環境でのフォールバック率
• カスタムビジネスロジック：顧客固有のワークフローにおける最も重要なボトルネックまたは障害モードを示すメトリクスを1つ トレースにツールまたはワークフローのスパンが含まれる場合の、最初に作成するシグナルの高い指標：
• 顧客のドメインに関連する、業界固有の障害モード指標を1つ。例：ロードサイド派遣レイテンシー P90、予約日破損率、支払いプランブロック率、本人確認完了率、エスカレーション発生率
• 依存関係ブロック率：必須の外部依存関係により完了できなかった割合
• ツール失敗率：ツール／API 呼び出しでエラーまたは利用不能な応答が返された割合
• ツールレイテンシー P90：呼び出し失敗になる前の、遅い下流ツールのレイテンシー
• カート合計平均または注文合計平均：チェックアウト中に確定したビジネス価値
• ワークフロー完了率またはフォールバック率：意図した顧客の成果が実現したかどうか

トレースにツール呼び出しまたはワークフロー属性が含まれる場合の、シグナルの高いトレース対応 LLM ジャッジ指標：

• ツール出力の根拠付け：発話中の主張が成功したツール出力と一致し、tool.error や error.type を無視していないこと
• ツール使用前の確認：機密識別子やアカウント固有のツールは、会話の文字起こしとトレースで確認済みであることが示されている場合にのみ使用されること
• ツール失敗からの回復：依存関係の障害または利用不能なツール応答の後、エージェントが適切に再プロンプト、再試行、エスカレーション、または拒否を行うこと
• 読み上げ確認の徹底：ツール呼び出しで使用する前に、エージェントが機密識別子を確認すること

顧客から指標をその場で更新するよう明示的に依頼されていない限り、既存の本番指標を目立たない形で変更するのではなく、既存の LLM ジャッジ指標のトレース対応版を新たに作成してください。

実際のトレースデータに存在しない属性についてカスタムトレース指標を作成しないでください。ただし、その計測機能も追加しており、検証実行を進めてその属性が記録されることを証明する場合は例外です。その場合は指標の本体を準備し、スパン／属性が Coval に現れてから作成してください。

プロセス内のモックまたはスタブのツールハンドラーを対象に、レイテンシー指標やエラー率指標を作成しないでください。即座に返すスタブのハンドラー（tool.latency_ms が 1 ミリ秒未満で、tool.error が常に 0）の場合、これらの指標にはシグナルがありません。実際の下流サービスではなく、スタブを計測していることになります。P90 ツールレイテンシーやツールエラー率などの指標が意味を持つのは、ハンドラーが実際の外部 API を呼び出す場合に限られます。エージェントが現在スタブを使用している場合は、その旨を記録し、実際のハンドラーが接続されるまでこれらの指標の作成を見送ってください。スタブに対して指標を作成するのは、指標を省略するよりも悪い結果になります。レイテンシーは常に優秀、エラー率は常にゼロという誤った安心感を生み、本番環境の実際の動作を覆い隠すためです。 成果物由来のマーカースパンから、レイテンシーのカスタムトレース指標を作成しないでください。Vapi ホスト型エージェントの場合、trace.timing=metadata_marker を持つ stt／llm／tts スパンは、プロバイダーの実測レイテンシーではありません。代わりに、実際のツール／ワークフロー指標とトレース対応ジャッジを使用してください。

自動ペアリングルール。 optimize-trace-observability の実行中に追加する数値属性はすべて、後のラウンドではなく、同じパスで少なくとも1つの指標案とペアにしてください。新しい属性セットを一度確認し、次のように対応させます。

• 任意のプロバイダースパン上の metrics.ttfb → P90 レイテンシー指標
• *.latency_ms／*.duration_s → P90 レイテンシー指標
• *.count／*_count／*.bytes → 呼び出しごとの平均指標
• *.total／*.amount／*.value（ビジネス関連の数値）→ ビジネス値の平均指標（例：cart.total／average／score）
• 数値の 0／1 フラグ（*.error、*.fallback_used、*.completed、*.dependency_unavailable）→ 平均／比率指標
• wait.*／*_to_first_* → P90 所要時間指標

自動ペアリングによって、顧客の疑問に答えない指標が作成される場合は、明示的に除外し、その理由を記録してください。一致する指標を提案せずにトレース拡充パスを完了しないでください。顧客に「指標はこれですべてですか？」と二度も尋ねさせてはいけません。 最初に設定する指標：実際のスパンに必要な属性が含まれている場合、業務分野に特化した指標を少なくとも1つ作成または準備し、さらにワークフロー完了率、ワークフローのブロック／依存関係によるブロック率、ツールのレイテンシのP90、ツールの失敗率、フォールバック使用率を設定します。トレースデータに顧客の運用状況を示すシグナルがすでに含まれている場合、汎用的な証拠指標だけを作成する設定では不十分です。

フェーズ2：設定の形を検証する

Coval のカスタムトレース指標フィールド：

• metric_type：METRIC_CUSTOM_TRACE
• span_name：出力されたスパン名と完全に一致する値
• metric_attribute：数値集計で必須
• aggregation_method：average、median、p90、p95、p99、max、min、sum、count、error_rate、success_rate のいずれか
• unit：省略可能な表示単位。例：s、ms、count、percent、tokens、ratio、score

対象環境で受け付けられる集計方法の正となる情報源は、公開 API／OpenAPI です。デプロイ済みの API バージョンによっては、POST /v1/metrics で受け付けられるのが average、median、p90、max、min のみです。API が count、error_rate、success_rate、p95、p99、sum を拒否する場合は、実際の数値属性に対して average や p90 など、本番環境で安全に使用できる数値指標を作成し、サポートされていない希望の指標は、公開 API とドキュメントの不整合として記録します。 デプロイ済みの API バージョンによっては、期間やスパンのステータスに基づく指標のほうが適切な場合でも、METRIC_CUSTOM_TRACE に metric_attribute が必要なことがあります。その場合は、計測時に有用な期間／ステータスを明示的な数値属性として出力し、その属性に対する指標を作成します。例：測定した insurance.workflow.dispatch_roadside スパンの期間を conversation.roadside.dispatch.latency_ms または roadside.dispatch.latency_ms にコピーし、その属性に対するP90指標を作成します。

本番環境で安全に使用できる率のパターン：スパンレベルの率の集計が受け付けられない場合は、数値の 0／1 属性を出力し、average で集計します。例：

• llm_tool_call ／ tool.error ／ average ／ ratio
• llm_tool_call ／ tool.dependency_unavailable ／ average ／ ratio
• conversation ／ workflow.dependency_blocked ／ average ／ ratio
• conversation ／ workflow.completed ／ average ／ ratio

count、error_rate、success_rate では、対象 API が許可する場合、metric_attribute を省略します。デプロイ済みの API で属性が引き続き必要な場合は、指標の意味を保てるときに限り、存在が確認されているスパン属性を使用します。それ以外の場合は、API の自動化による指標の作成を行いません。

API リクエストの例：

{
  "metric_name": "P95 LLM TTFB",
  "description": "95th percentile time to first token from llm spans.",
  "metric_type": "METRIC_CUSTOM_TRACE",
  "span_name": "llm",
  "metric_attribute": "metrics.ttfb",
  "aggregation_method": "p95",
  "unit": "s"
}

トレース対応 LLM ジャッジ指標のフィールド：

• metric_type：METRIC_LLM_BINARY、METRIC_CATEGORICAL、METRIC_NUMERICAL_LLM_JUDGE のいずれか
• prompt：判定にトランスクリプトと OTel トレースのコンテキストの両方を使用するよう、ジャッジに明示する
• include_traces：true

選択した LLM ジャッジの種類で include_traces がサポートされていることを、現在の Metrics OpenAPI で確認できた場合に作成します。適切なプロンプトでは、llm_tool_call、function.name、function.arguments、tool.error、error.type、ワークフローのルート属性など、具体的なトレースの証拠を参照します。

トレース対応ジャッジのリクエスト例：

{
  "metric_name": "Trace-Aware Tool Output Grounding",
  "description": "Uses transcript plus OTel tool-call traces to verify agent claims are grounded in successful tool outputs.",
  "metric_type": "METRIC_LLM_BINARY",
  "prompt": "Use BOTH the transcript and OTel trace context. Score YES only if the agent's customer-facing claims are supported by successful llm_tool_call outputs. Score NO if the agent asserts outcomes not supported by successful tool outputs, or if it ignores a tool.error or error.type result and presents the workflow as completed.",
  "include_traces": true
}

実際のトレースにスパン／属性が存在することを確認してから作成します。初回の検証がまだ実行中の場合は、指標のリクエスト本文を準備しながら Coval CLI／API でポーリングを続け、Trace Search または実行トレースの出力でデータを確認できたら、すぐに指標を作成します。

フェーズ 3：紐付けと検証

メトリクスを作成した後：

1. 現在の OpenAPI に対応する CLI/API の方法を使って、対象のエージェント、実行テンプレート、または実行設定にメトリクスを紐付けます。エージェントにデフォルトのメトリクスがなく、顧客が実行テンプレートを使用している場合は、エージェントのデフォルトが使われると決めつけず、実行テンプレートをパッチします。
2. 実行中の検証ランに新たに紐付けたメトリクスがすでに含まれている場合を除き、Coval CLI/API を通じて、小規模な評価を 1 回実行するか再実行します。
3. CLI/API を通じて、ランが完了するまでポーリングします。待機中は処理を止めず、トレースの品質を調べるか、引き継ぎの準備をします。
4. 新たに紐付けた各トレースメトリクスが、検証シミュレーションで終端ステータス（COMPLETED または FAILED）に到達することを確認します。出力がまだ IN QUEUE または IN PROGRESS の状態で止めないでください。
5. メトリクスが計算され、「No spans named...」または「metric_attribute is required」というエラーが発生しないことを確認します。
6. トレース対応の LLM ジャッジがトレースコンテキストを使って実行されることを、トレースのエクスポート後にそれらのメトリクスを含む検証ランを実行して確認します。
7. 計算値が顧客の質問に対して解釈可能であることを確認します。計算はできてもトレーシングの確認にしかならない場合は、診断用として扱い、引き継ぎ前に、より有用なシグナルを測るメトリクスに置き換えます。
8. データ不足が原因でメトリクスがエラーになる場合は、有用性の低いシグナルを測るようにメトリクスを変更するのではなく、計装を修正します。
9. 以前のランでメトリクスの失敗が確認されている場合は、メトリクスが壊れていると判断する前に、メトリクス／計装の更新後に最初に実行したランで検証します。
10. 作成 API がコード上は有効な集計を拒否する場合は、検証済みのフォールバックメトリクスを小さく明示的なものにし、拒否されたレスポンスを検証メモに含めます。

フェーズ 4：引き継ぎ

以下を報告します：

• 作成したメトリクスの ID と名前
• 各メトリクスのスパン／属性／集計／単位
• トレース対応のジャッジメトリクスの LLM ジャッジの種類と include_traces の状態
• 顧客の質問と、それぞれの運用上の解釈
• 作成前に各スパン／属性が存在していたことを示す証拠
• 計算の検証に使用したランまたは会話
• ラン一覧、ラン詳細、ラン結果、トレースビューアーへの Coval の直接 URL
• 意図的に作成しなかった、または置き換えた、確認のみを目的とするメトリクス
• 推奨する追加の計装