setup-tracing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Setup Coval Tracing

配置Coval追踪

Set up tracing in the customer's agent with the smallest additive change that produces a real Coval trace, then verify that trace against the agent's actual Coval connection path.

Operate from the customer's agent side. Do not assume access to Coval internal backend, frontend, docs, wizard, research, or example source repositories, and do not ask the customer for them. Use only the customer's repo, public Coval docs, public SDK examples, the Coval CLI/API, and fetched public OpenAPI specs. Code edits belong in the customer's agent/service repo. Coval-side changes must be limited to documented configuration through the Coval CLI, public API, or dashboard, and should be explained before mutation.

以最小的增量修改在客户的Agent中配置追踪，生成真实的Coval追踪数据，随后根据Agent实际的Coval连接路径验证该追踪数据。

操作需从客户的Agent端出发。请勿假设可访问Coval内部的后端、前端、文档、向导、研究或示例源码仓库，也不要向客户索要这些资源。仅可使用客户的仓库、公开的Coval文档、公开的SDK示例、Coval CLI/API，以及获取的公开OpenAPI规范。代码修改需在客户的Agent/服务仓库中进行。Coval端的变更必须限制为通过Coval CLI、公开API或控制台进行的已文档化配置，且在修改前需进行说明。

Preflight

预检查

Confirm the agent repo or service scope. In a monorepo, do not instrument every service unless the user explicitly asks.
Check Coval authentication without reading secret files:
bash
```
coval whoami
coval agents list --format json
```
If the CLI is unavailable, use
```
COVAL_API_KEY
```
from the user's shell environment and direct API calls. Never print or store the raw key. When listing agents through the API, redact
```
metadata
```
before showing output because some provider integrations store model API keys there.
Fetch current API shape before writing API integrations:
bash
```
curl -fsS https://api.coval.dev/v1/openapi
```
For broader docs discovery, fetch
```
https://docs.coval.dev/llms.txt
```
and then the specific public docs page needed for the task.
Stay inside the customer-owned code surface. Do not reference or require
```
coval-ai/backend
```
,
```
coval-ai/frontend
```
,
```
coval-ai/docs
```
,
```
coval-ai/wizard
```
, internal engineering docs, or private Coval repos as local source code. Public docs, public SDK examples, and installed skill reference files are the support material available to the customer-side agent.

Read the shared references before editing:

../references/coval-tracing-reference.md

```
../references/agent-type-routing.md
```
```
../references/span-schema.md
```

确认Agent仓库或服务范围。如果是单体仓库，除非用户明确要求，否则不要对所有服务进行埋点。
在不读取密钥文件的情况下检查Coval身份验证：
bash
```
coval whoami
coval agents list --format json
```
如果无法使用CLI，可从用户的Shell环境中获取
```
COVAL_API_KEY
```
并直接调用API。切勿打印或存储原始密钥。通过API列出Agent时，在显示输出前需编辑
```
metadata
```
内容，因为部分提供商集成会在此处存储模型API密钥。
在编写API集成前获取当前API结构：
bash
```
curl -fsS https://api.coval.dev/v1/openapi
```
如需更全面的文档发现，可先获取
```
https://docs.coval.dev/llms.txt
```
，再获取完成任务所需的特定公开文档页面。
仅在客户拥有的代码范围内操作。请勿引用或依赖
```
coval-ai/backend
```
、
```
coval-ai/frontend
```
、
```
coval-ai/docs
```
、
```
coval-ai/wizard
```
、内部工程文档或Coval私有仓库作为本地源码。公开文档、公开SDK示例和已安装的skill参考文件是客户端Agent可使用的支持材料。

在编辑前阅读共享参考文件：

../references/coval-tracing-reference.md

```
../references/agent-type-routing.md
```
```
../references/span-schema.md
```

Phase 1: Read-Only Analysis

第一阶段：只读分析

Do not edit files until this phase is complete.

Identify:

language and package manager
app start command and one representative local invocation
agent framework or provider stack: Pipecat, LiveKit, Vapi, Twilio, WebSocket, direct OpenAI/Anthropic, custom loop, etc.
Coval agent type and connection path: SIP inbound, PSTN inbound, outbound voice, WebSocket voice/chat, or conversation monitoring
where a per-call Coval ID can enter the agent process
existing telemetry owner: OpenTelemetry, Sentry, Datadog, Honeycomb, Langfuse, Arize, LangSmith, Traceloop, or custom OTLP exporter
short-lived process behavior and shutdown/flush path
customer-owned files that need edits, and any Coval configuration changes that must be done through CLI/API/dashboard rather than code changes

