Qwen Code 可观测性完全指南:基于 OpenTelemetry 的遥测配置、日志、指标与分布式追踪实战

原创2026-09-14 15:43:382,283 阅读
文章标签:人工智能AI Agent代码智能体AI 应用CLIQwen开发工具MCP Clients工具调用多智能体大模型浏览器控制

Qwen Code 可观测性完全指南:基于 OpenTelemetry 的遥测配置、日志、指标与分布式追踪实战

Qwen Code 是一款运行在终端中的开源 AI 编程 Agent,其内置的遥测系统基于 OpenTelemetry 构建,覆盖日志(Logs)、指标(Metrics)、分布式追踪(Spans/Traces)三大信号,支持导出到阿里云 ARMS、Jaeger、Prometheus 等任意 OTLP 后端。本文以仓库官方文档 docs/developers/development/telemetry.md 为骨架,结合 packages/core/src/telemetry 的源码实现,系统讲解如何开启与配置遥测、理解每一个配置项的底层语义、梳理全部日志事件/指标/Span 的数据契约,并给出本地调试与阿里云接入的完整操作步骤——读完即可在生产环境落地一套可检索、可引用、可监控的 Agent 观测体系。

迁移注意事项:先看这里,避免下游查询失效

升级遥测版本前,请确认以下三项契约变更,它们会影响依赖旧字段名的下游消费者:

  • tool_output_truncated 已重命名为 qwen-code.tool_output_truncated,以保持命名空间一致性——仍按旧名称过滤的查询需要更新。
  • tool.call.latency 直方图的文档此前列出过 decision 属性,但该属性从未被写入此直方图(实际只记录 function_name);tool.call.count 计数器则一直包含 decision 属性。
  • qwen-code.file_operation 日志事件与 file.operation.count 指标文档中列出的 diff-stat 属性(model_added_lines、model_removed_lines、user_added_lines、user_removed_lines)从未被写入。diff-stat 数据可通过 tool_call 日志事件的 metadata 属性获取。

遥测能带来什么:五大收益

官方文档明确列出的收益如下:

  • 使用分析:理解团队内的交互模式与功能采纳情况;
  • 性能监控:追踪响应时间、Token 消耗与资源利用率;
  • 实时调试:在问题发生时定位瓶颈、失败与错误模式;
  • 工作流优化:基于数据改进配置与流程;
  • 企业治理:跨团队监控用量、追踪成本、保障合规,并接入既有监控基础设施。

为什么基于 OpenTelemetry:设计理念

Qwen Code 的遥测系统构建在 OpenTelemetry(厂商中立、行业标准的可观测性框架)之上,因此天然具备:

  • 通用兼容性:可导出到任意 OpenTelemetry 后端(阿里云、Jaeger、Prometheus、Datadog 等);
  • 标准化数据:整个工具链使用一致的格式与采集方法;
  • 面向未来:可平滑接入现有与未来的可观测性基础设施;
  • 无厂商锁定:切换后端无需改动任何埋点代码。

从源码看,Qwen Code 在 packages/core/src/telemetry/sdk.ts 中通过 initializeTelemetry 统一初始化 SDK,并且采用懒加载策略:@opentelemetry/sdk-node 及 OTLP 导出器链通过动态 import('./sdk-impl.js') 按需加载,遥测未启用时进程完全不承担这些模块的加载成本。这保证了默认 enabled: false 状态下对启动性能的零影响。

配置指南:settings.json、环境变量与 CLI 标志

所有遥测行为都通过 .qwen/settings.json 控制,且可被环境变量或 CLI 标志覆盖。优先级从高到低为 CLI 标志 > 环境变量 > settings.json,这一点在 packages/core/src/telemetry/config.ts 的 resolveTelemetrySettings 中得到印证:函数按 argv → env → settings 的顺序依次取第一个非空值。

配置参数总表

Setting 环境变量 CLI Flag 说明 取值 默认值
enabled QWEN_TELEMETRY_ENABLED --telemetry / --no-telemetry 启用或禁用遥测 true/false false
target QWEN_TELEMETRY_TARGET --telemetry-target <local|gcp>(已废弃) 信息性目的地标签;不控制导出器路由——请设置 otlpEndpoint 或 outfile 来配置数据去向 "gcp"/"local" "local"
otlpEndpoint QWEN_TELEMETRY_OTLP_ENDPOINT --telemetry-otlp-endpoint <URL> OTLP Collector 端点 URL 字符串 http://localhost:4317
otlpProtocol QWEN_TELEMETRY_OTLP_PROTOCOL --telemetry-otlp-protocol <grpc|http> OTLP 传输协议 "grpc"/"http" "grpc"
otlpTracesEndpoint QWEN_TELEMETRY_OTLP_TRACES_ENDPOINT - 仅 HTTP 协议的 traces 逐信号端点覆盖 URL 字符串 -
otlpLogsEndpoint QWEN_TELEMETRY_OTLP_LOGS_ENDPOINT - 仅 HTTP 协议的 logs 逐信号端点覆盖 URL 字符串 -
otlpMetricsEndpoint QWEN_TELEMETRY_OTLP_METRICS_ENDPOINT - 仅 HTTP 协议的 metrics 逐信号端点覆盖 URL 字符串 -
outfile QWEN_TELEMETRY_OUTFILE --telemetry-outfile <path> 将遥测写入文件(覆盖 OTLP 导出) 文件路径 -
logPrompts QWEN_TELEMETRY_LOG_PROMPTS --telemetry-log-prompts / --no-telemetry-log-prompts 在遥测日志中包含用户提示内容与 API 请求/响应文本 true/false true
userId QWEN_TELEMETRY_USER_ID - 稳定的终端用户标识,写入 GenAI Span 的 ARMS 扩展属性 gen_ai.user.id;建议使用假名化值 字符串 -
includeSensitiveSpanAttributes QWEN_TELEMETRY_INCLUDE_SENSITIVE_SPAN_ATTRIBUTES - 将标准 GenAI 消息、指令、工具定义、工具参数及成功工具结果作为原生 Span 属性包含 true/false false
sensitiveSpanAttributeMaxLength QWEN_TELEMETRY_SENSITIVE_SPAN_ATTRIBUTE_MAX_LENGTH - 每个敏感原生 Span 属性的紧凑 JSON 字符串最大长度;后端拒绝大属性时可调低 1..104857600 1048576
resourceAttributes OTEL_RESOURCE_ATTRIBUTES(+ OTEL_SERVICE_NAME) - 附加到每条导出 Span/日志/指标上的静态资源属性 key=value,… {}
metrics.includeSessionId QWEN_TELEMETRY_METRICS_INCLUDE_SESSION_ID - 在指标数据点上包含 session.id。默认关闭,以保护指标后端免受时间序列扇出 true/false false

