setup-tracing

设置 Coval 跟踪

在客户的 Agent 中设置跟踪，以最小的增量改动生成真实的 Coval 跟踪，然后根据 Agent 实际连接 Coval 的路径验证该跟踪。

从客户的 Agent 侧操作。不要假设可以访问 Coval 内部后端、前端、文档、向导、研究资料或示例源代码仓库，也不要向客户索要这些内容。只能使用客户的代码仓库、公开的 Coval 文档、公开的 SDK 示例、Coval CLI/API，以及获取的公开 OpenAPI 规范。 代码改动应放在客户的 Agent/服务代码仓库中。Coval 侧的更改必须仅限于通过 Coval CLI、公开 API 或控制面板进行的文档化配置，并且应在修改前予以说明。

预检

1. 确认 Agent 代码仓库或服务的范围。在单体仓库中，除非用户明确要求，否则不要为所有服务添加埋点。
2. 检查 Coval 身份验证，但不要读取密钥文件：

   coval whoami
   coval agents list --format json
   

   如果无法使用 CLI，请从用户的 Shell 环境中读取 COVAL_API_KEY 并直接调用 API。切勿打印或存储原始密钥。通过 API 列出 Agent 时，在显示输出前应对 metadata 脱敏，因为某些提供商集成会在其中存储模型 API 密钥。
3. 在编写 API 集成之前，先获取当前的 API 结构：

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

   如需更广泛地查找文档，请先获取 https://docs.coval.dev/llms.txt，然后获取任务所需的具体公开文档页面。
4. 仅在客户拥有的代码范围内操作。不要将 coval-ai/backend、coval-ai/frontend、coval-ai/docs、coval-ai/wizard、内部工程文档或私有 Coval 代码仓库作为本地源代码来引用或要求访问。客户侧 Agent 可使用的参考资料包括公开文档、公开 SDK 示例，以及已安装技能的参考文件。
5. 编辑前请阅读共享参考资料：
   • ../references/coval-tracing-reference.md
   • ../references/agent-type-routing.md
   • ../references/span-schema.md
   • 如果 Agent 基于 Vapi，请阅读 ../references/vapi-artifact-tracing.md

阶段 1：只读分析

完成此阶段前不要编辑文件。

请确定：

• 语言和包管理器
• 应用启动命令及一个有代表性的本地调用方式
• Agent 框架或提供商技术栈：Pipecat、LiveKit、Vapi、Twilio、WebSocket、直接使用 OpenAI/Anthropic、自定义循环等
• 附近是否有相同技术栈的 Agent 实现（如同一工作区中存在），且已能发出更丰富的跟踪；应将其作为增量埋点的参考，而不是重新设计 Span 结构
• Coval Agent 类型和连接路径：SIP 入站、PSTN 入站、语音外呼、WebSocket 语音/聊天，或对话监控
• 每次调用对应的 Coval ID 如何传入 Agent 进程
• 现有遥测的负责人：OpenTelemetry、Sentry、Datadog、Honeycomb、Langfuse、Arize、LangSmith、Traceloop，或自定义 OTLP 导出器
• 短生命周期进程的行为以及关机/刷新路径
• 需要修改的客户所有文件，以及必须通过 CLI/API/控制面板而非代码进行的 Coval 配置更改

返回简洁的分析摘要。如果目标服务或代码仓库范围不明确，请先询问再编辑。不要让客户从菜单中选择关联路径。客户通常无法从外部判断 SIP 标头、调用前 Webhook 或触发器载荷是否受支持；请根据发现的 Agent 配置和以下决策规则推断最佳路径。

阶段 2：选择关联路径

每次导出只能使用一个目标标头：

• 模拟：X-Simulation-Id，其值为模拟输出 ID
• 对话监控：X-Conversation-Id，其值为 POST /v1/conversations:submit 返回的 conversation_id

如果仓库和 Coval Agent 配置明确表明某条路径更安全，请自行选择该路径。不要提出开放式的“我应该使用哪条路径？”问题。按以下顺序决策：

