optimize-trace-observability

优化 Coval Trace 可观测性

将可用但信息不足的 Coval trace 转化为实用的调试材料。优先检查一条已验证可用的 Coval trace。如果 setup-tracing 已启动初始异步验证运行，且该运行仍在等待中，请利用等待时间安全地补充代码中可见的信息，然后在运行完成后重新检查，再宣布优化完成。

首先阅读

按需加载以下参考资料：

• ../references/span-schema.md，了解规范 span、属性、别名和防护措施
• ../references/agent-type-routing.md，了解特定框架的 trace 边界
• ../references/coval-tracing-reference.md，了解查看器／搜索行为和数据摄取限制
• 当 Agent 使用 Vapi Webhook 时，阅读 ../references/vapi-artifact-tracing.md

阶段 1：检查当前 Trace 质量

以证据为依据，而不是凭假设行事。

1. 在 Coval 中找到一条近期的仿真或对话 trace。凭据可用时，请使用 Coval CLI/API 或 Trace Search，而不是让用户提供截图。
2. 如果唯一的候选项是 setup-tracing 启动的进行中验证运行，请启动或继续 有限次数的 CLI/API 轮询，不要干等。等待期间，检查代码路径，只添加基于实现 明确安全的补充信息。
3. trace 数据可用后，检查 trace 查看器或导出的 trace dump。
4. 对当前 trace 进行分类：
   • 没有 trace
   • 存在 trace，但只有根 span／提供商 span
   • 某一种 span 类型占主导（例如，几乎所有行都是 conversation）， 这通常意味着没有发出子 span，或子 span 的命名过于宽泛
   • 存在 STT/LLM/TTS span，但缺少属性
   • 缺少工具 span
   • 父子结构扁平或具有误导性
   • 属性不安全、体积过大或基数过高
   • 存在 turn span，但无法区分（都命名为 turn，没有角色区别）——这会让 trace 查看器充斥着完全相同的行，并掩盖对话结构；解决方法见阶段 2
5. 检查是否应当补充现有框架的检测，而不是重复添加。

对于 Pipecat、LiveKit、Vapi 或现有 OTel 集成已发出的操作，除非无法补充现有 span，否则不要手动添加重复 span。 对于由 Vapi 托管的 PSTN Agent，请准确说明 Webhook 能证明什么： tool-calls Webhook 是真实的工具执行；end-of-call-report.artifact 消息是真实的转录／turn 源数据；除非 Vapi 明确提供，否则无法获取提供商内部 STT/LLM/TTS 耗时。

阶段 1b：发现代码中已有的业务事件

决定要添加什么之前，先搜索 Agent 代码中客户已经实现、但尚未追踪的业务事件 范围。搜索以下术语： 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> span 或 llm_tool_call span 的候选项，并添加一个数值属性，以便之后转化为客户信号指标。 这是最常见的覆盖盲区：客户的协议已经定义了有意义的业务事件，但这些事件从未 进入 trace，因为首次检测只覆盖了音频／LLM 流水线。

对于每个不同的业务事件，建议添加一个 span，并至少包含一个数值属性 （购物车总额、商品数量、支付金额、升级处理级别等）。 同时，找出最重要的一个垂直领域特有故障模式，并为其添加一个可用于指标的根属性，例如 roadside.dispatch.latency_ms、reservation.date.changed、 identity.verification.completed、payment_plan.blocked 或 handoff.required。不要等客户问“就这些吗？”之后才添加这些内容。

阶段 2：添加 Coval 原生 Span 覆盖

优先添加能让 Coval 跟踪 UI、内置跟踪指标和自定义跟踪指标更实用的 span：

• conversation：完整调用／会话根 span
• turn：当框架提供轮次边界时，表示一次用户／助手交互
• stt：最终语音识别结果
• stt.provider.<name>：每次 STT 提供商尝试或回退
• llm：模型调用
• tts：合成调用
• llm_tool_call：工具／函数执行
• vad：在适用时记录语音活动判断
• pipeline 或 transport：仅在有助于诊断路由／音频问题时使用