布尔与整数环境变量的解析规则

  • 布尔环境变量(enabled、logPrompts、includeSensitiveSpanAttributes):设为 true 或 1 即启用,其他任何值都会禁用。该逻辑对应源码 config.ts 中的 parseBooleanEnvFlag。
  • 整数环境变量:QWEN_TELEMETRY_SENSITIVE_SPAN_ATTRIBUTE_MAX_LENGTH 必须为正整数,非法值会导致遥测配置解析**失败关闭(fail closed)**而非静默回退。源码中 config.ts 通过 parseSensitiveSpanAttributeMaxLengthEnvValue 抛出 FatalConfigError;常量定义见 constants.ts:默认 1 MiB(1048576),合法范围为 1..104857600(100 MiB)。
  • 同理,QWEN_TELEMETRY_TARGET 只接受 local/gcp,QWEN_TELEMETRY_OTLP_PROTOCOL 只接受 grpc/http,非法值同样抛 FatalConfigError。

端点解析优先级:QWEN_ 变体优先于 OTEL_ 变体

逐信号端点环境变量同时接受标准 OpenTelemetry 名称:

  • OTEL_EXPORTER_OTLP_TRACES_ENDPOINT
  • OTEL_EXPORTER_OTLP_LOGS_ENDPOINT
  • OTEL_EXPORTER_OTLP_METRICS_ENDPOINT

QWEN_TELEMETRY_OTLP_* 变体优先于 OTEL_* 变体(源码中 config.ts 第 200-213 行的合并顺序可验证)。基础端点 otlpEndpoint 还接受标准的 OTEL_EXPORTER_OTLP_ENDPOINT。

HTTP OTLP 信号路由

使用 HTTP 协议(otlpProtocol: "http")时,Qwen Code 会自动在基础 otlpEndpoint 后追加信号路径 /v1/traces、/v1/logs、/v1/metrics。例如 http://collector:4318 的 traces 端点会变成 http://collector:4318/v1/traces;若 URL 已以信号路径结尾则原样使用;逐信号端点覆盖优先于基础端点且按原样使用。gRPC 协议基于服务名路由,不追加路径。

该行为与源码 packages/core/src/telemetry/otlp-urls.ts 的 resolveHttpOtlpUrl 完全一致:函数用 URL 规范化路径、去除尾部斜杠,若不以信号路径结尾则拼接 /<signal-path>,并保留 query/hash。

终端用户标识(End-user identity)

telemetry.userId 与 QWEN_TELEMETRY_USER_ID 是 ARMS Span 属性 gen_ai.user.id 的显式 opt-in。规则如下:

  • 环境变量在两侧 trim 后优先于 settings;空环境值回退到 settings;
  • 标识只写入 interaction、LLM、Tool、Agent 这四类 Span,不是 Resource 属性、日志/指标属性、出站 Baggage 值或当前 OpenTelemetry GenAI 标准字段;
  • 建议使用稳定的假名化标识;
  • 该值在启动时解析,配置变更需重启生效;
  • 在服务于多个终端用户的 daemon 或 channel 实例上,不要配置进程级值。

更多配置细节可查阅 Configuration Guide。

敏感 Span 属性:安全边界与成本控制

gen_ai.tool.description 是非敏感的静态注册表元数据,独立于 includeSensitiveSpanAttributes 发射(包括 MCP 服务器与其他工作区工具提供者提供的描述),值限制为 4096 个 UTF-16 码元,绝不包含动态调用细节。

当 includeSensitiveSpanAttributes 启用时会发生两件事:

  1. 原生 Span 属性携带标准 OpenTelemetry GenAI JSON:

    • 主 Agent 与 LLM 输入消息(gen_ai.input.messages)
    • 系统指令(gen_ai.system_instructions)
    • 工具定义(gen_ai.tool.definitions)
    • 主 Agent 与 LLM 输出消息(gen_ai.output.messages)
    • 最终执行的工具参数(gen_ai.tool.call.arguments)
    • 成功工具结果(gen_ai.tool.call.result)
    • interaction span 保留兼容性 new_context 属性

    主 Agent 输入是上下文展开前的一份原始用户文本投影,主 Agent 输出是所有工具与续跑工作落定后的一份最终用户可见回答;LLM 值仍来自 provider-final SDK 请求对象与原始 provider 响应,因此其输入可包含历史、展开文件、系统指令与工具结果,输出可包含所有 provider 候选。每个标准 GenAI 值都是紧凑 JSON,必须完整且 schema 合法:无效、循环引用或超长的值整体省略,JSON 绝不截断,也不发射预览、哈希或截断元数据(interaction 特有的 new_context 属性保留其既有截断行为)。上限默认 1 MiB,范围 1..104857600,按 JavaScript 字符串长度而非 UTF-8 字节计量——非 ASCII 内容在 OTLP 导出后会占用更多字节。

  2. Log-to-span 桥接 Span(无日志端点时导出 HTTP traces 的场景)保留 function_args、error、error.message、error_message,以及(当 logPrompts 也启用时)prompt、request_text、response_text,而非丢弃这些属性。

⚠️ 安全警告:启用此开关会把完整对话历史、read_file 读取的文件内容、shell 命令及其输出(包括环境变量或参数中的密钥)、模型响应全部流式发送到所配置的 OTLP 后端。请将后端视为特权数据汇(privileged data sink)。该标志默认为 false。

成本 / 负载大小:在默认上限下,一个 LLM Span 在输入、输出、系统指令与工具定义上最多承载约 4 MiB;一个 Tool Span 在参数与结果上约 2 MiB;一个 interaction 在 Agent 输入、Agent 输出与兼容性 new_context 上约 3 MiB。这是 Qwen Code 应用侧上限,并非每个 Collector/后端都会接受如此大的单个属性。若 Span 被拒绝或丢弃,请调低 sensitiveSpanAttributeMaxLength(例如 61440)并监控导出器吞吐。

该设置不会禁用 OTel 日志或其他遥测汇中的敏感数据:非内部 API 响应遥测可填充 response_text,因此 OTel 日志、UI 遥测与聊天记录可能独立于该设置收到响应文本。QwenLogger 则不包含 response_text。

资源属性(Resource Attributes):按团队/环境切分数据

资源属性是附加到每条通过 OTLP 导出的 Span、日志与指标上的静态键值对,用于按团队、环境、部署区域等维度切片。

两个来源按优先级合并(低 → 高):

  1. 标准 OTEL_RESOURCE_ATTRIBUTES 环境变量;
  2. .qwen/settings.json 中的 telemetry.resourceAttributes(键冲突时覆盖环境变量)。

OTEL_SERVICE_NAME 是独立的逃生舱:设置时覆盖任何其他来源的 service.name(符合 OpenTelemetry 规范)。

配置示例

按团队 / 环境切片所有遥测:

export OTEL_RESOURCE_ATTRIBUTES="team=platform,env=prod,cost_center=eng-123"

通过 service.name 路由到租户级 Collector:

export OTEL_SERVICE_NAME=qwen-code-ci

舰队基线(~/.qwen/settings.json)+ 单主机覆盖:

{
  "telemetry": {
    "resourceAttributes": {
      "deployment.environment": "production",
      "service.namespace": "engineering-tooling"
    }
  }
}
# 不修改 settings 即可添加一次性标签:
export OTEL_RESOURCE_ATTRIBUTES="debug_run=true"

保留键(Reserved keys)

