optimize-trace-observability

Coval トレースの可観測性を最適化する

動作しているものの情報が乏しい Coval トレースを、デバッグに役立つ成果物に仕上げます。まず、実績のある Coval トレースを調べてください。setup-tracing が初期の非同期検証実行を開始していて、まだ完了していない場合は、待ち時間を利用して安全にコード上で確認できる情報を拡充し、完了した実行を再確認してから最適化の完了を宣言してください。

まず読むもの

必要に応じて、次のリファレンスを読み込んでください。

• ../references/span-schema.md：標準スパン、属性、エイリアス、ガードレール
• ../references/agent-type-routing.md：フレームワーク固有のトレース境界
• ../references/coval-tracing-reference.md：ビューアー／検索の動作と取り込み制限
• ../references/vapi-artifact-tracing.md：エージェントが Vapi Webhook を使用する場合

フェーズ 1：現在のトレース品質を調査する

推測ではなく、根拠に基づいて調査を始めてください。

1. Coval で、最近のトレース済みシミュレーションまたは会話を 1 件見つけます。認証情報が利用できる場合は、ユーザーにスクリーンショットを求めるのではなく、Coval CLI/API または Trace Search を使用してください。
2. 候補が setup-tracing による実行中の検証だけの場合は、範囲を限定した CLI/API のポーリングループを開始または継続し、何もせずに待たないでください。待つ間にコードパスを調べ、実装から安全だと明確に判断できる情報だけを拡充してください。
3. トレースデータが存在するようになったら、トレースビューアーまたはエクスポートしたトレースダンプを調べます。
4. 現在のトレースを分類します。
   • トレースがない
   • トレースはあるが、ルート／プロバイダースパンしかない
   • 1 種類のスパンが大半を占める（たとえば、ほとんどすべての行が conversation）。通常は、子スパンが出力されていないか、名前が広すぎることを示します
   • STT／LLM／TTS スパンはあるが、属性が不足している
   • ツールスパンがない
   • 親子構造がフラット、または誤解を招く
   • 属性が安全でない、大きすぎる、またはカーディナリティが高い
   • ターンスパンはあるが、区別されていない（すべて turn という名前で、役割の違いがない）。この場合、トレースビューアーは同じ行が並ぶだけになり、会話構造が見えなくなります。修正方法はフェーズ 2 を参照してください
5. 既存のフレームワークの計装を重複させずに拡充できないか確認します。

Pipecat、LiveKit、Vapi、または既存の OTel 統合ですでに出力されている操作については、既存のスパンを拡充できない場合を除き、手動で重複するスパンを追加しないでください。 Vapi ホスト型の PSTN エージェントでは、Webhook で確認できる内容を正確に把握してください。 tool-calls Webhook は実際のツール実行です。end-of-call-report.artifact メッセージは実際の文字起こし／ターンのソースデータです。Vapi が明示的に提供しない限り、プロバイダー内部の STT／LLM／TTS のタイミングは取得できません。

フェーズ 1b：コード内の既存のビジネスイベントを見つける

追加する内容を決める前に、顧客がすでに実装しているものの、トレースされていないビジネスイベントの対象範囲をエージェントのコードで grep します。cart、order、intent、tool_call、function_call、handoff、escalat、payment、checkout、confirm、cancel、transfer、submit、dispatch、end_of_call、conversation_end、system_notify、webhook、event_name などの語句を検索してください。 各一致箇所は、business.<event> スパン、または後から顧客シグナルのメトリクスにできる数値属性を持つ llm_tool_call スパンの候補です。 これは、最もよく見落とされるカバレッジの層です。最初の計装で音声／LLM パイプラインしか対象にしなかったため、顧客のプロトコルですでに定義されている重要なビジネスイベントがトレースに一切記録されていないことがあります。

異なるビジネスイベントごとに、数値属性を少なくとも 1 つ含むスパンを 1 つ提案してください（カートの合計額、アイテム数、支払額、エスカレーションレベルなど）。 また、その業界に固有の最も重要な障害モードを 1 つ特定し、それに対応する、メトリクス化可能なルート属性を追加してください。たとえば、roadside.dispatch.latency_ms、reservation.date.changed、identity.verification.completed、payment_plan.blocked、handoff.required などです。顧客に「これですべてですか？」と聞かれるまで、これらの追加を待たないでください。

フェーズ 2：Coval ネイティブのスパンカバレッジを追加する

Coval のトレース UI、組み込みトレースメトリクス、カスタムトレースメトリクスをより便利にするスパンを優先します：

• conversation：呼び出し／セッション全体のルート
• turn：フレームワークがターン境界を公開している場合の、ユーザーとアシスタントの 1 回のやり取り
• stt：音声認識の最終結果
• stt.provider.<name>：STT プロバイダーごとの試行またはフォールバック
• llm：モデル呼び出し
• tts：合成呼び出し
• llm_tool_call：ツール／関数の実行
• vad：関連する場合の音声アクティビティ判定
• pipeline または transport：ルーティング／音声の問題の診断に役立つ場合のみ

スパン名は安定させ、カーディナリティを低く保ちます。ID、プロバイダー名、エンドポイント名、動的な詳細情報は属性に入れます。 カスタムのビジネススパンを追加する前に、公開されているスパン命名規則に従ってください： 正規名には、セマンティックカラー、ラベル、組み込みトレースメトリクスのサポートが適用されます。

Vapi のアーティファクトベースのエンリッチメントでは：