保持 span 名称稳定且基数低。将 ID、提供商名称、端点名称和动态详情放入属性中。 添加自定义业务 span 前，请遵循公开的 span 命名规范： 规范名称会获得语义颜色、标签和内置跟踪指标支持。

对于基于 Vapi artifact 的增强：

• 根据 artifact.messages 的时间窗口创建 turn.assistant 和 turn.user span（而非扁平的 turn）；按角色区分名称可在跟踪查看器中显示为不同的行；添加 turn.text（消息开头约 200 个字符），以便无需打开详情面板即可阅读内容
• 根据实时工具调用 webhook 和处理程序结果创建 llm_tool_call span
• 仅在清楚标记为 trace.timing=metadata_marker 时使用提供商标记 span，或者使用 stt_marker／llm_marker／tts_marker
• 切勿让标记 span 与其所属轮次具有相同的完整时长
• 切勿添加虚假的置信度、虚假的 TTFB 或虚假的提供商延迟值
• 根据 Vapi artifact.messages 重建轮次 span 时，请遵循 ../references/vapi-artifact-tracing.md 中的时间戳限制，避免 time 字段导致 OTel int64 溢出，以及 secondsFromStart 值被错误路由

对于时刻性注释，优先使用 OTel span 事件，而不是新增 span。 span 事件（span.add_event("simulation_id_received", {...})）是在现有 span 上添加的轻量级带时间戳标记——它不会增加 span 数量，不会影响跟踪指标，还会在跟踪查看器的父时间线上显示醒目标记。在 conversation 根 span 或相关 turn 上，将事件用于记录 simulation_id_received、first_inbound_audio、first_speech_detected、cart_sent、tool_dispatched、websocket_disconnect 和 conversation_end 等里程碑。仅对具有实质时长或父子结构的事项使用完整 span。

阶段 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
• 垂直领域专用根属性：一两个用于描述客户主要工作流风险的数值信号，例如 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，以及各角色的轮次数
• 自定义 Span：一个可用于自定义 Trace 指标的数值属性，例如 duration_ms、retry_count、confidence_score、queue_wait_ms 或 external_api_latency_ms

对于失败的提供商/工具/API Span，将 OTel 状态设为 ERROR。Coval 自定义 Trace 指标可以根据 Span 状态计算 error_rate 和 success_rate。

重要比率也应发出数值型 0/1 标记。某些公共指标创建 API 要求 metric_attribute 为数值型；对这些标记取 average，既能保留比率，也能在这些环境中正常使用。 对于由 Vapi 托管的 Agent，除非明确测量了提供商耗时，否则优先使用 tool.error、 tool.latency_ms、tool.call.count、workflow.completed、 workflow.dependency_blocked 和 workflow.fallback_used 等工具/工作流属性，而非提供商耗时属性。

阶段 4：保护客户

提交增强数据前，移除或限制以下内容：

• API 密钥、令牌、密码、会话 Cookie、账户机密和凭据
• 原始音频数据块或 Base64 音频
• 可能包含 PII 的完整提示词/响应
• 与 stt.transcript 无关的自定义属性中未设上限的转录文本
• 基数过高的 Span 名称
• 重复的成功导出重试记录

优先使用摘要和计数：

• 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 运行一次有代表性的模拟或会话，或者重用正在进行的验证运行（如果它覆盖了已更改的代码）。
2. 通过 CLI/API 轮询，直到运行完成且 Trace 数据出现。等待期间，可以准备候选指标或文档说明，不要闲等。
3. 打开 Coval Trace 查看器。
4. 确认 Trace 具有清晰的层级结构和预期的 Span 颜色。
5. 检查 Trace Search 是否可以按 Span 名称、状态、耗时、提供商或属性进行筛选。
6. 如果添加了新的数值属性，在 Span/属性出现在实际 Trace 数据中后，运行 configure-trace-metrics，创建至少一个基于这些属性的指标。

以具体内容报告更改前后的差异，例如 Span 数量、新增的 Span 名称、新增的属性，以及现在 Trace 可以回答的具体调试问题。