Qwen Code 可观测性完全指南:基于 OpenTelemetry 的遥测配置、日志、指标与分布式追踪实战
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_ENDPOINTOTEL_EXPORTER_OTLP_LOGS_ENDPOINTOTEL_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 启用时会发生两件事:
-
原生 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 导出后会占用更多字节。 - 主 Agent 与 LLM 输入消息(
-
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、日志与指标上的静态键值对,用于按团队、环境、部署区域等维度切片。
两个来源按优先级合并(低 → 高):
- 标准
OTEL_RESOURCE_ATTRIBUTES环境变量; .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。
如果自定义资源属性没有出现在导出的遥测中:
- 检查
~/.qwen/log/otel-*.log中匹配cannot override(保留键被丢弃)、Skipping malformed(环境变量对畸形)、must be a string(settings 值非字符串)的行; - 确认环境变量在 qwen-code 进程环境中已设置(而不只是你的 shell),且值已百分号编码;
- 确认
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)的请求——访问日志以 camelCasetraceId字段输出调用方 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,遥测写入文件而非发送到阿里云。
-
在
.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 级设置时请移除它。 -
若阿里云端点需要认证,通过标准 OpenTelemetry 环境变量提供 OTLP 头,例如
OTEL_EXPORTER_OTLP_HEADERS(或信号级变体)。Qwen Code 目前不在.qwen/settings.json中直接暴露 OTLP 认证头。 -
运行 Qwen Code 并发送提示。
-
在 Managed Service for OpenTelemetry 中查看遥测:
- 使用
Applications检查 trace 与服务拓扑; - 查找 OTLP 端点与接入信息:新控制台(
trace.console.aliyun.com或国际版)进入Integration Center;旧控制台(tracing.console.aliyun.com)进入Cluster Configurations→Access point information。
- 使用
本地遥测:开发调试的两条路径
基于文件的输出(推荐)
-
在
.qwen/settings.json中启用遥测:{ "telemetry": { "enabled": true, "outfile": ".qwen/telemetry.log" } }注意:设置
outfile后 OTLP 导出自动禁用。target与otlpEndpoint对纯文件输出非必需,可从配置中安全省略。 -
运行 Qwen Code 并发送提示。
-
在指定文件(如
.qwen/telemetry.log)中查看日志与指标。
基于 Collector 的导出(高级)
-
运行自动化脚本(仓库根 package.json 中定义了
telemetryscript):npm run telemetry -- --target=local该脚本会:
- 下载并启动 Jaeger 与 OTEL Collector;
- 为本地遥测配置你的工作区;
- 提供 Jaeger UI(http://localhost:16686);
- 将日志/指标保存到
~/.qwen/tmp/<projectHash>/otel/collector.log; - 退出时停止 Collector(如
Ctrl+C)。
-
运行 Qwen Code 并发送提示。
-
在 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_requestspan)、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 在逐属性限制内时发射。
- GenAI 属性:
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即表示非流式。
- GenAI 属性:
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
- 属性:
源码地图:遥测模块速查
若想深入阅读实现,可沿以下路径展开:
- packages/core/src/telemetry/config.ts:三层优先级配置解析、环境变量校验与
FatalConfigError失败关闭逻辑; - packages/core/src/telemetry/resource-attributes.ts:保留键过滤、
OTEL_RESOURCE_ATTRIBUTES解析与畸形容错; - packages/core/src/telemetry/otlp-urls.ts:HTTP OTLP 逐信号路径拼接;
- packages/core/src/telemetry/sdk.ts:SDK 懒加载初始化、诊断日志路由、优雅关闭与指标强刷;
- packages/core/src/telemetry/constants.ts:全部事件名、Span 名、工具失败词汇表与敏感属性长度常量;
- packages/core/src/telemetry/metrics.ts 与 packages/core/src/telemetry/daemon-metrics.ts:指标与 daemon 指标注册;
- 对应测试位于 packages/core/src/telemetry 下的
config.test.ts、resource-attributes.test.ts、metrics.test.ts、daemon-metrics.test.ts、sdk.test.ts等文件。
结语
Qwen Code 的遥测系统在 OpenTelemetry 之上提供了从配置到导出的完整链路:三层优先级配置让 settings、环境变量与 CLI 标志各司其职;资源属性与基数控制保证了多租户、大规模场景下后端不爆炸;敏感 Span 属性开关配合大小上限兼顾深度诊断与数据安全;入站/出站关联打通了 daemon、子进程与第三方 LLM 提供方之间的分布式链路。对于想在企业内落地 AI Agent 治理、成本核算与性能监控的团队,建议从文件输出模式起步验证数据契约,再逐步切换到阿里云 ARMS 或自建 OTLP Collector,并遵循本文梳理的事件、指标与 Span 定义建立自己的查询面板与告警规则。