• artifact.messages のタイミングウィンドウから、フラットな turn ではなく turn.assistant と turn.user のスパンを作成します。ロールごとに異なる名前を付けると、トレースビューアーで行が視覚的に区別されます。また、詳細パネルを開かなくても内容が読めるよう、turn.text（メッセージの先頭約 200 文字）を追加します
• ライブのツール呼び出し Webhook とハンドラーの結果から llm_tool_call スパンを作成します
• プロバイダーマーカースパンを使うのは、trace.timing=metadata_marker と明確にラベル付けする場合に限ります。または stt_marker／llm_marker／tts_marker を使用します
• マーカースパンに、囲んでいるターンと同じ全期間を設定してはいけません
• 架空の信頼度、架空の TTFB、架空のプロバイダーレイテンシー値を追加してはいけません
• Vapi の artifact.messages からターンスパンを再構築する場合は、time フィールドによる OTel int64 オーバーフローと、誤ったルーティングにつながる secondsFromStart の値を避けるため、../references/vapi-artifact-tracing.md のタイムスタンプに関するガードレールを適用します

瞬間的な注釈には、新しいスパンではなく OTel スパンイベントを優先してください。 スパンイベント（span.add_event("simulation_id_received", {...})）は、既存のスパンに付ける軽量なタイムスタンプ付きマーカーです。スパン数を増やさず、トレースメトリクスにも影響せず、トレースビューアーの親タイムラインに視認できるフラグを表示します。simulation_id_received、first_inbound_audio、first_speech_detected、cart_sent、tool_dispatched、websocket_disconnect、conversation_end などのマイルストーンには、conversation ルートまたは関連する turn 上のイベントを使用します。全期間が無視できないものや、親子構造を持つものには、完全なスパンを使用します。

フェーズ 3：価値の高い属性を追加する

../references/span-schema.md の標準属性を使用します。

価値を得るための最小限のセット：

• stt：利用可能な場合は transcript、metrics.ttfb、stt.confidence
• stt.provider.<name>：stt.providerName、metrics.ttfb、stt.confidence、プロバイダー失敗時のエラーステータス
• llm：metrics.ttfb、llm.finish_reason、gen_ai.usage.input_tokens、gen_ai.usage.output_tokens、利用可能な場合はモデル／プロバイダーのメタデータ
• tts：metrics.ttfb、安全な場合はプロバイダー／音声のメタデータ
• llm_tool_call：function.name、tool_call_id、安全かつ上限付きの場合は function.arguments、tool.latency_ms、数値の tool.error、数値の tool.dependency_unavailable、該当する場合は tool.result.count
• conversation：セッションの境界を取得できる場合は tool.call.count、tool.failure.count、数値の workflow.completed、数値の workflow.dependency_blocked、数値の workflow.fallback_used
• 特定の業界向けのルート属性：顧客の主要なワークフローリスクを示す数値シグナルを 1 つか 2 つ。例：roadside.dispatch.latency_ms、roadside.dispatch.slow、fnol.fields_captured.count、fraud.pattern_detected、reservation.date.changed、identity.verification.completed、payment_plan.blocked
• 安全に取得できる場合の会話集計値：call.cost_usd、conversation.summary.length_chars、transcript.length_chars、transcript.turn.count、およびロールごとのターン数
• カスタムスパン：duration_ms、retry_count、confidence_score、queue_wait_ms、external_api_latency_ms など、カスタムトレースメトリクスに使用できる数値属性を 1 つ

失敗したプロバイダー／ツール／API のスパンでは、OTel のステータスを ERROR に設定します。Coval のカスタムトレースメトリクスは、スパンのステータスから error_rate と success_rate を計算できます。

重要な率については、数値の 0／1 フラグも出力します。一部の公開メトリクス作成 API では数値の metric_attribute が必要です。これらのフラグに対して average を計算すると、そうした環境でも率を維持しながら利用できます。 Vapi がホストするエージェントでは、プロバイダーのタイミングを明示的に計測している場合を除き、プロバイダーのレイテンシ属性よりも tool.error、tool.latency_ms、tool.call.count、workflow.completed、workflow.dependency_blocked、workflow.fallback_used などのツール／ワークフロー属性を優先します。

フェーズ 4：顧客を保護する

エンリッチメントをコミットする前に、以下を削除するか、値に上限を設けます。

• API キー、トークン、パスワード、セッション Cookie、アカウントの秘密情報、認証情報
• 生の音声データや Base64 形式の音声データ
• PII が含まれる可能性がある完全なプロンプト／応答
• stt.transcript に関連しないカスタム属性内の上限のないトランスクリプト
• カーディナリティの高いスパン名
• 成功したエクスポートの重複リトライ

要約や件数を優先します。

• tool.result.count
• tool.result.success
• tool.error
• tool.call.count
• tool.failure.count
• workflow.completed
• workflow.dependency_blocked
• workflow.fallback_used
• prompt.message_count
• response.length
• http.status_code
• retry_count

フェーズ 5：改善された価値を確認する

変更後：

1. Coval CLI/API を通じて代表的なシミュレーションまたは会話を 1 つ実行するか、変更したコードを実行する進行中の検証ランがあれば、それを再利用します。
2. ランが完了し、トレースデータが表示されるまで CLI/API でポーリングします。処理中は何もせず待つのではなく、候補メトリクスやドキュメントのメモを準備します。
3. Coval のトレースビューアーを開きます。
4. トレースに意味のある階層構造があり、想定されるスパンの色が表示されていることを確認します。
5. Trace Search でスパン名、ステータス、期間、プロバイダー、属性を使って絞り込めることを確認します。
6. 新しい数値属性を追加した場合は、実際のトレースデータでスパン／属性が表示された後に configure-trace-metrics を実行し、それらの属性を使ったメトリクスを少なくとも 1 つ作成します。

スパン数、新しいスパン名、新しい属性、トレースで新たに回答できるようになった具体的なデバッグ上の疑問など、変更前後の違いを具体的に報告します。