入站与出站 Trace 关联

区分自己的 OTLP 数据、提供商请求 header 和 daemon 访问日志中的 traceId。

This page has not been translated into English yet. The original Chinese version is shown below.

客户端 HTTP span、出站 traceparent 和 daemon 入站关联是三件独立的事。先确认数据接收者，再决定是否把本地 trace 身份传到第三方端点。

启用 telemetry 后，进程内 outbound fetch instrumentation 可记录 HTTP 延迟，帮助区分网络与模型处理耗时。这些 span 发往自己的 collector 或 outfile，不自动意味着请求带 traceparent。

outboundCorrelation.propagateTraceContext 默认 false，位于 telemetry 之外的顶层配置。关闭时使用不注入的 propagator，HTTP span 仍可存在；开启后使用 W3C tracecontext/baggage 传播，并为 Shell、Hooks、Monitor 等子进程设置 TRACEPARENT、TRACESTATE。

该开关还依赖 telemetry.enabled=true。仅开启传播而不初始化遥测不会生效。

{
  "telemetry": {
    "enabled": true,
    "otlpProtocol": "http",
    "otlpEndpoint": "http://localhost:4318"
  },
  "outboundCorrelation": {
    "propagateTraceContext": true
  }
}

这适用于确实需要与对应上游拼接 trace 的环境。配置的 collector 与提供商请求接收方不同，不能因启用了内部监控就默认同意向任意提供商传播关联标识。

避免遥测递归记录自身

OTLP exporter 也可能使用 fetch。instrumentation 会跳过配置的基础和按信号 OTLP endpoint 前缀，避免上传遥测产生新的遥测请求形成循环。outfile 模式没有这类 HTTP 上传。

Routify 会话亲和例外

HTTPS 直接请求 routify.alibaba-inc.com、routify-online.alibaba-inc.com 或 routify-pub.alibaba-inc.com 时，支持的 provider 路径会添加 session_id header，用于该服务的会话亲和。这不受 telemetry.enabled 或 outboundCorrelation 控制。

初始目标匹配不覆盖子域、其他 alibaba-inc.com 主机或其他提供商端点；但标准 fetch 重定向行为仍可能继续转发该 header。每次请求读取当前会话 ID，/clear 后更新；Gemini 需显式 Routify baseUrl 才能验证目的地。

当前未实现 X-Qwen-Code-Request-Id，不能把该 header 作为现成关联入口。

daemon 入站 traceparent

有效入站 traceparent 在遥测开启时成为请求 span 的远端 parent，相关子进程转发上下文也沿用该 parent。

独立的 pre-auth 捕获逻辑还把 traceId 写入访问日志，即使 telemetry 关闭也有效；涵盖认证提前返回的 401、限流 429、JSON 解析 400 和未匹配路由 404。

无效但存在的 header 不会成为 span parent，并留下限流后的 qwen-code.daemon.traceparent.invalid DEBUG 诊断。header 不是认证凭据，不能据此决定请求权限。

采样与请求身份

默认 parentbased_always_on 及相关 parentbased 默认配置会强制入站 parent 的 SAMPLED 位，不把调用者 sampled=0 当成必须丢弃 daemon telemetry 的要求。

OTEL_TRACES_SAMPLER=parentbased_always_off 是文档给出的保留调用方采样决定的例外，但它也关闭整个 daemon 的 root span 采样。不要只为一条入站请求修改后忽略全局影响。

压测或自定义客户端不要把一个固定 traceparent 用于所有独立请求，否则它们会挂进同一 trace。应按实际请求链生成与传播上下文。