以下键由运行时控制,不可覆盖:

  • service.version —— 始终设为当前 CLI 版本;任何来源的设置都会被静默丢弃并告警(防版本伪造)。
  • session.id —— 按会话由运行时注入。来自环境变量或 settings 的用户值会被丢弃并告警。原因:Resource 属性会自动附加到每个指标数据点,允许用户覆盖会绕过下文 基数控制 的保护;Span 与日志始终携带 session.id。

service.name 不是保留键,遵循上述优先级链。源码 packages/core/src/telemetry/resource-attributes.ts 中的 RESERVED_RESOURCE_ATTRIBUTE_KEYS 集合定义了这两个保留键。

格式要求

OTEL_RESOURCE_ATTRIBUTES 遵循 OpenTelemetry 规范:key1=value1,key2=value2,值需百分号编码。值中的空格编码为 %20,逗号编码为 %2C(未编码的逗号会在错误边界处切开值,后半段会作为畸形数据被丢弃)。畸形键值对被跳过并告警,不会导致遥测启动失败。

排障:用户属性看似未生效

保留键、畸形键值对、非字符串 settings 值、无效百分号编码都会被静默丢弃,并通过 OpenTelemetry diagnostics 通道告警。该通道路由到调试日志文件(~/.qwen/log/otel-*.log)而不是控制台,因此可能看起来像静默失败。这也是源码 sdk.ts 将 diag.setLogger 指向 createDebugLogger('OTEL') 的原因——OTel SDK 诊断必须避免写入控制台,因为控制台输出可能进入用户可见的 UI。

如果自定义资源属性没有出现在导出的遥测中:

  1. 检查 ~/.qwen/log/otel-*.log 中匹配 cannot override(保留键被丢弃)、Skipping malformed(环境变量对畸形)、must be a string(settings 值非字符串)的行;
  2. 确认环境变量在 qwen-code 进程环境中已设置(而不只是你的 shell),且值已百分号编码;
  3. 确认 telemetry.enabled 为 true——遥测初始化只在启用时运行。

基数控制(Cardinality Controls):保护指标后端

指标在后端按属性集聚合——每个不同的属性值组合都会产生一条新时间序列。把 session.id 这类高基数字段附加到指标上,会造成与会话数成正比的时间序列扇出,迅速耗尽指标后端存储。

因此 Qwen Code 默认将高基数属性排除在指标数据点之外。Span 与日志是逐事件的、不受影响,继续携带 session.id 用于追踪与日志关联。

telemetry.metrics.includeSessionId(默认 false)

设为 true(通过 settings 或 QWEN_TELEMETRY_METRICS_INCLUDE_SESSION_ID=true)会把 session.id 重新附加到每个指标数据点。

⚠️ 警告:每个 CLI 会话都会产生新值。舰队长期开启会撑爆指标存储,仅建议短期调试使用。长期会话关联请查询 trace 或 log 后端。

从早期版本迁移

此前版本默认将 session.id 附加到指标。如果你的 Prometheus 查询 / Grafana 面板 / 告警规则引用了指标上的 session_id,有两个选项:

方案 A —— 恢复旧行为用于短期调试:

export QWEN_TELEMETRY_METRICS_INCLUDE_SESSION_ID=true

或:

{
  "telemetry": {
    "metrics": { "includeSessionId": true }
  }
}

方案 B(推荐) —— 将会话级分析移出指标。Span 与日志仍携带 session.id,trace/log 后端(Jaeger、Tempo、Loki、阿里云 SLS / ARMS Tracing)原生支持按会话切片且无基数压力。

客户端 HTTP Span:出站 fetch 的可观测性

遥测启用时,Qwen Code 注册 UndiciInstrumentation,为进程发起的每次出站 fetch() 请求创建客户端 HTTP Span——覆盖 LLM SDK(openai、@google/genai、@anthropic-ai/sdk)、MCP StreamableHTTP 客户端、WebFetch 工具以及 IDE 扩展的进程外调用。该 Span 可独立观察网络延迟(TTFB / 响应体传输),与上游模型处理时间区分开——这是既有 api.generateContent Span 无法做到的。

这些 Span 与其余遥测一样发送到你自己的 OTLP Collector(或文件 outfile),不会影响出站 HTTP 请求本身。是否在出站请求流中写入 W3C traceparent 头由独立的、安全相关的设置控制,见下文 出站关联。

反馈循环避免:OTel SDK 内部使用 fetch 上传 OTLP 数据。若不对插桩加以保护,fetch 插桩会追踪这些上传、上传又触发追踪,形成无限循环。Qwen Code 的 undici 插桩配置了 ignoreRequestHook,跳过匹配 telemetry.otlpEndpoint / otlpTracesEndpoint / otlpLogsEndpoint / otlpMetricsEndpoint 前缀的 URL。文件 outfile 模式没有出站 HTTP 上传,该钩子为空操作。

出站关联(SECURITY-RELEVANT)

这些设置刻意放在与 telemetry.* 分离的顶层命名空间中:telemetry 控制数据流入运维者自己的可观测性后端,而 outboundCorrelation.* 控制 qwen-code 写入出站 LLM API 请求流(到达 DashScope、OpenAI、Anthropic 等第三方 LLM 提供方端点)的客户端关联数据。接收方不同,同意决策也不同。所有值默认关闭。

outboundCorrelation.propagateTraceContext

"outboundCorrelation": {
  "propagateTraceContext": false // 默认
}

为 false(默认)时,Qwen Code 在 OTel SDK 上安装 no-op TextMapPropagator。UndiciInstrumentation 仍为你的 OTLP Collector 创建客户端 HTTP Span,但 propagation.inject() 是空操作,因此出站请求上不会写入 traceparent。Trace ID 保持在运维者 Collector 内部。

为 true 时,安装 SDK 默认的 W3C 复合传播器(tracecontext + baggage),并在每次出站 fetch 上写入标准 traceparent 头:

traceparent: 00-<32位hex traceId>-<16位hex parentSpanId>-<01-sampled | 00-not-sampled>

此外,TRACEPARENT 与 TRACESTATE 环境变量会被设置到 shell 子进程(Bash 工具、hooks、monitor)中,使派生命令可以参与同一条分布式追踪。

仅在 LLM 提供方也向你的 OTel Collector 上报、需要跨进程 trace 拼接时才开启——例如 ARMS Tracing 服务 DashScope 的场景。对大多数运维者该值为 false;跨厂商 trace 续接是少见需求。

依赖 telemetry.enabled: true:OTel SDK 仅在遥测启用时初始化,因此 propagateTraceContext 只在该状态下生效。在遥测禁用时设为 true 是静默空操作——没有 SDK、没有传播器、线上没有 traceparent。配置 ARMS+DashScope 关联时请同时核验两个标志:

{
  "telemetry": {
    "enabled": true,
    "otlpTracesEndpoint": "http://tracing-analysis-...",
  },
  "outboundCorrelation": {
    "propagateTraceContext": true,
  },
}

Routify 会话亲和

