debug-traces

Coval のトレースをデバッグする

Coval でトレースが表示されるはずなのに、見つからない、誤っている、少ない、重複している、または本番環境のデバッグに役立たない場合に、このスキルを使用します。

最初に読むもの

読み込むファイル：

• ../references/debugging-matrix.md
• ../references/coval-tracing-reference.md
• ../references/agent-type-routing.md
• トレースの品質に問題がある場合は ../references/span-schema.md
• Vapi の Webhook トレースをデバッグする場合は ../references/vapi-artifact-tracing.md

フェーズ 1：問題の発生箇所を特定する

問題を次のいずれかに分類します。

• エージェントがスパンを一度もエクスポートしていない
• エクスポートで HTTP エラーが返された
• エクスポートは成功したが、対象のシミュレーション、会話、または組織が間違っている
• スパンは保存されているが、ユーザーが確認した場所に UI のルートがない
• スパンは存在するが、情報が少ない、または役に立たない
• カスタムトレースメトリクスでスパンまたは属性を見つけられない

次の情報を収集します。

• 使用したエンドポイント
• /v1/traces のレスポンスステータスと本文
• エクスポートで X-Simulation-Id と X-Conversation-Id のどちらを使用したか
• シミュレーション出力 ID または会話 ID。監視対象の会話でない限り、run ID は使用しません
• Coval のエージェントタイプと接続経路
• 最近のトレースビューアー URL、Trace Search URL、またはコピーしたトレースダンプ
• スパンを OTLP JSON と protobuf のどちらで送信したか

生の API キーを求めないでください。環境変数を使ってコマンドをローカルで実行するようユーザーに依頼してください。API レスポンスを共有する前に、Coval エージェントの metadata をマスキングしてください。プロバイダーのキーがそこに保存されている可能性があります。

フェーズ 2：最小限のチェックを実行する

Coval の認証を確認します。

coval whoami

必要に応じて、単独の接続確認を実行します。

python skills/traces/setup-tracing/scripts/send-test-span.py \
  --api-key "$COVAL_API_KEY" \
  --simulation-id "$SIMULATION_OUTPUT_ID"

結果の解釈：

• 200 は、Coval がその対象のテストスパンを受け付け、保存したことを意味します。
• coval-tracing-test やその他の既知の偽 ID に対する 404 は、認証と接続は機能しているものの、対象 ID が実在しないことを意味します。意図的に偽 ID を確認する場合は、--allow-not-found を使用してください。
• 実在する対象に対する 404 は、通常、ID または組織キーが間違っているか、シミュレーション出力 ID の代わりに run ID を使用していることを意味します。

会話の監視では、次を使用します。

python skills/traces/setup-tracing/scripts/send-test-span.py \
  --api-key "$COVAL_API_KEY" \
  --conversation-id "$CONVERSATION_ID"

フェーズ 3：トラブルシューティングマトリックスを適用する

../references/debugging-matrix.md を使って、症状を原因と修正方法に対応付けます。

発生確率の高い原因：

• ターゲットヘッダーがない、または両方のターゲットヘッダーが送信されている
• X-Simulation-Id にシミュレーション出力 ID ではなく、実行 ID が含まれている
• 監視対象ではない実行に X-Conversation-Id が使われている
• PSTN の電話経路で、受信できない SIP ヘッダーが想定されている
• WebSocket の初期化ペイロードにシミュレーション出力 ID が含まれていなかった
• 別の組織の API キーが使われている
• ペイロードが約 3～4 MB を超えている
• 再試行によって、すでに受理されたスパンが再送されている
• 自動計装されたプロバイダースパンしかなく、トレースに STT／TTS／ツールのコンテキストがない
• Vapi ホスト型 PSTN トレースでは、アーティファクト由来の STT／LLM／TTS マーカースパンが使われているが、計測されたプロバイダーのレイテンシとして報告されている
• トレーシングヘルパーファイルや OpenTelemetry の依存関係がローカルに追加されたものの、デプロイ済みイメージ／バンドルにコピーされていない
• WebSocket のスモークテストで、エージェントの応答しきい値に満たない量の音声しか送信されていない。または、Coval がソケットを閉じた後も、エージェントが長い定型応答をストリーミングした
• 実行の進行状況で completed_test_cases == total_test_cases に達しているものの、実行ステータスがまだ終端状態ではなく、メトリクス出力が引き続きキューに入っている
• 古い実行が古いメトリクス定義を反映しているにもかかわらず、現在の計装状態の証拠として扱われている

Vapi ホスト型 PSTN エージェントでは、各スパンを実際のプロバイダー監視とみなす前に、そのスパンのソースを確認します。tool-calls Webhook は実際のツール実行です。end-of-call-report.artifact.messages は実際の文字起こし／ターンの証拠です。スパンに計測済みのプロバイダータイミングまたは明示的なプロバイダーフィールドが含まれておらず、trace.timing=metadata_marker である場合、プロバイダー内部の STT／LLM／TTS のタイミングは実際のものではありません。

Vapi ホスト型 PSTN エージェントでは、各スパンを実際のプロバイダー監視とみなす前に、そのスパンのソースを確認します。tool-calls Webhook は実際のツール実行です。end-of-call-report.artifact.messages は実際の文字起こし／ターンの証拠です。スパンに計測済みのプロバイダータイミングまたは明示的なプロバイダーフィールドが含まれておらず、trace.timing=metadata_marker である場合、プロバイダー内部の STT／LLM／TTS のタイミングは実際のものではありません。

フェーズ 4：Coval UI で確認する

適切な画面を使います：

• シミュレーション結果：実行結果ページ、OTel Traces カード、トレースビューアー
• 通話をまたいだ調査：Observability の Trace Search
• 実行レベルのフロー障害：Transition Hotspots タブ
• 会話の監視：シミュレーション専用のルートではなく、会話の結果／トレース検索

問題の切り分けに役立つ Trace Search のフィルター：

• スパン名：llm、stt、tts、llm_tool_call
• ステータス：ERROR
• 想定しきい値を超える期間
• 属性の存在：metrics.ttfb、stt.providerName、function.name、llm.finish_reason
• エージェント／テストセットのスコープ

メトリクスのデバッグでは、実行サマリーに加えてシミュレーションメトリクス API／CLI の出力を使います：

• メトリクスを計算中の間、実行は引き続き IN PROGRESS と表示されることがあります
• 各メトリクス出力は終端状態（COMPLETED または FAILED）になるはずです
• IN QUEUE／IN PROGRESS のメトリクス出力は、失敗ではなく保留中として扱います

フェーズ 5：修正またはエスカレーションする

リポジトリを利用でき、変更が追加的なものである場合は、実装上の問題を直接修正します。次の場合は、正確な証拠を添えてエスカレーションします：

• ターゲット ID が別の組織に属しており、ユーザーが正しいキーを提供する必要がある
• 顧客が、リポジトリ外での SIP プロビジョニングまたは Coval エージェント設定の変更を必要としている
• 有効な再試行後も Coval API が繰り返し 500／503 を返す
• トレースはストレージに存在するものの、UI で読み込めない

最後に、観測されたステータス、根本原因、適用済みまたは必要な修正、現在の状態を証明する正確なコマンドまたは Coval UI での確認方法を含む、短いインシデント形式の要約を記載します。