1. 如果当前连接路径已将 Coval ID 传递到进程中，请使用该路径。例如：SIP 参与者属性、出站触发器负载、WebSocket 初始化负载，或监控用的 conversation_id。
2. 如果当前 Coval Agent 记录或已获取的 OpenAPI 确认存在现有的呼叫前/注册 Webhook 字段，且服务已提供合适的端点，请配置或复用该 Webhook。
3. 对于没有已验证 SIP 标头且未确认已接入 Coval 呼叫前 Webhook 的 PSTN 入站电话 Agent，默认使用独立的注册端点以及一个冒烟测试启动器，在通话前立即注册 simulation_output_id。这是最安全的首次验证方式，因为它无需猜测 Coval Agent 元数据的结构，也不会修改客户的 Agent 配置。验证成功后，说明生产环境的升级方案：在可用时，将同一端点接入已验证的 Coval 呼叫前 Webhook 字段；或者在客户需要由 Coval 管理每通电话的注入时配置 SIP。
4. 仅当所有可行路径都需要你无法推断的策略或部署决策时，才向客户提问，例如是否允许公开新的 Webhook、更新 Coval Agent 配置或配置 SIP 路由。在这种情况下，先给出一项建议，解释原因，并询问所需的最少批准。

对于文档中已定义且当前为空的字段，Coval 侧的配置变更若纯粹是增量式的（例如，将 initialization_json 从 "{}" 设为文档规定的 {"simulation_id":"{{simulation_id}}"} 占位符，或填入空的 pre_call_webhook_url），无需征求同意——客户提出的“让跟踪记录正常工作”意图已包含此意，而且该变更可通过同一 PATCH 轻松撤销。在交接说明中展示变更前后的值，但无需询问即可继续。对于删除配置、降低身份验证级别、覆盖非空字段，或修改电话号码、SIP 路由、测试集、Webhook 密钥等共享资源的变更，务必先征求同意。

根据 ../references/agent-type-routing.md 选择路径：

• SIP 入站语音：从 SIP 标头或框架参与者属性中提取 X-Coval-Simulation-Id。
• PSTN 入站电话：不要期待存在 SIP 标头。添加或配置 pre_call_webhook_url / 注册 Webhook 关联，或引导客户配置 SIP 地址。
• 出站语音：在触发器负载中传递 simulation_output_id，并在触发器处理程序中读取。
• WebSocket 语音/聊天：在初始设置负载或初始化 JSON 中传递模拟输出 ID。
• 对话监控：在通话期间缓冲跨度，在通话结束时提交对话，然后使用 X-Conversation-Id 导出缓冲的跨度。

对于直接 WebSocket Agent，优先使用显式初始化负载配置 Coval 元数据，例如：

{"simulation_id": "{{simulation_id}}"}

然后将第一个非音频帧视为设置元数据，提取 simulation_id 或 simulation_output_id，并且仅在该 ID 已存在后才使用 X-Simulation-Id 导出。当前生产示例使用 {{simulation_id}}；如果文档提到 {{simulation_output_id}}，请先验证当前 Agent 元数据行为，再将任一名称硬编码。

阶段 3：实施增量式监测

优先使用现有的遥测管理方。如果应用已有 TracerProvider，请向其添加 Coval 导出器/处理器，而不是替换该 Provider。如果尚未设置遥测，请创建一个中央模块，例如 coval_tracing.py、covalTracing.ts 或 coval_tracing.go，并让 Agent 入口专注于业务逻辑和 Webhook 路由。除非仓库是一个小型的单文件原型，否则不要将最终实现写成大型的内联追踪代码块，放在 server.py、app.ts 或主 Webhook 处理程序中。 实现要求：

