configure-trace-metrics

配置 Coval Trace 指标

只有在目标 Agent 至少存在一条真实 Trace 后，才能根据 Trace 数据创建指标。如果 setup-tracing 验证运行当前仍在等待中，请利用等待时间盘点现有 Trace 并准备指标定义。只有当历史 Trace 或正在运行的验证已证明目标 Span 和属性存在时，才可在等待期间创建指标。

质量标准：证明数据已写入的指标并非最终目标。只证明 Trace 已到达的指标（例如通用调用时长或原始 Span 数量）只能用于诊断，除非它能帮助客户做出决策。优先选择能揭示工作流瓶颈、影响用户的故障、依赖项健康问题、延迟长尾、成本驱动因素、回退、交接或完成信号的指标。

只要 Trace 数据支持，此技能通常应生成两种指标：

• 针对真实 Span 属性的数值型 METRIC_CUSTOM_TRACE 指标
• 感知 Trace 的 LLM 裁判指标（METRIC_LLM_BINARY、 METRIC_CATEGORICAL 或 METRIC_NUMERICAL_LLM_JUDGE），并设置 include_traces: true，以便在 Trace 能帮助判断仅凭对话记录无法察觉的序列、依据或恢复行为时使用

只有当 Trace Span 是合适的数据来源时，才使用 Trace 指标。每次调用的轮数通常更适合使用对话记录、模拟输出或评估指标。当 Agent 在真实 Span 上输出安全的数值时，购物车总额、订单总额、提供商回退、工具故障或下游延迟等数据则适合作为 Trace 指标。

请先阅读

加载：

• ../references/trace-metrics-playbook.md
• ../references/span-schema.md
• ../references/coval-tracing-reference.md
• 当 Agent 使用 Vapi Webhook 时，加载 ../references/vapi-artifact-tracing.md

第 0 阶段：盘点

检查身份验证和当前资源：

coval whoami
coval agents list --format json
coval metrics list --include-builtin --format json

如果 CLI 无法创建所需的指标格式，请先获取最新的 OpenAPI，再使用 API：

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

将实时目标 API 视为权威来源。在 api.coval.dev 上，自定义 Trace 指标的验证规则可能因部署环境而异。如果创建操作返回聚合方法验证错误，请改用该环境接受的生产环境选项，并在交接说明中指出公开 API/文档存在差异。

收集：

• Agent ID 和类型
• 最近一次带有 Trace 的运行或对话，或由 setup-tracing 轮询中的验证运行
• Trace Search 建议、Trace 查看器或复制的 Trace 转储中可用的 Span 名称和属性
• 已附加的现有内置 Trace 指标
• 现有 LLM 裁判指标，以及是否已启用 include_traces
• 客户用例或垂直领域

第 1 阶段：确定指标候选项

使用操作手册提出一小组候选项。与其创建大量嘈杂的指标，不如优先选择 3-6 个高信号指标。

对于每个候选项，写明它要回答的客户问题。如果唯一的问题是“Trace 是否正常工作？”，则删除该指标，或将其标记为仅用于诊断。如果同样的答案通过非 Trace Coval 数据计算效果更好，也应删除该指标。

基线建议：

• 语音 Agent：LLM/TTS/STT 首字节时间（TTFB）、令牌用量、工具调用次数；当 stt Span 包含 transcript 时，计算 STT WER
• 实时或 WebSocket Agent：模型/实时延迟、响应首字节时间（TTFB）、令牌用量、流/错误 Span
• 对话监控：p95/p99 延迟、工具/API 错误率、关键事件计数、生产环境回退率
• 自定义业务逻辑：针对最重要的客户特定工作流瓶颈或故障模式，设置一项指标 当轨迹包含工具或工作流跨度时，优先创建以下高信号指标：
• 一个与客户所在领域工作流相关的垂直领域故障模式指标，例如道路救援调度延迟 P90、预订日期损坏率、付款计划受阻率、身份验证完成率或触发升级率
• 依赖项受阻率：必需的外部依赖项导致无法完成
• 工具故障率：工具/API 调用返回错误或不可用的响应
• 工具延迟 P90：下游工具变慢但尚未导致调用失败
• 购物车总额平均值或订单总额平均值：结账期间记录的业务价值
• 工作流完成率或回退率：是否实现了预期的客户结果

当轨迹包含工具调用或工作流属性时，优先创建以下高信号、感知轨迹的 LLM 评估指标：

