用途：当客户预期在 Coval 中看到追踪数据，但数据缺失、错误、稀疏、重复或对生产调试无帮助时使用本技能，按阶段定位故障边界、执行最小检查、套用排查矩阵并在 Coval UI 中验证，最后修复或升级。
必要用法：先加载 ../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。阶段一收集 endpoint、/v1/traces 响应状态与正文、导出是否使用 X-Simulation-Id 或 X-Conversation-Id、simulation output ID 或 conversation ID、Coval agent 类型与连接路径、trace viewer/Trace Search URL 或 trace dump、OTLP 格式（JSON 或 protobuf）。不要索取原始 API key，让用户在本地通过环境变量运行命令；共享 API 响应前脱敏 Coval agent 元数据，其中可能存储 provider key。
最小检查：运行 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 不存在，可使用 --allow-not-found 做有意假 ID 检查；对真实目标返回 404 通常表示 ID 错误、org key 错误或误用 run ID 而非 simulation output ID。对话监控使用 --conversation-id "$CONVERSATION_ID"。
常见原因：缺少目标 header 或两个目标 header 同时发送；X-Simulation-Id 使用 run ID 而非 simulation output ID；X-Conversation-Id 用于非监控运行；PSTN 电话路径期望无法到达的 SIP header；WebSocket 初始化载荷未包含 simulation output ID；组织 API key 错误；载荷超过约 3-4 MB；重试重发已接受的 span；仅有自动插桩的 provider span 导致缺少 STT/TTS/tool 上下文；Vapi 托管 PSTN 追踪使用 artifact 派生 marker span 却报告为实测 provider 延迟；追踪辅助文件或 OpenTelemetry 依赖本地添加但未复制进部署镜像/包；WebSocket 冒烟测试发送的音频少于 agent 响应阈值，或 Coval 关闭 socket 后 agent 仍流式输出长固定响应；run 进度 completed_test_cases == total_test_cases 但 run 状态仍未终止、metric 输出仍在排队；旧 run 反映陈旧 metric 定义却被当作当前插桩状态证明。对 Vapi 托管 PSTN agent，需先检查每个 span 来源：tool-calls webhook 是真实工具执行，end-of-call-report.artifact.messages 是真实转录/轮次证据，除非 span 有实测 provider 计时或显式 provider 字段而非 trace.timing=metadata_marker，否则 provider 内部 STT/LLM/TTS 计时不算真实可观测性。
UI 验证：模拟结果查看 run result 页、OTel Traces 卡片、trace viewer；跨调用调查使用 Observability 下的 Trace Search；run 级别流程失败查看 Transition Hotspots 标签页；对话监控使用 conversation result/trace search，而非仅模拟路由。常用过滤条件包括 span name: llm、stt、tts、llm_tool_call，status: ERROR，时长超过预期阈值，attribute 存在 metrics.ttfb、stt.providerName、function.name、llm.finish_reason，以及 agent/test set 范围。调试 metric 时同时使用 simulation metrics API/CLI 输出：run 可能在 metric 计算时仍显示 IN PROGRESS，每个 metric 输出应进入 COMPLETED 或 FAILED 终态，IN QUEUE/IN PROGRESS 视为待处理而非失败。
修复或升级：仓库可用且改动为增量时直接修复实现问题；当目标 ID 属于其他组织需用户提供正确 key、客户需要 SIP 配置或 Coval agent 配置变更、Coval API 在有效重试后重复返回 500/503、追踪已存储但 UI 无法加载时，携带精确证据升级。最后给出简短事件式总结：观察状态、根因、已应用或所需修复、证明当前状态的精确命令或 Coval UI 检查。限制：资料未提供完整命令示例、各命令全部参数、具体阈值数值及支持平台范围。