Return a concise analysis summary. If the target service or repo scope is ambiguous, ask before editing. Do not ask the customer to choose a correlation route from a menu. Customers usually cannot know whether SIP headers, pre-call webhooks, or trigger payloads are supported from the outside; infer the best route from the discovered agent configuration and the decision rules below.

完成此阶段前请勿编辑文件。

需识别：

编程语言和包管理器
应用启动命令及一个代表性的本地调用示例
Agent框架或提供商栈：Pipecat、LiveKit、Vapi、Twilio、WebSocket、直接对接OpenAI/Anthropic、自定义循环等
Coval Agent类型和连接路径：SIP呼入、PSTN呼入、语音呼出、WebSocket语音/聊天或对话监控
每通呼叫的Coval ID可进入Agent进程的位置
现有遥测工具所有者：OpenTelemetry、Sentry、Datadog、Honeycomb、Langfuse、Arize、LangSmith、Traceloop或自定义OTLP导出器
短生命周期进程的行为及关闭/刷新路径
需要编辑的客户自有文件，以及必须通过CLI/API/控制台而非代码变更完成的Coval配置变更

返回简洁的分析总结。如果目标服务或仓库范围不明确，需先询问再进行编辑。请勿让客户从菜单中选择关联路径。客户通常无法知晓外部是否支持SIP头、呼叫前Webhook或触发负载；需根据发现的Agent配置及以下决策规则推断最佳路径。

Phase 2: Pick The Correlation Path

第二阶段：选择关联路径

Use exactly one target header per export:

simulations:
```
X-Simulation-Id
```
with the simulation output ID

conversation monitoring:

X-Conversation-Id

with the

conversation_id

returned by

POST /v1/conversations:submit

Pick the route yourself when the repo and Coval agent configuration make one route clearly safer. Do not present an open-ended "which route should I use?" question. Use this decision order:

If the current connection path already delivers a Coval ID into the process, use that path. Examples: SIP participant attributes, outbound trigger payload, WebSocket initialization payload, or a monitoring
```
conversation_id
```
.
If the current Coval agent record or fetched OpenAPI confirms an existing pre-call/registration webhook field and the service already exposes a suitable endpoint, configure or reuse that webhook.
For inbound PSTN phone agents with no verified SIP headers and no confirmed Coval pre-call webhook wiring, default to a self-contained registration endpoint plus a smoke launcher that registers
```
simulation_output_id
```
right before the call. This is the safest first validation because it does not guess at Coval agent metadata shape or mutate customer agent config. After it works, state the production upgrade: wire the same endpoint into the verified Coval pre-call webhook field when available, or provision SIP if the customer needs Coval-managed per-call injection.
Ask a customer question only when every viable route requires a policy or deployment decision you cannot infer, such as whether you may expose a new public webhook, update the Coval agent configuration, or provision a SIP route. In that case, give one recommendation first, explain why, and ask for the smallest approval needed.

Coval-side config changes that are purely additive to a documented field that is currently empty (e.g., setting

initialization_json

from

"{}"

to the documented

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

placeholder, or filling an empty

pre_call_webhook_url

) do not need a consent prompt — the customer's "get traces working" intent implies it, and the change is trivially reversible via the same PATCH. Show the before/after value in the handoff but proceed without asking. Always ask before changes that delete config, downgrade auth, overwrite a non-empty field, or modify shared resources like phone numbers, SIP routes, test sets, or webhook secrets.

Choose the route from

../references/agent-type-routing.md

SIP inbound voice: extract
```
X-Coval-Simulation-Id
```
from SIP headers or framework participant attributes.
PSTN inbound phone: do not expect SIP headers. Add or configure
```
pre_call_webhook_url
```
/ registration-webhook correlation, or guide the customer to provision a SIP address.
Outbound voice: carry
```
simulation_output_id
```
in the trigger payload and read it in the trigger handler.
WebSocket voice/chat: carry the simulation output ID in the initial setup payload or initialization JSON.
Conversation monitoring: buffer spans during the call, submit the conversation at call end, then export buffered spans with
```
X-Conversation-Id
```
.

For direct WebSocket agents, prefer configuring Coval metadata with an explicit initialization payload such as:

json

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

Then treat the first non-audio frame as setup metadata, extract

simulation_id

simulation_output_id

, and only export with

X-Simulation-Id

after that ID is present. Current production examples use

{{simulation_id}}

; if docs mention

{{simulation_output_id}}

, verify current agent metadata behavior before hardcoding either name.

每个导出仅使用一个目标头：

模拟场景：使用
```
X-Simulation-Id
```
，值为模拟输出ID

对话监控场景：使用

X-Conversation-Id

，值为

POST /v1/conversations:submit

接口返回的

conversation_id

当仓库和Coval Agent配置明确显示某一路径更安全时，自行选择该路径。请勿提出开放式问题“我应该使用哪条路径？”。请按照以下决策顺序选择：

如果当前连接路径已将Coval ID传入进程，则使用该路径。示例：SIP参与者属性、呼出触发负载、WebSocket初始化负载或监控用的
```
conversation_id
```
。
如果当前Coval Agent记录或获取的OpenAPI确认存在呼叫前/注册Webhook字段，且服务已暴露合适的端点，则配置或复用该Webhook。
对于无已验证SIP头且无已确认Coval呼叫前Webhook连接的呼入PSTN电话Agent，默认使用独立注册端点加上在呼叫前注册
```
simulation_output_id
```
的快速验证启动器。这是最安全的首次验证方案，因为它无需猜测Coval Agent元数据结构或修改客户Agent配置。验证通过后，说明生产环境升级方案：当可用时将同一端点接入已验证的Coval呼叫前Webhook字段，或如果客户需要Coval管理的每通呼叫注入，则配置SIP。
仅当所有可行路径都需要你无法推断的策略或部署决策时，才向客户提问，例如是否可以暴露新的公开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。
对话监控：在呼叫期间缓存span，呼叫结束时提交对话，然后使用
```
X-Conversation-Id
```
导出缓存的span。

对于直接对接的WebSocket Agent，优先使用明确的初始化配置Coval元数据，例如：

json

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

随后将第一个非音频帧视为设置元数据，提取

simulation_id

或

simulation_output_id

，仅在该ID存在后才使用

X-Simulation-Id

进行导出。当前生产示例使用

{{simulation_id}}

；如果文档提到

{{simulation_output_id}}

，在硬编码任一名称前需验证当前Agent元数据的行为。

Phase 3: Implement Additive Instrumentation

第三阶段：实现增量埋点

Prefer an existing telemetry owner. If the app already has a

TracerProvider

, add a Coval exporter/processor to it instead of replacing the provider. If there is no telemetry setup, create one central module such as

coval_tracing.py

covalTracing.ts

, or

coval_tracing.go

Implementation requirements:

Endpoint:
```
https://api.coval.dev/v1/traces
```
Auth header:
```
x-api-key
```
or
```
X-API-Key
```
from an environment variable, never a literal secret
Timeout: 30 seconds
Resource: set
```
service.name
```
to the agent or service name
Export one target header only:
```
X-Simulation-Id
```
or
```
X-Conversation-Id
```
Buffer spans only when the Coval ID is not yet available; bound the buffer
Use
```
BatchSpanProcessor
```
or equivalent for high-volume agents and keep batches comfortably below 3-4 MB
Flush/shutdown tracing before short-lived processes exit
Retry only failed batches; Coval stores spans append-only and does not deduplicate successful retries
Update deployment packaging. Dockerfiles, serverless bundles, Pipecat Cloud packages, and Fly/Render/Heroku deploys must include any new tracing helper module and dependency files.
Emit the canonical span names from
```
../references/span-schema.md
```
first:
```
llm
```
,
```
tts
```
,
```
stt
```
,
```
stt.provider.<name>
```
,
```
vad
```
,
```
llm_tool_call
```
,
```
turn
```
,
```
conversation
```
,
```
pipeline
```
, and
```
transport
```
. These names drive semantic UI labels, colors, and built-in trace metrics.
When adding tool or workflow spans, include metric-ready numeric attributes from the first implementation:
```
tool.latency_ms
```
, numeric
```
tool.error
```
, numeric
```
tool.dependency_unavailable
```
,
```
tool.call.count
```
,
```
tool.failure.count
```
, numeric
```
workflow.completed
```
, numeric
```
workflow.dependency_blocked
```
, and numeric
```
workflow.fallback_used
```
when available. These keep
```
configure-trace-metrics
```
from having to settle for proof-only metrics.
For webhook-style voice agents, do not rely only on a final end-of-call event if tool-call or turn webhooks already have the Coval target ID. Export the per-event spans when the target ID is known, or buffer them until it is known, then flush once. Avoid replaying spans after a successful export because Coval trace ingest is append-only.