• 工具输出依据性：口头陈述与成功的工具输出一致，且不会忽略 tool.error 或 error.type
• 工具使用前验证：只有当对话记录和轨迹显示已完成验证后，才使用敏感标识符或账户专属工具
• 工具故障恢复：依赖项故障或工具响应不可用后，Agent 会适当地重新提示、重试、升级处理或拒绝
• 信息复述规范：在工具调用中使用敏感标识符前，Agent 会先确认这些标识符

除非客户明确要求原位更新现有指标，否则应优先创建现有 LLM 评估指标的感知轨迹版本，而不是悄悄修改现有生产指标。

如果实际轨迹数据中不存在某个属性，请勿为其创建自定义轨迹指标，除非你也会添加相应的检测埋点，并且正在进行验证运行以证明其有效。在这种情况下，先暂存指标正文，待跨度/属性在 Coval 中出现后再创建指标。

请勿针对进程内的模拟或桩工具处理程序创建延迟或错误率指标。如果工具处理程序是立即返回的桩（tool.latency_ms 小于 1 毫秒，且 tool.error 始终为 0），这些指标就没有信号——它们测量的是桩，而不是真实的下游服务。只有在处理程序调用真实外部 API 时，工具延迟 P90 和工具错误率等指标才有意义。如果 Agent 当前使用的是桩，请注明这一点，并将这些指标推迟到接入真实处理程序后再创建。针对桩创建这些指标比不创建更糟：它们会产生错误的信心（延迟始终极佳，错误率始终为零），从而掩盖真实的生产行为。 请勿根据源自产物的标记跨度创建延迟自定义轨迹指标。对于由 Vapi 托管的 Agent，带有 trace.timing=metadata_marker 的 stt/llm/tts 跨度并不代表测得的供应商延迟。应改用真实的工具/工作流指标和感知轨迹的评估指标。

自动配对规则。 在 optimize-trace-observability 期间添加的每个新数值属性，都应在同一轮中至少配对一个建议指标，而不是留到下一轮。遍历一次新增属性集：

• 任意供应商跨度上的 metrics.ttfb → P90 延迟指标
• *.latency_ms / *.duration_s → P90 延迟指标
• *.count / *_count / *.bytes → 每次调用平均值指标
• *.total / *.amount / *.value（业务数值）→ 业务平均值指标（例如，cart.total/平均值/评分）
• 数值型 0/1 标记（*.error、*.fallback_used、*.completed、*.dependency_unavailable）→ 平均值/比率指标
• wait.* / *_to_first_* → P90 耗时指标

如果自动配对会创建一个无法回答客户问题的指标，请明确舍弃该指标并说明原因。没有提出相应的配套指标，就不要交付轨迹增强轮次——不应让客户不得不两次追问“这些就是全部指标吗？”。 第一轮基准：如果真实跨度包含所需属性，至少创建或暂存一个垂直领域专属指标，以及工作流完成率、工作流阻塞／依赖阻塞率、工具延迟 P90、工具失败率和回退使用率。如果跟踪数据已包含客户运营信号，只创建通用验证指标的配置并不完整。

阶段 2：验证配置结构

Coval 自定义跟踪指标字段：

• metric_type：METRIC_CUSTOM_TRACE
• span_name：完全匹配的已发出跨度名称
• metric_attribute：数值聚合必需
• aggregation_method：以下之一：average、median、p90、p95、p99、max、min、sum、count、error_rate、success_rate
• unit：可选显示单位，例如 s、ms、count、percent、tokens、ratio 或 score

目标环境的公共 API／OpenAPI 是可接受聚合方式的事实来源。某些已部署的 API 版本通过 POST /v1/metrics 仅接受 average、median、p90、max 和 min。当 API 拒绝 count、error_rate、success_rate、p95、p99 或 sum 时，应针对真实数值属性创建生产安全指标，例如 average 或 p90，然后将不受支持的目标指标记录为公共 API／文档偏差项。 某些已部署的 API 版本还要求 METRIC_CUSTOM_TRACE 必须提供 metric_attribute，即便基于时长或跨度状态的指标更合适。在这种情况下，应在埋点时将有用的时长／状态作为显式数值属性发出，并针对该属性创建指标。例如，将测得的 insurance.workflow.dispatch_roadside 跨度时长复制到 conversation.roadside.dispatch.latency_ms 或 roadside.dispatch.latency_ms，然后针对该属性创建 P90 指标。

生产安全的比率模式：当不接受跨度级比率聚合时，发出数值 0／1 属性，并使用 average 聚合。示例：