Qwen Code 经 OpenAI 兼容、DashScope、Anthropic、Gemini 与 Vertex 提供方路径发出的 LLM 请求,在直接以 HTTPS 发往 routify.alibaba-inc.com、routify-online.alibaba-inc.com 或 routify-pub.alibaba-inc.com 时,会在 session_id 头中包含当前 Qwen Code 会话 ID。Routify 的 ModelRouter 使用该值做会话亲和与流量标记。此行为不受 telemetry.enabled 或 outboundCorrelation.* 控制。

初始目的地匹配刻意收窄:Qwen Code 不会把该头附加到子域名、其他 alibaba-inc.com 主机或其他 LLM 端点。匹配之后仍遵循标准 fetch 重定向行为,因此 Routify 响应可以通过重定向请求转发该头。

会话 ID 每次请求都会读取,因此 /clear 创建的新会话无需重建 SDK 客户端即可获得新的亲和值。Gemini 需要显式 Routify baseUrl,以便 Qwen Code 校验目的地。

X-Qwen-Code-Request-Id 未实现。

入站关联:daemon HTTP API

daemon HTTP API 在每个请求上接受标准 W3C traceparent 头。两个消费者独立读取它:

  • 请求 Span 重新挂父(遥测启用时):遥测 SDK 初始化后,有效头会被提取为请求 Span 的远端父级,daemon Span 挂到调用方的 trace 之下而非新开一条。_meta 转发路径读取同一父链,因此经 daemon 请求转发的会话子进程 Span 也会继承它。
  • 访问日志 traceId 字段(两种模式):专用的认证前捕获中间件解析每个请求的头——包括在认证(401)、限流(429)、JSON 体解析(400)被短路或未被任何路由匹配(404)的请求——访问日志以 camelCase traceId 字段输出调用方 trace id。遥测禁用时,该字段是 daemon 日志行与调用方日志(或 trace 后端)之间的唯一连接,一个保存的查询即可覆盖两种模式,无需任何遥测配置。

无效但存在的头会被拒绝(Span 保持无父)并留下限速的 DEBUG breadcrumb(qwen-code.daemon.traceparent.invalid)记录被拒绝的值,因此损坏的跨服务连接可以从 daemon 日志单独诊断。

入站父级下的强制采样

在默认 parentbased_always_on 采样器(以及其他 parentbased 默认值)下,远端父级的 sampled=0 标志是调用方一侧的 head-based 决策,不是丢弃 daemon 遥测的请求,因此提取时会强制在入站父级上设置 SAMPLED 标志。唯一退出方式是 OTEL_TRACES_SAMPLER=parentbased_always_off,它尊重调用方标志——注意它同时会禁用整个 daemon 的根 Span 采样,而不仅限于入站关联的请求。

警告:恒定 traceparent(例如负载测试客户端中硬编码的)会把每个 daemon 请求重新挂到同一条 trace;请为每个请求生成新的头。

阿里云遥测:接入 ARMS / Managed Service for OpenTelemetry

手动 OTLP 导出

要在阿里云 Managed Service for OpenTelemetry 中查看 Qwen Code 遥测,需将 Qwen Code 配置为向 ARMS 提供的 OTLP 端点导出。

注意:仅设置 "target": "gcp" 并不会配置导出目的地。如果未设置 otlpEndpoint,Qwen Code 仍默认 http://localhost:4317。若设置了 outfile,它会覆盖 otlpEndpoint,遥测写入文件而非发送到阿里云。

  1. 在 .qwen/settings.json 中启用遥测并设置 OTLP 端点:

    方案 A:gRPC 协议(标准 OTLP 端点):

    {
      "telemetry": {
        "enabled": true,
        "target": "gcp",
        "otlpEndpoint": "https://<your-otlp-endpoint>",
        "otlpProtocol": "grpc"
      }
    }
    

    方案 B:HTTP 协议 + 逐信号端点(适用于使用非标准路径的后端,例如 /api/otlp/traces 而非 /v1/traces):

    {
      "telemetry": {
        "enabled": true,
        "otlpProtocol": "http",
        "otlpTracesEndpoint": "http://<host>/<token>/api/otlp/traces",
        "otlpLogsEndpoint": "http://<host>/<token>/api/otlp/logs",
        "otlpMetricsEndpoint": "http://<host>/<token>/api/otlp/metrics"
      }
    }
    

    注意:使用 HTTP 协议且只有 otlpEndpoint(无逐信号覆盖)时,Qwen Code 会向基础 URL 追加标准 OTLP 路径(/v1/traces、/v1/logs、/v1/metrics)。如果后端路径不同,请使用方案 B 的逐信号端点覆盖。

    要填充 ARMS Session Analysis 的 User ID,添加一个稳定的假名化身份作为 Span 级设置:

    {
      "telemetry": {
        "userId": "user-079458",
        "resourceAttributes": {
          "acs.arms.service.feature": "genai_app"
        }
      }
    }
    

    容器部署时改为设置 QWEN_TELEMETRY_USER_ID=user-079458。自定义 telemetry.resourceAttributes.user.id 仍是无关的 Resource 维度,不会填充 ARMS Session Analysis;迁移到 Span 级设置时请移除它。

  2. 若阿里云端点需要认证,通过标准 OpenTelemetry 环境变量提供 OTLP 头,例如 OTEL_EXPORTER_OTLP_HEADERS(或信号级变体)。Qwen Code 目前不在 .qwen/settings.json 中直接暴露 OTLP 认证头。

  3. 运行 Qwen Code 并发送提示。

  4. 在 Managed Service for OpenTelemetry 中查看遥测:

    • 使用 Applications 检查 trace 与服务拓扑;
    • 查找 OTLP 端点与接入信息:新控制台(trace.console.aliyun.com 或国际版)进入 Integration Center;旧控制台(tracing.console.aliyun.com)进入 Cluster Configurations → Access point information。

本地遥测:开发调试的两条路径

基于文件的输出(推荐)

  1. 在 .qwen/settings.json 中启用遥测:

    {
      "telemetry": {
        "enabled": true,
        "outfile": ".qwen/telemetry.log"
      }
    }
    

    注意:设置 outfile 后 OTLP 导出自动禁用。target 与 otlpEndpoint 对纯文件输出非必需,可从配置中安全省略。

  2. 运行 Qwen Code 并发送提示。

  3. 在指定文件(如 .qwen/telemetry.log)中查看日志与指标。