• 端点：https://api.coval.dev/v1/traces
• 认证请求头：使用环境变量中的 x-api-key 或 X-API-Key，绝不写入字面形式的密钥
• 超时：30 秒
• 资源：将 service.name 设置为 Agent 或服务名称。已知时，还要添加客户可见且稳定的资源属性：service.namespace、agent.name、agent.provider、coval.agent_type 和 coval.correlation.method。
• 只导出一个目标请求头：X-Simulation-Id 或 X-Conversation-Id
• 仅在 Coval ID 尚未可用时缓冲 Span；并限制缓冲区大小
• 有可用的标准 OpenTelemetry SDK 时，使用该 SDK。对于 Coval 目标 ID 在 Span 启动后才到达的调用流，使用基于 SDK 的缓冲区，例如 InMemorySpanExporter，然后在 ID 已知后，用 OTLPSpanExporter 导出已结束的 Span。除非该语言／运行时没有可用的 SDK，否则避免手动编写 OTLP JSON 导出器。
• 高流量 Agent 使用 BatchSpanProcessor 或等效机制，并确保批次大小远低于 3-4 MB
• 短生命周期进程退出前，刷新并关闭追踪
• 仅重试失败的批次；Coval 以仅追加方式存储 Span，不会对成功的重试进行去重
• 更新部署打包配置。Dockerfile、无服务器部署包、Pipecat Cloud 软件包以及 Fly／Render／Heroku 部署必须包含任何新增的追踪辅助模块和依赖文件。
• 优先使用 ../references/span-schema.md 中的规范 Span 名称：llm、tts、stt、stt.provider.<name>、vad、llm_tool_call、turn、conversation、pipeline 和 transport。这些名称决定语义 UI 标签、颜色和内置追踪指标。
• 添加工具或工作流 Span 时，从首个实现版本起就包含可用于指标的数值属性：tool.latency_ms、数值型 tool.error、数值型 tool.dependency_unavailable、tool.call.count、tool.failure.count、数值型 workflow.completed、数值型 workflow.dependency_blocked，以及可用时的数值型 workflow.fallback_used。这样 configure-trace-metrics 就不必只使用验证型指标。
• 首轮实现时，为客户最重要的故障模式添加一个特定垂直领域的工作流 Span 或根属性。例如：roadside.dispatch.latency_ms、reservation.date.changed、identity.verification.completed、payment_plan.blocked 或 handoff.required。如果代码库明显包含关键业务路径，仅有通用工具指标是不够的。
• 在会话根 Span 上发出 OTel Span 事件，记录 simulation_id_received、dispatch_called、delay_acknowledged、callback_offered、fnol_started、fnol_completed、booking_attempted 或 escalation_triggered 等特定时刻的业务里程碑。时间线标记使用事件；具有持续时间的工作使用 Span。
• 对于 Webhook 式语音 Agent，如果工具调用或轮次 Webhook 已有 Coval 目标 ID，不要只依赖通话结束时的最终事件。目标 ID 已知时导出每个事件的 Span，或先缓冲，待 ID 已知后一次性刷新。避免在成功导出后重放 Span，因为 Coval 追踪接收采用仅追加方式。
• 对于托管在 Vapi 上的 PSTN Agent，在基本工具调用追踪正常工作后，解析 end-of-call-report.artifact.messages。使用 Vapi 消息窗口生成 turn Span，但不要伪造提供商延迟。如果从 Artifact 消息生成 stt、llm 或 tts Span，请将其标记为元数据标记，使用 trace.source=vapi_artifact、trace.timing=metadata_marker 和 trace.duration_note；或者使用带标记后缀的 Span 名称。不要根据这些标记 Span 创建 LLM/STT/TTS 延迟指标。

对于 Python 语音 Agent，客户代码库中已有的生成式 coval_tracing.py 辅助模块可以作为可接受的基线，但应针对发现的连接路径和现有遥测进行改进。

第 4 阶段：最小跨度覆盖

第一个可用的跟踪应包含：

• 如果框架提供调用边界，则包含根 conversation 或等效的会话跨度
• 至少包含一个与实际 Agent 路径相符的 stt、llm、tts 或 llm_tool_call 跨度
• 框架能够提供时，确保父子关系正确
• service.name 资源元数据
• 与 Coval 兼容的目标 ID 路由