• llm_tool_call / tool.error / average / ratio
• llm_tool_call / tool.dependency_unavailable / average / ratio
• conversation / workflow.dependency_blocked / average / ratio
• conversation / workflow.completed / average / ratio

对于 count、error_rate 和 success_rate，如果目标 API 允许省略 metric_attribute，则应将其省略。如果已部署的 API 仍要求提供属性，仅当已知存在的跨度属性能够保留指标含义时才使用；否则，不要通过 API 自动化创建该指标。

API 请求体示例：

{
  "metric_name": "P95 LLM TTFB",
  "description": "95th percentile time to first token from llm spans.",
  "metric_type": "METRIC_CUSTOM_TRACE",
  "span_name": "llm",
  "metric_attribute": "metrics.ttfb",
  "aggregation_method": "p95",
  "unit": "s"
}

支持跟踪数据的 LLM 评估指标字段：

• metric_type：METRIC_LLM_BINARY、METRIC_CATEGORICAL 或 METRIC_NUMERICAL_LLM_JUDGE
• prompt：明确告知评估器同时使用对话记录和 OTel 跟踪上下文
• include_traces：true

仅当当前 Metrics OpenAPI 确认所选 LLM 评估类型支持 include_traces 时，才创建这些指标。优质提示词会引用具体的跟踪证据，例如 llm_tool_call、function.name、function.arguments、tool.error、error.type 和工作流根属性。

支持跟踪数据的评估器请求体示例：

{
  "metric_name": "Trace-Aware Tool Output Grounding",
  "description": "Uses transcript plus OTel tool-call traces to verify agent claims are grounded in successful tool outputs.",
  "metric_type": "METRIC_LLM_BINARY",
  "prompt": "Use BOTH the transcript and OTel trace context. Score YES only if the agent's customer-facing claims are supported by successful llm_tool_call outputs. Score NO if the agent asserts outcomes not supported by successful tool outputs, or if it ignores a tool.error or error.type result and presents the workflow as completed.",
  "include_traces": true
}

仅在确认真实跟踪中存在该跨度／属性后再创建。如果初始验证仍在运行，请在准备指标请求体的同时，继续通过 Coval CLI/API 轮询，然后在 Trace Search 或运行跟踪输出确认数据后立即创建指标。

阶段 3：关联并验证

创建指标后：

1. 使用与当前 OpenAPI 相匹配的 CLI/API 路径，将指标关联到目标 Agent、运行模板或运行配置。如果 Agent 没有默认指标，但客户使用运行模板，请修改运行模板，而不要假设会使用 Agent 默认值。
2. 通过 Coval CLI/API 启动或重新运行一次小规模评估，除非正在进行的验证运行已包含新关联的指标。
3. 通过 CLI/API 轮询运行，直到运行结束。等待期间，检查轨迹质量或准备交接材料，不要一直等待。
4. 确认每个新关联的轨迹指标在验证模拟中都达到终态（COMPLETED 或 FAILED）。如果输出仍处于 IN QUEUE 或 IN PROGRESS，请勿停止。
5. 确认指标能够计算，且不会报错，错误信息如 "No spans named..." 或 "metric_attribute is required"。
6. 对于感知轨迹的 LLM 评审器，导出轨迹后启动包含这些指标的验证运行，以确认其能够使用轨迹上下文运行。
7. 确认计算出的值能够解读，并能回答客户的问题。如果指标虽能计算，但只能证明追踪功能正常，请将其标记为诊断指标，并在交接前替换为信号更强的指标。
8. 如果指标因数据缺失而报错，请修复埋点，而不是更改指标以衡量价值较低的信号。
9. 如果先前的运行显示指标失败，请以指标/埋点更新后启动的首次运行为准进行验证，然后再判定指标是否损坏。
10. 如果创建 API 拒绝了代码中有效的聚合方式，请保留简洁明确且已验证的备用指标，并在验证备注中附上被拒绝的响应。

阶段 4：交接

报告：

• 已创建指标的 ID 和名称
• 每个指标对应的 span/属性/聚合方式/单位
• 对于感知轨迹的评审器指标，说明 LLM 评审器类型和 include_traces 状态
• 每个指标对应的客户问题和业务解读
• 创建前已存在每个 span/属性的证据
• 用于验证计算的运行或对话
• 运行列表、运行详情、运行结果和轨迹查看器的 Coval 直达 URL
• 有意未创建或已替换的纯证明用途指标
• 建议后续补充的埋点