mcpField
D
debug-traces

debug-traces

github.com/coval-ai云与 DevOps347 次安装今天更新
代码仓库

关于 debug-traces

debug-traces 是用于排查 Coval 跟踪数据缺失、路由错误或质量不佳的技能，面向开发者提供从收集证据、执行检查到验证界面和升级问题的流程。

主要功能

  1. 01分类定位跟踪故障边界
  2. 02检查 Coval 身份验证与连通性
  3. 03按症状匹配排查步骤
  4. 04在 Coval 界面验证跟踪数据
  5. 05基于证据提供升级指导

适用场景

  1. 01调查缺失或重复的 Span
  2. 02查找存储在错误目标的跟踪数据
  3. 03诊断稀疏或误导性的跟踪数据
  4. 04确认跟踪指标和运行状态

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/coval-ai/coval-external-skills --skill debug-traces

安装后在 Claude Code 中输入/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：确定故障边界

将问题归入以下某个边界：

  • Agent 从未导出过 span
  • 导出返回了 HTTP 错误
  • 导出成功，但目标模拟、对话或组织不正确
  • span 已存储，但用户查看的位置不是相应的 UI 路径
  • span 存在，但内容稀疏或没有帮助
  • 自定义跟踪指标无法找到 span 或属性

收集：

  • 使用的端点
  • /v1/traces 的响应状态码/正文
  • 导出是否使用了 X-Simulation-Id 或 X-Conversation-Id
  • 模拟输出 ID 或对话 ID；除非这是监控对话，否则不要使用运行 ID
  • Coval Agent 类型和连接路径
  • 最近的跟踪查看器 URL、跟踪搜索 URL 或复制的跟踪转储
  • span 是以 OTLP JSON 还是 protobuf 发送的

不要索取原始 API 密钥。请用户在本地使用环境变量运行命令。分享 API 响应前，请删去 Coval Agent 的 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 已接受并为该目标存储了测试 span。
  • 对于 coval-tracing-test 或其他已知的虚构 ID，404 表示身份验证和连通性正常，但目标 ID 不存在。对于有意使用虚构 ID 的检查，请使用 --allow-not-found。
  • 对于真实目标，404 通常表示 ID 错误、组织密钥错误，或使用了运行 ID 而非模拟输出 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
  • 重试时重新发送了已接受的 spans
  • 只有自动插桩的提供商 spans，因此跟踪缺少 STT/TTS/工具上下文
  • Vapi 托管的 PSTN 跟踪使用从制品派生的 STT/LLM/TTS 标记 spans，却将其报告为实测提供商延迟
  • 在本地添加了跟踪辅助文件或 OpenTelemetry 依赖项，但未将其复制到已部署的镜像/包中
  • WebSocket 冒烟测试发送的音频少于 Agent 的响应阈值，或者 Coval 关闭套接字后，Agent 仍在流式传输较长的预设响应
  • 运行进度已达到 completed_test_cases == total_test_cases，但运行状态仍未结束，且指标输出仍在排队
  • 较早的运行反映的是过时的指标定义，却被当作当前插桩状态的依据

对于 Vapi 托管的 PSTN Agent，在将 span 视为真实的提供商可观测性数据前，请检查每个 span 的来源。tool-calls webhook 代表真实的工具执行。end-of-call-report.artifact.messages 是真实的转录/轮次证据。除非 span 包含实测提供商时序或明确的提供商字段，而不是 trace.timing=metadata_marker，否则提供商内部的 STT/LLM/TTS 时序不是真实数据。

对于 Vapi 托管的 PSTN Agent，在将 span 视为真实的提供商可观测性数据前，请检查每个 span 的来源。tool-calls webhook 代表真实的工具执行。end-of-call-report.artifact.messages 是真实的转录/轮次证据。除非 span 包含实测提供商时序或明确的提供商字段，而不是 trace.timing=metadata_marker，否则提供商内部的 STT/LLM/TTS 时序不是真实数据。

阶段 4：在 Coval UI 中验证

使用正确的界面：

  • 模拟结果：运行结果页面、OTel Traces 卡片、跟踪查看器
  • 跨通话调查：Observability 下的 Trace Search
  • 运行级流程故障：Transition Hotspots 选项卡
  • 对话监控：对话结果/跟踪搜索，而不是仅适用于模拟的路由

通常可用于筛选问题的 Trace Search 条件：

  • span 名称：llm、stt、tts、llm_tool_call
  • 状态：ERROR
  • 时长超过预期阈值
  • 属性存在：metrics.ttfb、stt.providerName、function.name、llm.finish_reason
  • Agent/测试集范围

调试指标时，除了运行摘要外，还应使用模拟指标 API/CLI 输出：

  • 指标计算期间，运行可能仍显示 IN PROGRESS
  • 每项指标输出都应达到终态（COMPLETED 或 FAILED）
  • 将 IN QUEUE / IN PROGRESS 指标输出视为待处理，而不是失败

阶段 5：修复或升级处理

如果代码仓库可用，且改动属于增量修改，请直接修复实现问题。在以下情况下，请提供准确证据并升级处理：

  • 目标 ID 属于其他组织，用户必须提供正确的密钥
  • 客户需要在代码仓库之外进行 SIP 配置或 Coval Agent 配置更改
  • Coval API 在有效重试后仍反复返回 500/503
  • 跟踪已存储，但 UI 无法加载

最后以简短的事件摘要收尾：说明观察到的状态、根本原因、已应用或需要的修复，以及可证明当前状态的确切命令或 Coval UI 检查项。

评论

支持 Markdown