如果应用目前还无法暴露 STT/TTS/LLM 内部信息，先交付最小可用跟踪，然后使用 optimize-trace-observability 丰富信息。

反模式：为每个分块或每帧创建传输跨度。 语音/实时 Agent 会将音频流拆分成许多小块（通常为 20-100 ms）。每个块都生成一个 OTel 跨度，会产生数百个微型跨度，在视觉上淹没跟踪查看器，并让真正的 turn/tts/llm 跨度缩成难以看见的细条——即使跟踪并非空白，看起来也会像是空的。应将每个分块的活动汇总为父流跨度上的计数器属性：

• 在 tts 跨度上记录 audio.chunks_sent（计数）和 audio.chunk_target_ms（配置的节奏）
• 在 turn 或 stt 跨度上记录 audio.chunks_received
• audio.payload_bytes、audio.duration_s 已记录总量

同样的规则适用于逐帧的 transport.recv_audio、每个 WebSocket 事件的 ping，以及逐 Token 的流式跨度。每个高层操作创建一个跨度；每个分块的细节应写入数值属性。

第 5 阶段：验证

先运行本地检查：

python -m compileall .
npm test
npm run typecheck
go test ./...

使用与仓库匹配的检查；不要臆造包管理器命令。

然后通过 CLI/API 启动 Coval 验证，并在其运行期间开展有效工作。Coval 模拟和监控对话都是异步的；启动后不要闲置。

1. 使用发现的 Coval CLI/API 路径，通过客户使用的同一种 Coval Agent 类型启动一次真实测试。有 CLI 命令时优先使用；否则先获取 OpenAPI，再调用公共 API。记录启动后返回的运行 ID、模拟输出 ID、对话 ID、仪表板 URL 或轮询端点。
2. 通过 CLI/API 启动有界轮询循环。记录所用命令或端点、轮询间隔和超时时间。不要打印 API 密钥或 Coval Agent 响应中的原始提供商元数据。 对于模拟，不要只等待 GET /v1/runs/{run_id} 暴露 results.output_ids；该信息可能直到完成后才更新，那时再注册 PSTN/webhook 就太迟了。还要轮询： GET /v1/simulations?filter=run_id%3D%22<RUN_ID>%22，立即注册首个返回的 simulation_id / 模拟输出 ID，然后继续监视运行。
3. 运行处于等待状态时，继续进行非阻塞式追踪改进：
   • 添加代码路径中可见的安全跨度增强信息，例如稳定的 conversation、turn、stt、llm、tts、llm_tool_call、 transport 或提供商跨度
   • 添加有界且高价值的属性，例如 metrics.ttfb、令牌数、结束原因、工具名称、安全的工具参数摘要、状态和错误
   • 添加可转化为指标的客户信号数值属性，例如 tool.error、tool.latency_ms、tool.call.count、workflow.dependency_blocked、workflow.completed 和 workflow.fallback_used
   • 改进实现过程中发现的刷新/关闭、缓冲、批次大小、重试或部署打包问题
   • 根据预期跨度和已有的历史 Coval 追踪数据，准备自定义追踪指标候选项；通用时长或跨度计数指标只能作为诊断证据，除非它们能回答客户的运营问题
   • 当需要追踪上下文来评估顺序、工具输出依据、工具调用前验证或工具错误恢复时，准备设置 include_traces=true 的追踪感知型 LLM 评判指标候选项