基于 Collector 的导出(高级)

  1. 运行自动化脚本(仓库根 package.json 中定义了 telemetry script):

    npm run telemetry -- --target=local
    

    该脚本会:

    • 下载并启动 Jaeger 与 OTEL Collector;
    • 为本地遥测配置你的工作区;
    • 提供 Jaeger UI(http://localhost:16686);
    • 将日志/指标保存到 ~/.qwen/tmp/<projectHash>/otel/collector.log;
    • 退出时停止 Collector(如 Ctrl+C)。
  2. 运行 Qwen Code 并发送提示。

  3. 在 http://localhost:16686 查看 trace,在 Collector 日志文件中查看日志/指标。

日志事件(Logs)全览

日志是特定事件带时间戳的记录。所有日志记录自动包含 event.name 与 event.timestamp 属性,且 sessionId 作为公共属性出现在所有日志与指标上。以下事件按类别列出(属性名与取值均为文档定义的正式契约)。

核心会话事件

  • qwen-code.config:启动时发射一次,携带 CLI 配置。
    • 属性:model、sandbox_enabled、core_tools_enabled、approval_mode、file_filtering_respect_git_ignore、debug_mode、truncate_tool_output_threshold、truncate_tool_output_lines、hooks(逗号分隔,禁用时省略)、ide_enabled、interactive_shell_enabled、mcp_servers、mcp_servers_count、mcp_tools、mcp_tools_count、output_format、skills、subagents
  • session.start:会话开始。启动时在遥测初始化后发射,每次会话切换再次发射。
    • 属性:session.id(字符串)、session.previous_id(字符串,仅当本次开始延续了持久化对话并生成了新会话 id 时出现)
  • session.end:会话结束。在会话切换替换当前会话前及遥测关闭时发射。
    • 属性:session.id(字符串)
  • qwen-code.user_prompt:用户提交提示。
    • 属性:prompt_length(int)、prompt_id(string)、prompt(string,log_prompts_enabled 为 false 时排除)、auth_type(string)
  • qwen-code.user_retry:用户重试最后一条提示。
    • 属性:prompt_id(string)
  • qwen-code.conversation_finished:一轮对话序列完成。
    • 属性:approvalMode(string)、turnCount(int)
  • qwen-code.user_feedback:用户提交会话反馈。
    • 属性:session_id(string)、rating(int:1=差,2=一般,3=好)、model(string)、approval_mode(string)、prompt_id(string,可选)

工具事件

  • qwen-code.tool_call:每次函数/工具调用。终端事件已归一化,status 是权威值:成功与取消事件省略错误字段,错误事件总是有非空 error_type(生产者未分类时取 unknown)。空白工具名以 unknown_tool 发射。缺失的 execution_status 归一化为 unknown,绝不从终端 status 推断。
    • 属性:function_name(string)、function_args(object)、call_id(string,可选)、duration_ms(int)、status(string:"success"、"error"、"cancelled")、execution_status(string:"not_started"、"success"、"error"、"cancelled"、"unknown")、success(boolean)、decision(string:"accept"、"reject"、"auto_accept"、"modify",可选)、error(string,可选)、error_type(string,错误事件出现)、prompt_id(string)、response_id(string,可选)、content_length(int,可选)、tool_type(string:"native" 或 "mcp")、mcp_server_name(string,可选)、metadata(object,可选——文件写入工具包含 model_added_lines、model_removed_lines、user_added_lines、user_removed_lines、model_added_chars、model_removed_chars、user_added_chars、user_removed_chars)
  • qwen-code.file_operation:每次文件操作。
    • 属性:tool_name(string)、operation(string:"create"、"read"、"update")、lines(int,可选)、mimetype(string,可选)、extension(string,可选)、programming_language(string,可选)
  • qwen-code.tool_output_truncated:工具输出超过大小阈值。
    • 属性:tool_name(string)、original_content_length(int)、truncated_content_length(int)、threshold(int)、lines(int)、prompt_id(string)

API 事件

  • qwen-code.api_request:发往 LLM API 的出站请求。
    • 属性:model(string)、prompt_id(string)、request_text(string,可选——仅当 log_prompts_enabled 为 true 时包含请求内容;log-to-span 桥接 Span 还额外要求 includeSensitiveSpanAttributes)、subagent_name(string,可选)
  • qwen-code.api_response:收到 LLM API 响应。
    • 属性:response_id(string)、model(string)、status_code(int/string,可选)、duration_ms(int)、input_token_count(int)、output_token_count(int)、cached_content_token_count(int)、thoughts_token_count(int)、total_token_count(int)、prompt_id(string)、auth_type(string,可选)、response_text(string,可选——仅当 log_prompts_enabled 为 true 时包含可见响应内容;log-to-span 桥接 Span 还额外要求 includeSensitiveSpanAttributes;内部 prompt id 或无可见文本的响应不携带内容)、subagent_name(string,可选)
  • qwen-code.api_error:API 请求失败。
    • 属性:model(string)、prompt_id(string)、duration_ms(int)、error_message(string)、response_id(string,可选)、auth_type(string,可选)、error_type(string,可选)、status_code(int/string,可选)、subagent_name(string,可选)
    • 同时为兼容性发射 OTel 标准别名(http.status_code、error.message、model_name、duration)。
  • qwen-code.api_cancel:API 请求被用户取消。
    • 属性:model(string)、prompt_id(string)、auth_type(string,可选)、loop_wakeups_cancelled(int,可选)
  • qwen-code.api_retry:LLM 调用点的 HTTP 状态重试(429/5xx)。与处理 InvalidStreamError 重试(独立预算)的 chat.content_retry 不同。
    • 属性:model(string)、prompt_id(string,可选)、attempt_number(int)、error_type(string,可选)、error_message(string)、status_code(int/string,可选)、retry_delay_ms(int)、duration_ms(int,等于 retry_delay_ms——退避睡眠而非 HTTP 往返;尝试耗时请查 qwen-code.llm_request span)、subagent_name(string,可选)
  • qwen-code.malformed_json_response:generateJson 响应无法解析。
    • 属性:model(string)
  • qwen-code.flash_fallback:切换到 flash 模型作为回退。
    • 属性:auth_type(string)
  • qwen-code.ripgrep_fallback:切换到 grep 作为回退。
    • 属性:use_ripgrep(boolean)、use_builtin_ripgrep(boolean)、error(string,可选)

韧性(Resilience)事件

  • qwen-code.chat.content_retry:内容错误重试(如空流)。
    • 属性:attempt_number(int)、error_type(string)、retry_delay_ms(int)、model(string)
  • qwen-code.chat.content_retry_failure:所有内容重试耗尽。
    • 属性:total_attempts(int)、final_error_type(string)、total_duration_ms(int,可选)、model(string)
  • qwen-code.chat.invalid_chunk:流中收到无效 chunk。
    • 属性:error.message(string,可选)

命令与扩展事件

  • qwen-code.slash_command:用户执行斜杠命令。
    • 属性:command(string)、subcommand(string,可选)、status(string:"success" 或 "error",可选)
  • qwen-code.slash_command.model:用户通过 /model 切换模型。
    • 属性:model_name(string)
  • qwen-code.skill_launch:技能启动。
    • 属性:skill_name(string)、success(boolean)、prompt_id(string)
  • qwen-code.extension_install / extension_uninstall / extension_enable / extension_disable / extension_update:扩展生命周期事件,分别携带 extension_name、extension_version、extension_source、status、setting_scope、extension_id、extension_previous_version 等属性。
  • qwen-code.ide_connection:IDE 连接事件。
    • 属性:connection_type(string:"start" 或 "session")
  • qwen-code.auth:认证事件。
    • 属性:auth_type(string)、action_type("auto"、"manual"、"coding-plan")、status("success"、"error"、"cancelled")、error_message(可选)

子 Agent 事件

  • qwen-code.subagent_execution:子 Agent 生命周期事件。
    • 属性:subagent_name(string)、status("started"、"completed"、"failed"、"cancelled")、terminate_reason(可选)、result(可选)、execution_summary(可选)

Arena 事件

  • qwen-code.arena_session_started:Arena 会话开始。
    • 属性:arena_session_id(string)、model_ids(JSON 字符串数组)、task_length(int)
  • qwen-code.arena_agent_completed:Arena Agent 完成。
    • 属性:arena_session_id、agent_session_id、agent_model_id、status("completed"/"failed"/"cancelled")、duration_ms、rounds、total_tokens、input_tokens、output_tokens、tool_calls、successful_tool_calls、failed_tool_calls
  • qwen-code.arena_session_ended:Arena 会话完成。
    • 属性:arena_session_id、status("selected"/"discarded"/"failed"/"cancelled")、duration_ms、display_backend(可选)、agent_count、completed_agents、failed_agents、cancelled_agents、winner_model_id(可选)

工作流事件

  • qwen-code.workflow_keyword:工作流关键词触发。
  • qwen-code.workflow_run:工作流运行到达终态。
    • 属性:status、agents_dispatched、agents_completed(所有已落定派发)、agents_failed(状态为失败的已落定派发)、agents_cached(由先前运行提供服务的已落定派发)、agents_respawned(先前失败或中断尝试后重新运行的派发调用)、phase_count、tokens_spent、duration_ms。agents_failed 与 agents_cached 是 agents_completed 的子集,agents_respawned 描述来源而非额外结果计数。

自动记忆(Auto-Memory)事件

  • qwen-code.memory.extract:记忆提取运行完成。
    • 属性:trigger("auto"/"manual")、status("completed"/"skipped"/"failed")、skipped_reason(可选)、patches_count、touched_topics(string)、duration_ms
  • qwen-code.memory.dream:记忆整合(dream)运行完成。
    • 属性:trigger("auto"/"manual")、status("updated"/"noop"/"failed"/"cancelled")、deduped_entries、touched_topics_count、touched_topics(string)、duration_ms
  • qwen-code.memory.recall:记忆召回操作完成。
    • 属性:query_length、docs_scanned、docs_selected、strategy("none"/"heuristic"/"model")、duration_ms

提示建议与推测(Speculation)事件

  • qwen-code.prompt_suggestion:提示建议结果。
    • 属性:outcome("accepted"/"ignored"/"suppressed")、prompt_id(可选)、accept_method("tab"/"enter"/"right",可选)、accept_source("live"/"fallback",可选)、time_to_accept_ms(可选)、time_to_ignore_ms(可选)、time_to_first_keystroke_ms(可选)、suggestion_length(可选)、similarity(可选)、was_focused_when_shown(可选)、reason(可选)
  • qwen-code.speculation:推测执行结果。
    • 属性:outcome("accepted"/"aborted"/"failed")、turns_used、files_written、tool_use_count、duration_ms、boundary_type(可选)、had_pipelined_suggestion(boolean)

其他事件

  • qwen-code.chat_compression:聊天上下文被压缩。
    • 属性:tokens_before(int)、tokens_after(int)、compression_input_token_count(int,可选)、compression_output_token_count(int,可选)
  • qwen-code.next_speaker_check:下一个发言者判定。
    • 属性:prompt_id(string)、finish_reason(string)、result(string)
  • loop_detected:Agent 执行期间检测到循环。(注意:发射时不带 qwen-code. 前缀——既有不一致。)
    • 属性:loop_type(string)、prompt_id(string)
  • kitty_sequence_overflow:Kitty 图形协议序列超出缓冲区。(同样不带 qwen-code. 前缀。)
    • 属性:sequence_length(int)、truncated_sequence(string,前 20 字符)

上述事件名在 packages/core/src/telemetry/constants.ts 中以常量形式集中定义,事件名称与文档契约保持一致,避免写点与文档漂移。

指标(Metrics)全览

指标是随时间变化的数值度量,名称使用 qwen-code.* 前缀。指标在 packages/core/src/telemetry/metrics.ts 与 packages/core/src/telemetry/daemon-metrics.ts 中通过 meter.createCounter / createHistogram 注册。

核心指标

  • qwen-code.session.count(Counter, Int):每次 CLI 启动递增一次。
  • qwen-code.tool.call.count(Counter, Int):统计工具调用。
    • 属性:function_name、status("success"/"error"/"cancelled")、success(boolean,为兼容保留)、decision("accept"/"reject"/"auto_accept"/"modify",可选)、tool_type("mcp"/"native",可选)
  • qwen-code.tool.execution.count(Counter, Int):统计工具执行结果。刻意不带 function_name 维度以保持低基数——因此执行失败率无法归因到具体工具,需下沉到 qwen-code.tool_call 日志;计算执行失败率时排除 unknown、not_started、cancelled(分母为 success + error)。
    • 属性:execution_status("not_started"/"success"/"error"/"cancelled"/"unknown")、tool_type("mcp"/"native"),以及全局配置的公共指标属性(如 opt-in 的 session.id)
  • qwen-code.tool.call.latency(Histogram, ms):工具调用延迟。
    • 属性:function_name(string)
  • qwen-code.api.request.count(Counter, Int):统计所有 API 请求。
    • 属性:model、status_code、error_type(可选)
  • qwen-code.api.request.latency(Histogram, ms):API 请求延迟。
    • 属性:model(string)
  • qwen-code.token.usage(Counter, Int):统计使用的 Token。
    • 属性:model、type("input"/"output"/"thought"/"cache")
  • qwen-code.file.operation.count(Counter, Int):统计文件操作。
    • 属性:operation("create"/"read"/"update")、lines(可选)、mimetype(可选)、extension(可选)、programming_language(可选)
  • qwen-code.chat_compression(Counter, Int):统计聊天压缩操作。
    • 属性:tokens_before(int)、tokens_after(int)
  • qwen-code.slash_command.model.call_count(Counter, Int):统计模型斜杠命令调用。
    • 属性:slash_command.model.model_name(string)
  • qwen-code.subagent.execution.count(Counter, Int):统计子 Agent 执行事件。
    • 属性:subagent_name、status("started"/"completed"/"failed"/"cancelled")、terminate_reason(可选)

韧性指标

  • qwen-code.api.retry.count(Counter, Int):LLM 调用点的 HTTP 状态重试(429/5xx)。
    • 属性:model(string)
  • qwen-code.chat.content_retry.count(Counter, Int):内容错误重试。
  • qwen-code.chat.content_retry_failure.count(Counter, Int):所有内容重试耗尽。
  • qwen-code.chat.invalid_chunk.count(Counter, Int):来自流的无效 chunk。

Arena 指标

  • qwen-code.arena.session.count(Counter, Int):按状态统计 Arena 会话。
    • 属性:status、display_backend(可选)
  • qwen-code.arena.session.duration(Histogram, ms):Arena 会话时长。
    • 属性:status
  • qwen-code.arena.agent.count(Counter, Int):Arena Agent 完成数。
    • 属性:status、model_id
  • qwen-code.arena.agent.duration(Histogram, ms):Arena Agent 执行时长。
    • 属性:model_id
  • qwen-code.arena.agent.tokens(Counter, Int):Arena Agent 的 Token 用量。
    • 属性:model_id、type("input"/"output")
  • qwen-code.arena.result.selected(Counter, Int):Arena 结果选择。
    • 属性:model_id

自动记忆指标

  • qwen-code.memory.extract.count(Counter, Int):自动记忆提取运行。
    • 属性:trigger("auto"/"manual")、status
  • qwen-code.memory.extract.duration(Histogram, ms):提取时长。
    • 属性:trigger、status
  • qwen-code.memory.dream.count(Counter, Int):自动记忆 dream 运行。
    • 属性:trigger("auto"/"manual")、status
  • qwen-code.memory.dream.duration(Histogram, ms):dream 运行时长。
    • 属性:trigger、status
  • qwen-code.memory.recall.count(Counter, Int):自动记忆召回操作。
    • 属性:strategy("none"/"heuristic"/"model")
  • qwen-code.memory.recall.duration(Histogram, ms):召回时长。
    • 属性:strategy

API 请求分解

  • qwen-code.api.request.breakdown(Histogram, ms):按阶段分解的 API 请求耗时。
    • 属性:model、phase("request_preparation"/"network_latency"/"response_processing"/"token_processing")

Daemon 指标:守护进程专属观测

daemon 进程(长驻 HTTP 服务器模式)暴露自己的指标集。三个 Observable Gauge(daemon.session.active、daemon.sse.active、daemon.process.heap_used)是基于回调的指标,在每个采集间隔更新;registerDaemonGaugeCallbacks() 必须在 daemon 初始化期间调用以注册观测回调(对应源码 daemon-metrics.ts)。

HTTP

  • qwen-code.daemon.http.request.count(Counter, Int):按路由与状态类统计请求数。
    • 属性:route、status_class("2xx"/"4xx"/"5xx")
  • qwen-code.daemon.http.request.duration(Histogram, ms):请求时长。
    • 属性:route
    • Buckets:1, 2, 5, 10, 25, 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000

会话

  • qwen-code.daemon.session.active(ObservableGauge, Int):当前活动会话数。
  • qwen-code.daemon.session.lifecycle(Counter, Int):会话生命周期事件。
    • 属性:action("spawn"/"close"/"die")

通道

  • qwen-code.daemon.channel.lifecycle(Counter, Int):ACP 通道生命周期事件。
    • 属性:action("spawn"/"exit")、expected(boolean,可选)

提示(Prompts)

  • qwen-code.daemon.prompt.queue_wait(Histogram, ms):提示 FIFO 队列等待时间。
    • Buckets:1, 5, 10, 50, 100, 500, 1000, 5000, 10000, 30000, 60000
  • qwen-code.daemon.prompt.duration(Histogram, ms):端到端提示时长。
    • Buckets:100, 500, 1000, 2500, 5000, 10000, 30000, 60000, 120000, 300000, 600000

错误

  • qwen-code.daemon.bridge.error.count(Counter, Int):按类型统计桥接错误。
    • 属性:error_type(已知类名或 "unknown")
  • qwen-code.daemon.cancel.count(Counter, Int):取消请求数。

资源

  • qwen-code.daemon.sse.active(ObservableGauge, Int):活动 SSE 连接数。
  • qwen-code.daemon.process.heap_used(ObservableGauge, Int, bytes):堆内存使用量。

Span(分布式追踪)全览

分布式追踪 Span 构成以 qwen-code.interaction 为根的树。CLI 中每个 interaction 是带自己 traceId 的 trace 根;ACP 与 daemon 路径可能继承入站父上下文。跨提示关联使用 session.id 属性。

会话生命周期也通过 OpenTelemetry General Session 语义约定导出:OTel 日志管道启用时,Qwen Code 发射带必需 session.id 属性的 session.start 与 session.end 日志事件。恢复的持久化对话仅在恢复的会话 id 与当前不同时,在 session.start 事件上携带 session.previous_id;冷启动恢复(--resume、--continue、--fork-session)不携带它。/clear 等替换流程因丢弃前一对话而刻意不声明延续。

既有 Qwen 特定 qwen-code.config/cli_config 与 RUM session_start 记录保留兼容;GenAI 请求 Span 继续使用 gen_ai.conversation.id 表示同一所属会话 ID。

主要 Span 定义

  • qwen-code.interaction:主 Agent 调用 Span,覆盖一次逻辑提示的所有 LLM 请求、工具审批/执行与续跑。用户查询、重试、cron 提示、通知、队友消息与 Goal 回合创建调用;工具结果、hooks 与 steering 复用精确的活动 prompt ID。
    • GenAI 属性:gen_ai.operation.name(invoke_agent)、gen_ai.agent.name(qwen-code)、gen_ai.conversation.id、可选 gen_ai.output.type(仅配置 JSON Schema 时为 json)、敏感 gen_ai.input.messages、敏感 gen_ai.output.messages、可选 ARMS 扩展 gen_ai.user.id
    • 兼容属性:session.id、qwen-code.prompt_id、qwen-code.message_type、qwen-code.model、qwen-code.approval_mode、interaction.sequence、interaction.duration_ms、qwen-code.turn_status("ok"/"error"/"cancelled")
    • gen_ai.request.model 刻意省略,因为 Agent 支持覆盖、回退与动态模型选择。gen_ai.provider.name 与 Agent ID/版本/描述同样省略。
    • Agent 输入是一份原始用户提示(非展开后的模型请求);Agent 输出是一份最终用户可见文本投影;结构化 JSON 使用紧凑 JSON 文本且 finish_reason=tool_call。两者仅在敏感 Span 属性启用且完整 JSON 在逐属性限制内时发射。
  • qwen-code.llm_request:包裹单次 LLM API 调用。
    • GenAI 属性:gen_ai.operation.name、gen_ai.provider.name、gen_ai.conversation.id、可选 ARMS 扩展 gen_ai.user.id、gen_ai.request.model、gen_ai.request.stream、gen_ai.request.choice.count、gen_ai.request.max_tokens、gen_ai.request.temperature、gen_ai.request.top_p、gen_ai.request.frequency_penalty、gen_ai.request.presence_penalty、gen_ai.request.stop_sequences、可选 gen_ai.output.type、gen_ai.response.id、gen_ai.response.model、gen_ai.response.finish_reasons、gen_ai.response.time_to_first_chunk、gen_ai.usage.input_tokens、gen_ai.usage.output_tokens、gen_ai.usage.cache_read.input_tokens、gen_ai.usage.cache_creation.input_tokens
    • 兼容属性:session.id、qwen-code.prompt_id、llm_request.context("subagent"/"interaction"/"standalone")、duration_ms、ttft_ms、request_setup_ms、attempt、retry_total_delay_ms、sampling_ms、output_tokens_per_second、success、error、finish_reason、thoughts_token_count、subagent_name、error_type、error_status_code
    • 标准响应字段来自 provider 响应;标准 Token 字段仅发射 provider 报告的非负安全整数。若 provider 只报告总 Token 数,input/output 用量省略而非估算。
    • 标准请求参数字段来自 adapter 默认值、覆盖、不支持字段移除与输出窗口钳制后的第一个 provider-final SDK 请求对象。Qwen Code 不推断 SDK 或服务器默认值。
    • 流式请求发射 gen_ai.request.stream=true;gen_ai.response.time_to_first_chunk 测量从 provider 调用到 provider adapter 产出首个归一化响应的秒数(可能与首个原始网络帧不同)。非流式请求省略两个标准流式属性——语义约定中缺失 gen_ai.request.stream 即表示非流式。
  • qwen-code.tool:包裹完整工具生命周期(审批等待 + 执行)。
    • 属性:session.id、可选 ARMS 扩展 gen_ai.user.id、gen_ai.operation.name(execute_tool)、可选继承 gen_ai.agent.name、gen_ai.tool.name、gen_ai.tool.type(function)、gen_ai.tool.call.id、tool.call_id、duration_ms、success、error、失败时 error.type、tool.failure_kind(string,可选——具体失败原因,如 "cancelled"、"tool_error"、"tool_exception"、"timeout"、"permission_denied"、"pre_hook_blocked")。该词汇表在 constants.ts 中作为 TOOL_FAILURE_KIND_* 常量集中定义,写点与文档不会漂移。
  • qwen-code.tool.execution:包裹工具执行阶段(审批后)。仅对已尝试执行发射。
    • 属性:session.id、gen_ai.tool.name(可选)、tool.call_id(可选)、duration_ms、success、error、execution_status("success"/"error"/"cancelled")、error_type、error.type
  • qwen-code.tool.blocked_on_user:工具等待用户审批的时间。
    • 属性:session.id、tool.name、tool.call_id、duration_ms、decision("proceed_once"/"proceed_always"/"cancel"/"aborted"/"auto_approved"/"error")、source("cli"/"ide"/"hook"/"auto"/"system")
  • qwen-code.hook:包裹每个 pre/post-tool-use hook 触发点。
    • 属性:session.id、hook_event("PreToolUse"/"PostToolUse"/"PostToolUseFailure"/"PostToolBatch")、tool.name、tool.use_id(可选)、is_interrupt(boolean,可选)、duration_ms、success、should_proceed(可选)、should_stop(可选)、block_type(可选)、error(可选)
  • qwen-code.subagent:包裹单次子 Agent 调用。
    • 属性:gen_ai.operation.name(invoke_agent)、gen_ai.agent.name、gen_ai.agent.description、gen_ai.conversation.id、可选 ARMS 扩展 gen_ai.user.id、可选 gen_ai.request.model、qwen-code.subagent.id、qwen-code.subagent.name、qwen-code.subagent.invocation_kind("foreground"/"fork"/"background")、qwen-code.subagent.is_built_in、qwen-code.subagent.depth、qwen-code.subagent.status、qwen-code.subagent.terminate_reason、qwen-code.subagent.duration_ms
  • qwen-code.daemon.request:包裹 daemon HTTP 请求。
    • 属性:http.request.method、http.route、qwen-code.daemon.operation、session.id、http.response.status_code
  • qwen-code.daemon.bridge:包裹 daemon 桥接操作。
    • 属性:qwen-code.daemon.operation

成功与取消的 GenAI Span 将 SpanStatus 保持为 UNSET;失败设置 ERROR、有界的状态描述与低基数 error.type。

GenAI 字段迁移与 ARMS 识别

LLM Span 现使用标准 gen_ai.request.*、gen_ai.response.*、gen_ai.usage.* 字段,无精确等价私有别名。请求采样属性只以标准名称写入,不再发射裸 temperature、top_p、max_tokens、penalty、choice-count 或 stop-sequence 别名。Tool Span 同样使用 gen_ai.tool.name(无 tool.name);blocked-on-user 与 hook Span 保留 tool.name,因为它们不是 GenAI Tool Span。以下无效别名不再发射:gen_ai.usage.cached_tokens、gen_ai.server.time_to_first_token、gen_ai.usage.reasoning_tokens。请使用 gen_ai.usage.cache_read.input_tokens(provider 报告的缓存读取)与 gen_ai.response.time_to_first_chunk(标准流式延迟)。私有 ttft_ms Span 属性仍可用于首次用户可见输出延迟,并继续驱动 /stats、sampling_ms 与输出 Token 吞吐;gen_ai.response.time_to_first_chunk 是独立的标准属性,测量首个归一化 chunk 延迟。完整版本固定契约与延期字段见 GenAI 与 ARMS 字段对齐设计文档。

要让 ARMS 将导出的 Span 识别为 GenAI 应用,显式配置其资源特性:

{
  "telemetry": {
    "resourceAttributes": {
      "acs.arms.service.feature": "genai_app"
    }
  }
}

Qwen Code 不会注入此 ARMS 特定资源属性或 gen_ai.span.kind。ARMS 可从 gen_ai.operation.name 推断 LLM、Tool 与 Agent 角色。

资源指标(Resource Metrics)

  • qwen-code.memory.usage(Histogram, bytes):内存用量。遥测启用时由内存压力监视器记录。
    • 属性:memory_type(string:"heap_used"/"rss")
  • qwen-code.cpu.usage(Histogram, percent):CPU 使用百分比。遥测启用时由内存压力监视器记录。
    • 属性:(无)

性能监控(Reserved):预留但未启用

以下指标已定义但尚未在生产启用,将随专用性能监控配置开关激活:

  • qwen-code.startup.duration(Histogram, ms):按阶段统计 CLI 启动时间。
    • 属性:phase(string)
  • qwen-code.tool.queue.depth(Histogram, count):执行队列中的工具数。
  • qwen-code.tool.execution.breakdown(Histogram, ms):按阶段分解的工具执行时间。
    • 属性:function_name、phase("validation"/"preparation"/"execution"/"result_processing")
  • qwen-code.token.efficiency(Histogram, ratio):Token 效率指标。
    • 属性:model、metric、context(可选)
  • qwen-code.performance.score(Histogram, score):综合性能得分(0-100)。
    • 属性:category、baseline(可选)
  • qwen-code.performance.regression(Counter, Int):回归检测事件。
    • 属性:metric、severity("low"/"medium"/"high")、current_value、baseline_value
  • qwen-code.performance.regression.percentage_change(Histogram, percent):相对基线的百分比变化。
    • 属性:metric、severity、current_value、baseline_value
  • qwen-code.performance.baseline.comparison(Histogram, percent):相对基线的性能。
    • 属性:metric、category、current_value、baseline_value

源码地图:遥测模块速查

若想深入阅读实现,可沿以下路径展开:

结语

Qwen Code 的遥测系统在 OpenTelemetry 之上提供了从配置到导出的完整链路:三层优先级配置让 settings、环境变量与 CLI 标志各司其职;资源属性与基数控制保证了多租户、大规模场景下后端不爆炸;敏感 Span 属性开关配合大小上限兼顾深度诊断与数据安全;入站/出站关联打通了 daemon、子进程与第三方 LLM 提供方之间的分布式链路。对于想在企业内落地 AI Agent 治理、成本核算与性能监控的团队,建议从文件输出模式起步验证数据契约,再逐步切换到阿里云 ARMS 或自建 OTLP Collector,并遵循本文梳理的事件、指标与 Span 定义建立自己的查询面板与告警规则。

登录后查看全文
qwen-code