For Python voice agents, an existing generated

coval_tracing.py

helper in the customer repo is an acceptable baseline, but improve it for the discovered connection path and existing telemetry.

优先使用现有遥测工具。如果应用已有

TracerProvider

，则向其添加Coval导出器/处理器，而非替换该Provider。如果尚未设置遥测，则创建一个中央模块，例如

coval_tracing.py

、

covalTracing.ts

或

coval_tracing.go

。

实现要求：

端点：
```
https://api.coval.dev/v1/traces
```
认证头：
```
x-api-key
```
或
```
X-API-Key
```
，值来自环境变量，切勿使用明文密钥
超时时间：30秒
资源：将
```
service.name
```
设置为Agent或服务名称
仅导出一个目标头：
```
X-Simulation-Id
```
或
```
X-Conversation-Id
```
仅在Coval ID不可用时缓存span；需限制缓存大小
对于高并发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
```
只能使用仅作验证用的指标。
对于Webhook风格的语音Agent，如果工具调用或轮次Webhook已包含Coval目标ID，则不要仅依赖最终的呼叫结束事件。在目标ID已知时导出每个事件的span，或缓存span直到目标ID已知后一次性刷新。避免在成功导出后重放span，因为Coval追踪数据的摄入是追加式的。

对于Python语音Agent，客户仓库中已有的生成版

coval_tracing.py

辅助文件可作为基线，但需根据发现的连接路径和现有遥测进行优化。

Phase 4: Minimum Span Coverage

第四阶段：最小Span覆盖范围

The first working trace should contain:

a root
```
conversation
```
or equivalent session span when the framework gives a call boundary
at least one
```
stt
```
,
```
llm
```
,
```
tts
```
, or
```
llm_tool_call
```
span that matches the actual agent path
correct parent/child relationships where the framework exposes them
```
service.name
```
resource metadata
Coval-compatible target ID routing

If the app cannot expose STT/TTS/LLM internals yet, ship the minimum useful trace first, then use

optimize-trace-observability

for enrichment.

Anti-pattern: per-chunk or per-frame transport spans. Voice/realtime agents stream audio in many small chunks (often 20-100 ms). Emitting one OTel span per chunk produces hundreds of micro-spans that visually drown the trace viewer and collapse the real

turn

tts

llm

spans into invisible slivers — the trace will look empty even when it is not. Aggregate per-chunk activity into counter attributes on the parent stream span instead:

```
audio.chunks_sent
```
(count) and
```
audio.chunk_target_ms
```
(configured cadence) on the
```
tts
```
span
```
audio.chunks_received
```
on the
```
turn
```
or
```
stt
```
span
```
audio.payload_bytes
```
,
```
audio.duration_s
```
already capture the totals

The same rule applies to per-frame

transport.recv_audio

, per-event WebSocket pings, and per-token streaming spans. One span per high-level operation; per- chunk detail goes into numeric attributes.

首个可用的追踪应包含：

当框架提供呼叫边界时，一个根级
```
conversation
```
或等效的会话span
至少一个与Agent实际路径匹配的
```
stt
```
、
```
llm
```
、
```
tts
```
或
```
llm_tool_call
```
span
框架暴露的正确父子关系
```
service.name
```
资源元数据
兼容Coval的目标ID路由

如果应用暂时无法暴露STT/TTS/LLM内部细节，先交付最有用的最小化追踪，再使用

optimize-trace-observability

进行增强。

反模式：按块或按帧生成transport span。 语音/实时Agent会将音频拆分为许多小块（通常为20-100毫秒）。为每个块生成一个OTel span会产生数百个微span，在追踪查看器中造成视觉干扰，并将真正的

turn

tts

llm

span压缩成不可见的细条——即使追踪数据存在，看起来也像是空的。应将按块的活动聚合到父流span的计数器属性中：

在
```
tts
```
span上添加
```
audio.chunks_sent
```
（计数）和
```
audio.chunk_target_ms
```
（配置的节奏）
在
```
turn
```
或
```
stt
```
span上添加
```
audio.chunks_received
```
```
audio.payload_bytes
```
、
```
audio.duration_s
```
已捕获总计数据

同一规则适用于按帧的

transport.recv_audio

、按事件的WebSocket ping以及按token的流式span。每个高级操作对应一个span；按块的细节放入数值属性中。

Phase 5: Verification

第五阶段：验证

Run local checks first:

bash

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

Use the checks that match the repo; do not invent package-manager commands.

Then start the Coval validation through CLI/API and do useful work while it runs. Coval simulations and monitoring conversations are asynchronous; do not sit idle after launching one.

Use the discovered Coval CLI/API path to launch one real test through the same Coval agent type the customer uses. Prefer CLI commands when available; otherwise use the public API after fetching OpenAPI. Capture the run ID, simulation output ID, conversation ID, dashboard URL, or polling endpoint returned by the launch.
Start a bounded poll loop through the CLI/API. Record the command or endpoint used, poll interval, and timeout. Do not print API keys or raw provider metadata from Coval agent responses.
While the run is pending, continue with non-blocking trace improvement:
- add safe span enrichment visible from the code path, such as stable
```
conversation
```
  ,
```
turn
```
  ,
```
stt
```
  ,
```
llm
```
  ,
```
tts
```
  ,
```
llm_tool_call
```
  ,
```
transport
```
  , or provider spans
- add bounded high-value attributes such as
```
metrics.ttfb
```
  , token counts, finish reasons, tool names, safe tool argument summaries, status, and errors
- add customer-signal numeric attributes that can become metrics, such as
```
tool.error
```
  ,
```
tool.latency_ms
```
  ,
```
tool.call.count
```
  ,
```
workflow.dependency_blocked
```
  ,
```
workflow.completed
```
  , and
```
workflow.fallback_used
```
- improve flush/shutdown, buffering, batch size, retry, or deployment packaging issues found during implementation
- prepare custom trace metric candidates from expected spans and any historical Coval traces already available; treat generic duration or span-count metrics as diagnostic proof unless they answer a customer operating question
Create custom trace metrics during the wait only when real trace data already proves the span name and metric attribute exist, either from historical traced runs or from the in-flight validation once spans appear in Trace Search. If this validation is the first trace for the agent, stage the metric definitions while waiting and create them immediately after the run produces confirmed spans.
When the run finishes, confirm the agent export returned 200 or that the exporter logged a successful accepted batch. A 404 from the standalone test script only proves auth/connectivity, not lifecycle wiring.
Open the Coval run or conversation result and verify the OTel Traces card or Trace Search result appears.
Inspect the trace for expected spans and attributes. If it is missing, sparse, duplicated, or attached to the wrong result, stop further metric creation and apply
```
debug-traces
```
before continuing.
Trace density self-check. Before declaring success, count spans by name. If a single span name is more than ~70% of total spans and those spans are each shorter than ~50 ms, that name is almost certainly per-chunk/per-frame noise. Collapse it into a counter attribute on the parent span and redeploy before opening the result for the customer — the trace viewer will look empty otherwise. Do not rely on the customer to flag visual noise.
Verify correlation activation from the exporter, not from pre-existing agent counters. Pre-existing counters like a
```
non_audio_messages
```
or
```
non_setup_frames
```
tally on the agent often increment after the setup/init branch returns, so they read
```
0
```
even when correlation worked. The authoritative signal that the simulation ID reached the exporter is the OTel logger line (
```
activated OTLP export simulation_id=<id>
```
) or the batch processor's accepted-batch log. Check those first; only chase counters if the exporter never activated.
After the initial trace is confirmed, finish any prepared metric creation and run one follow-up calculation/preview/attached-run check through the CLI/API when the public API supports it.

For WebSocket agents, make the smoke interaction long enough to trigger the agent's response threshold. A client that sends too little audio, or an agent that waits for more silence/audio than Coval sends, can make tracing look broken even when the exporter is wired correctly. If a

tts

span is marked

ERROR

with a WebSocket disconnect after partial audio, shorten the canned response or stop streaming when the client closes.

Optional connectivity-only check:

bash

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

A 404 with

Simulation output not found

means the key reached Coval and auth worked, but it is not proof that the agent call lifecycle is wired.

先运行本地检查：

bash

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

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

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

使用发现的Coval CLI/API路径，通过客户使用的同一Coval Agent类型启动一次真实测试。优先使用CLI命令；否则在获取OpenAPI后使用公开API。记录返回的运行ID、模拟输出ID、对话ID、控制台URL或轮询端点。
通过CLI/API启动一个有限制的轮询循环。记录使用的命令或端点、轮询间隔和超时时间。请勿打印API密钥或Coval Agent响应中的原始提供商元数据。
在运行等待期间，继续进行非阻塞的追踪优化：
- 添加从代码路径可见的安全span增强，例如稳定的
```
conversation
```
  、
```
turn
```
  、
```
stt
```
  、
```
llm
```
  、
```
tts
```
  、
```
llm_tool_call
```
  、
```
transport
```
  或提供商span
- 添加有价值的有限属性，如
```
metrics.ttfb
```
  、token计数、结束原因、工具名称、安全的工具参数摘要、状态和错误
- 添加可转化为指标的客户信号数值属性，如
```
tool.error
```
  、
```
tool.latency_ms
```
  、
```
tool.call.count
```
  、
```
workflow.dependency_blocked
```
  、
```
workflow.completed
```
  和
```
workflow.fallback_used
```
- 修复实现过程中发现的刷新/关闭、缓存、批量大小、重试或部署打包问题
- 从预期的span和已有的历史Coval追踪数据中准备自定义追踪指标候选；除非这些指标能解答客户的运营问题，否则将通用时长或span计数指标视为诊断验证数据
仅当真实追踪数据已证明span名称和指标属性存在时，才在等待期间创建自定义追踪指标，无论是来自历史追踪运行还是在追踪搜索中出现span后的在途验证。如果此次验证是Agent的首次追踪，则在等待期间暂存指标定义，并在运行生成确认的span后立即创建。
运行完成后，确认Agent导出返回200状态码，或导出器记录了成功接收的批量。独立测试脚本返回404仅证明认证/连接正常，而非生命周期连接正常。
打开Coval运行或对话结果，验证OTel追踪卡片或追踪搜索结果是否出现。
检查追踪中是否存在预期的span和属性。如果缺失、稀疏、重复或关联到错误结果，停止进一步的指标创建，先使用
```
debug-traces
```
进行调试，然后再继续。
追踪密度自查。 在宣布成功前，按名称统计span数量。如果单个span名称占总span数的70%以上，且每个span的时长都短于约50毫秒，那么该名称几乎可以肯定是按块/按帧产生的噪音。将其合并到父span的计数器属性中，并在向客户展示结果前重新部署——否则追踪查看器看起来会是空的。不要依赖客户来指出视觉噪音。
从导出器验证关联激活，而非依赖Agent的预定义计数器。 Agent上的预定义计数器（如
```
non_audio_messages
```
或
```
non_setup_frames
```
计数）通常在设置/初始化分支返回后才会递增，因此即使关联成功，它们的值也可能为0。模拟ID到达导出器的权威信号是OTel日志行（
```
activated OTLP export simulation_id=<id>
```
）或批量处理器的已接收批量日志。先检查这些日志；仅当导出器从未激活时再排查计数器。
确认初始追踪正常后，完成所有已准备的指标创建，并在公开API支持时通过CLI/API运行一次后续计算/预览/附加运行检查。

对于WebSocket Agent，确保快速测试交互时长足够触发Agent的响应阈值。如果客户端发送的音频过少，或Agent等待的静音/音频时长超过Coval发送的时长，即使导出器连接正确，追踪也可能看起来异常。如果

tts

span被标记为

ERROR

且WebSocket在部分音频发送后断开，可缩短预设响应内容，或在客户端关闭时停止流式传输。

可选的仅连接性检查：

bash

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呼叫生命周期已正确连接。

Handoff

交接

End with:

files changed and why
exact correlation path used
how the customer sets required env vars
commands run, including the Coval launch and polling commands/API endpoints
Coval trace URL or simulation/conversation ID used for proof
custom trace metrics created, staged, or deferred and why

any remaining gaps to handle with

optimize-trace-observability

configure-trace-metrics

, or

debug-traces

结束时需提供：

修改的文件及原因
使用的具体关联路径
客户设置所需环境变量的方法
运行的命令，包括Coval启动和轮询命令/API端点
用于验证的Coval追踪URL或模拟/对话ID
创建、暂存或延迟创建的自定义追踪指标及原因

需通过

optimize-trace-observability

、

configure-trace-metrics

或

debug-traces

处理的剩余差距