4. 等待期间，只有真实追踪数据已证明跨度名称和指标属性存在时，才创建自定义追踪指标；证明数据可以来自历史追踪运行，也可以来自进行中的验证（跨度出现在 Trace Search 中后）。如果此次验证是该 Agent 的首次追踪，则等待期间先拟定指标定义，并在运行产生已确认的跨度后立即创建。 如果 Metrics OpenAPI 支持 include_traces，且追踪感知型 LLM 评判指标的提示词依赖于首条追踪已证明存在的追踪上下文，则应在后续验证运行之前创建这些指标。
5. 运行结束后，确认 Agent 导出返回了 200，或导出器记录了批次已成功接收。独立测试脚本返回 404 只能证明身份验证/连接正常，不能证明生命周期接线正常。
6. 打开 Coval 运行或对话结果，并确认 OTel Traces 卡片或 Trace Search 结果已显示。
7. 检查追踪中是否包含预期跨度和属性。如果缺失、稀疏、重复或关联到了错误结果，请停止继续创建指标，并在继续之前应用 debug-traces。
8. 追踪密度自检。 宣布成功前，按名称统计跨度数量。如果某个跨度名称占总跨度的比例超过约 70%，且这些跨度各自都短于约 50 ms，那么它几乎肯定是逐块/逐帧噪声。将其合并为父跨度上的计数器属性，并在向客户打开结果前重新部署；否则追踪查看器会显得空空如也。不要等客户指出视觉噪声。
9. 从导出器确认关联已激活，而不是查看已有的 Agent 计数器。 Agent 上已有的计数器（例如 non_audio_messages 或 non_setup_frames）通常会在设置/初始化分支返回后才递增，因此即使关联成功也可能显示 0。模拟 ID 已到达导出器的权威信号是 OTel 日志行（activated OTLP export simulation_id=<id>）或批处理器的批次已接收日志。先检查这些信号；只有导出器从未激活时，才追查计数器。
10. 确认初始追踪后，完成所有已准备的指标创建；如果公共 API 支持，则通过 CLI/API 运行一次后续计算/预览/关联运行检查。
11. 如果更改了指标定义或关联了新指标，请在更改后执行验证，并持续轮询，直到运行状态为终态（COMPLETED、FAILED 或 CANCELLED），且每个新关联的追踪指标在模拟上都有终态输出（COMPLETED 或 FAILED）。即使 progress.completed_test_cases 已等于 total_test_cases，只要输出仍为 IN QUEUE / IN PROGRESS，就不要停止。
12. 如果以往运行中有 FAILED 的追踪指标，请对照实施了你的埋点和指标更改后启动的第一轮运行进行验证，不要把旧运行当作当前状态的证明。较早运行中的指标失败，可能是因为当时的定义已过时，不再与最新埋点相匹配。 对于 WebSocket Agent，请让冒烟交互持续足够长的时间，以触发 Agent 的响应阈值。如果客户端发送的音频太少，或 Agent 等待的静音／音频时长超过 Coval 发送的时长，即使导出器已正确接入，追踪也可能看起来无法正常工作。如果 tts span 在播放部分音频后因 WebSocket 断开而标记为 ERROR，请缩短预设响应，或在客户端关闭连接时停止流式传输。

仅检查连通性的可选项：

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

如果出现 404 和 Simulation output not found，说明密钥已到达 Coval 且身份验证成功，但这并不能证明 Agent 调用生命周期已接通。

交接

结束时提供：

• 更改了哪些文件及原因
• 使用的确切关联路径
• 客户如何设置必需的环境变量
• 运行的命令，包括 Coval 启动和轮询命令／API 端点
• 用于证明的 Coval 追踪 URL 或 simulation/conversation ID
• 以下页面的 Coval 直接 URL：
  • runs 列表（https://app.coval.dev/<org-slug>/runs?sort=createdAt%3Adescending）
  • run 详情（https://app.coval.dev/<org-slug>/runs/<run-id>）
  • run 结果（https://app.coval.dev/<org-slug>/runs/<run-id>/results/<simulation-output-id>）
  • 追踪查看器（https://app.coval.dev/<org-slug>/runs/<run-id>/results/<simulation-output-id>/traces）
• 已创建、暂存或推迟的自定义追踪指标及原因
• 仍需通过 optimize-trace-observability、configure-trace-metrics 或 debug-traces 处理的任何问题