qwen-code Workflow 级 Trace Span 缺口分析用双 ALS 父级解析构建 Agent 执行轨迹树【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code本文以 qwen-code 的设计文档《Workflow 级 Span 粒度不足分析》为主线剖析一个 AI coding agent 在 OpenTelemetry 接入中有 tracing 主干、却没有 workflow 阶段边界的典型困境审批等待、hook、subagent 等阶段如何编码成 trace 树中的独立节点。读完本文你将掌握基于 AsyncLocalStorageALS的 span 父子挂载模型、五种 workflow span 缺口及其修复方案并能对照当前仓库源码验证这些建议的实际落地方式。1. 背景从有 tracing 主干到编码 workflow 阶段边界该分析文档基于 2026-05-13 对 qwen-code origin/main 的复核。当时项目已具备 tracing 基础设施各组件分布如下组件位置说明Span 类型定义session-tracing.tsinteraction、llm_request、tool、tool.executionTracer 工具tracer.tssession root context、withSpan、startSpanWithContext交互入口client.ts顶层交互显式启动interactionspan生命周期管理—AsyncLocalStorage WeakRef TTL cleanup当时的 runtime 中稳定接入的主要是两类 generic spanapi.generateContent/api.generateContentStreamtool.toolName文档的核心结论是已进入有 tracing 主干阶段但尚未把 agent workflow 的阶段边界完整编码进 trace 树。作为对照文档引用了外部项目 claude-code 在src/utils/telemetry/sessionTracing.ts中已实现的六类 spaninteraction、llm_request、tool、tool.blocked_on_user、tool.execution、hook此引用来自原文档的外部对比非本仓库文件。2. 五大缺口workflow 阶段在哪里隐形缺失 span / 机制影响permission_wait/blocked_on_userspan无法区分审批等待 vs 工具执行耗时hookspanhook 耗时被折叠进 tool span定位边界不清subagentroot spansubagent 内部 llm/tool 调用无法形成 trace 子树tool.execution真实接线helper 已定义但主链路未调用稳定的 parent-child wiringspans 多为 session root 下的 sibling 而非层级树2.1 用户审批等待不在 trace 中工具调用等待审批时状态迁移路径为awaiting_approval→scheduled→ 执行。等待用户确认只是状态迁移不是 trace 节点trace 上看不到审批等待耗时工具慢时无法区分是卡在等用户还是工具本身执行慢。2.2 Hook 有事件记录但没有独立 spanPre/Post hook 执行后产出HookCallEvent走logHookCall()记录日志但不建立独立 OTel span。后果是hook 变慢时表现为外层 tool span 变慢hook 失败时表现为tool 失败trace 无法回答时间花在 hook 还是 tool.execution 上。2.3 Subagent 是 log/metric 而非 trace subtreesubagent 启动/完成时记录SubagentExecutionEvent事件名定义见 constants.ts并进入 log/metric但没有形成显式 span 子树。能统计哪个 subagent 跑过但不能顺着 trace 看这个 subagent 触发了哪些 llm/tool 调用并发 subagent 场景下因果链不清。2.4 tool.execution helper 已定义但未接入主链路复核时session-tracing.ts中已有startToolExecutionSpan()/endToolExecutionSpan()但非测试代码中未见调用点。当时的实际 trace 树与理想 trace 树对比如下实际session-root interaction api.generateContent tool.Bash subagent_execution (log/metric) hook_call (event/QwenLogger)理想interaction llm_request tool tool.blocked_on_user hook(pre) tool.execution hook(post) subagent interaction llm_request tool2.5 Parent-child wiring 不够稳定interaction span 已存在但很多运行中的 spans 挂在 session root 下作为 sibling而不是 interaction 的子节点。调用树偏平、节点间因果关系不直观从一个用户轮次追到内部 llm/tool/hook/subagent 的体验不连续。在 Jaeger / Tempo / ARMS 等后端上这样的树比层级清晰的实现更难读。3. 根因剖析两套断裂的 span 创建路径这是文档指出的当前最关键的架构问题层文件用法parent 解析session-tracing 层session-tracing.tsstartInteractionSpan/startLLMRequestSpan/startToolSpan/startToolExecutionSpan显式从interactionContextALS 取 parenttracer 层tracer.tswithSpan/startSpanWithContext从context.active()取 parentfallback 到 session rootruntime 实际调用情况复核时点startInteractionSpan→已接入client.ts写入interactionContextALSstartLLMRequestSpan/endLLMRequestSpan→未接入runtime 用的是withSpan(api.generateContent, ...)在loggingContentGenerator.tsstartToolSpan/endToolSpan→未接入runtime 用的是withSpan(tool.${name}, ...)在coreToolScheduler.tsstartToolExecutionSpan/endToolExecutionSpan→未接入。从源码看withSpan的父级解析函数getParentContext()只返回context.active()tracer.ts它完全不读取interactionContextALS找不到活跃 span 时回退到 session root context。因此 interaction span 与 LLM/tool spans 变成了 session root 下的平级 sibling而不是 parent-child 树session-root ├── interaction (来自 session-tracing, 写入了 interactionContext ALS) ├── api.generateContent (来自 withSpan, 不读 interactionContext → 挂到 session root) ├── tool.Bash (来自 withSpan, 同上) └── tool.Read (来自 withSpan, 同上)而参照实现 claude-code 中只有一套 span 创建路径sessionTracing.ts所有 span 都走同一套 ALS → OTel context 转换逻辑所以树是完整的。4. 参照模型claude-code 的双 ALS span 管理文档对 claude-code 源码做了深度对比其 tracing 架构可概括为interactionContext (ALS) toolContext (ALS) │ │ ▼ ▼ ┌─────────────────────┐ ┌─────────────────────┐ │ interaction span │ │ tool span │ │ (session root) │ │ (child of intxn) │ └─────────────────────┘ └─────────────────────┘ ▲ parent of ▲ parent of │ │ ┌───────┴───────┐ ┌──────────┼──────────┐ │ │ │ │ │ llm_request tool blocked execution hook _on_user核心机制机制实现双 ALSinteractionContext存当前 interaction spantoolContext存当前 tool spanparent 解析每种 span 类型硬编码从哪个 ALS 取 parentllm_request/tool取interactionContextblocked_on_user/execution/hook取toolContexthook有 fallback 到interactionContext生命周期enterWith 注入 → span 运行 → enterWith(undefined) 清除查找 span非 ALS 存储的 span如 blocked_on_user通过activeSpansMap 按span.type反查内存管理ALS 持有的 span 用 WeakRef非 ALS 持有的 span 用 strongRef 防 GCTTL 30min 自动清理tool span 完整生命周期toolExecution.tsstartToolSpan(name, attrs) // → toolContext.enterWith(spanCtx) startToolBlockedOnUserSpan() // → parent toolContext.getStore() [permission resolution / user prompt] endToolBlockedOnUserSpan(decision, source) startToolExecutionSpan() // → parent toolContext.getStore() [tool.call()] endToolExecutionSpan({ success }) endToolSpan(result) // → toolContext.enterWith(undefined)hook spanhooks.tsstartHookSpan(event, name, count, defs) // → parent toolContext ?? interactionContext [parallel hook execution] endHookSpan(span, { success, blocking, ... })5. 逐项复用方案5.1 双 ALS 显式 parent 解析核心修复维度claude-codeqwen-code复核时ALS 数量2interactionContexttoolContext1interactionContext无toolContextparent 解析每种 span 类型显式指定从哪个 ALS 取 parentwithSpan统一走context.active()context 注入trace.setSpan(otelContext.active(), parentCtx.span)withSpan内部由startActiveSpan隐式注入qwen-code 的session-tracing.ts当时已经实现了与 claude-code几乎相同的 parent 解析模式// qwen-code session-tracing.ts (已有但未用) export function startLLMRequestSpan(model, promptId): Span { const parentCtx interactionContext.getStore(); const ctx parentCtx ? trace.setSpan(otelContext.active(), parentCtx.span) : otelContext.active(); // ... }核心修复路径废弃 runtime 中的withSpan(api.*)/withSpan(tool.*)调用改为调用 session-tracing 的 typed helpers。不需要重写 session-tracing 层——它的 API 已经就绪。需要新增的只有增加toolContextALS仿 claude-code增加blocked_on_user和hookspan 类型及 helper 函数。5.2 tool.blocked_on_user适配审批流差异维度claude-codeqwen-code审批位置在toolExecution.ts内tool span 内部在coreToolScheduler._schedule()内tool span 之前审批模式同步等待resolveHookPermissionDecision()状态机驱动validating→awaiting_approval→scheduled→executingspan 覆盖范围tool span 包含 blocked executiontool spanwithSpan只包含 execution从executeSingleToolCall开始关键差异qwen-code 的executeSingleToolCall入口检查toolCall.status ! scheduled才继续——调用到这里时审批已经完成tool span 的withSpan包不住审批等待。文档给出两种适配方案方案 A — 前移 tool span 起点推荐将startToolSpan调用从executeSingleToolCall移到_schedule中审批检查之前使 tool span 覆盖完整生命周期。在进入awaiting_approval状态时startToolBlockedOnUserSpan在审批完成scheduled时endToolBlockedOnUserSpan_schedule(): startToolSpan(name) // ← 新增 startToolBlockedOnUserSpan() // ← 新增进入 awaiting_approval 时 [状态机等待] endToolBlockedOnUserSpan(decision) // ← 新增进入 scheduled 时 executeSingleToolCall(): startToolExecutionSpan() // ← 接入已有 helper [hook execute] endToolExecutionSpan() endToolSpan() // ← 需要在 finally 中方案 B — 保持 tool span 位置不变单独追踪审批在_schedule中独立创建approval_waitspan不作为 tool 的 child挂到 interaction 下。好处是改动更小坏处是与参照模型不一致、trace 树可读性差。建议采用方案 A原因与参照实现的 trace 树结构一致trace 上一个 tool 节点就能看到等了多久 执行了多久状态机驱动的特性只影响 span start/end 的触发时机不影响 parent-child 建模。5.3 hook span可直接复用维度claude-codeqwen-codehook 执行入口executeHooks()inhooks.tsfirePreToolUseHook/firePostToolUseHookviahookEventHandler.ts现有记录方式OTel span Perfetto spanHookCallEvent→QwenLogger无 OTelparenttoolContext ?? interactionContext—复用方案在session-tracing.ts新增startHookSpan/endHookSpanparent toolContext ?? interactionContext在coreToolScheduler.ts的executeSingleToolCall中 pre/post hook 调用前后分别 start/end hook span保留现有logHookCall事件记录两套并行不互斥。改动量低不影响现有 hook 逻辑。5.4 tool.execution已有 helper只需接线startToolExecutionSpan()/endToolExecutionSpan()已经完整实现只需在executeSingleToolCall中调用// coreToolScheduler.ts executeSingleToolCall 内部 const toolSpan startToolSpan(toolName, attrs); // ... hook pre ... const execSpan startToolExecutionSpan(toolSpan); try { // ... invocation.execute() ... endToolExecutionSpan(execSpan, { success: true }); } catch (e) { endToolExecutionSpan(execSpan, { success: false, error: e.message }); } // ... hook post ... endToolSpan(toolSpan);风格差异说明qwen-code 的startToolExecutionSpan原设计接收显式parentToolSpan参数而参照实现从toolContextALS 隐式获取。引入toolContextALS 后可统一为隐式获取。5.5 subagent trace tree不建议直接复用维度claude-codeqwen-codeOTel trace 传播无— subagent 的 interaction 是新 root无— subagent 无显式 trace 传播身份关联Perfetto metadataagent process/threadteammateContextStorageALSsubagentNameContextALS SubagentExecutionEvent并发隔离OTel ALS 有泄漏风险enterWith是进程级并发 subagent 会互覆盖同样的风险claude-code 在 subagent OTel tracing 上自己也没解决好interactionContext.enterWith()是进程级的并发 subagent 会覆盖彼此的 ALS 值真正的 agent 层级树只存在于 Perfetto一个 feature-flagged 的内部系统不在 OTel 中。因此建议短期沿用现有的subagentNameContext 事件日志方案中期在 subagent 启动时创建一个subagentspanparent 当前 toolContext并用context.with()而非enterWith()来隔离并发 subagent 的 OTel context。这是需要独立设计的工作项不建议直接照搬。5.6 LLM request span路径明确复核时点在loggingContentGenerator.ts中用withSpan(api.generateContent, ...)和startSpanWithContext(api.generateContentStream, ...)改为调用startLLMRequestSpan/endLLMRequestSpansession-tracing 层已有实现即可。streaming 场景需注意startLLMRequestSpan返回Span对象需要手动传入endLLMRequestSpan(span, metadata)终结——这与startSpanWithContext的手动管理模式兼容。5.7 复用总结与实施顺序改造项可复用程度改动量优先级统一 span 创建路径废弃 runtimewithSpan用 session-tracing helpers核心修复— 解决 parent-child 断裂中约 5 个调用点P0新增toolContextALS直接照搬参照模式低session-tracing.ts 内部P0tool.blocked_on_user span方案 A 需适配状态机中_scheduleexecuteSingleToolCall协调P1tool.execution 接线helper 已有只需调用低executeSingleToolCall内 3 行P1hook span新增 helper 调用点低P1LLM request span 切换替换 withSpan 为 typed helper低2 个调用点P1subagent trace tree不建议直接复用— 需独立设计高P2Phase 1 — 修复 trace 树结构 (P0) ├── 1a. session-tracing.ts 新增 toolContext ALS blocked_on_user / hook span helpers ├── 1b. loggingContentGenerator.ts: withSpan → startLLMRequestSpan/endLLMRequestSpan └── 1c. coreToolScheduler.ts: withSpan → startToolSpan/endToolSpan Phase 2 — 补齐 workflow span (P1) ├── 2a. coreToolScheduler._schedule: blocked_on_user span 接入 ├── 2b. coreToolScheduler.executeSingleToolCall: tool.execution span 接入 └── 2c. hook pre/post 调用处: hook span 接入 Phase 3 — Subagent trace tree (P2) ├── 3a. 设计 context.with() 隔离方案替代 enterWith ├── 3b. subagent 启动时创建 subagent root span └── 3c. 并发 subagent 场景验证6. 当前仓库源码验证缺口如何被逐一修复设计文档是 2026-05 的快照而当前仓库源码显示上述修复项已基本落地源码注释中引用了 issue #3731 的 Phase 2/3 等推进标记。本节以当前源码为证据说明每项建议的实际实现形态。6.1 Span 词汇表七类 workflow span 全部成为一等公民constants.ts 定义了完整的 span 名常量常量span 名语义SPAN_INTERACTIONqwen-code.interaction一次用户轮次trace rootSPAN_LLM_REQUESTqwen-code.llm_request单次 LLM 请求SPAN_TOOLqwen-code.tool工具调用完整生命周期含审批等待SPAN_TOOL_EXECUTIONqwen-code.tool.execution工具实际执行阶段SPAN_TOOL_BLOCKED_ON_USERqwen-code.tool.blocked_on_userawaiting_approval等待用户的时间SPAN_HOOKqwen-code.hook单个 hook 触发点SPAN_SUBAGENTqwen-code.subagent单次 subagent 调用同时 constants.ts 维护了tool.failure_kind词汇表cancelled、pre_hook_blocked、invocation_guard_denied、timeout、plan_mode_blocked等注释明确要求写入点与文档不能漂移——即 span 语义在 coreToolScheduler、session-tracing 与文档三方共享同一常量源。6.2 双 ALS实为三 ALS与 parent 优先级链session-tracing.ts 中现有三个 AsyncLocalStorageconst interactionContext new AsyncLocalStorageSpanContext | undefined(); const toolContext new AsyncLocalStorageSpanContext | undefined(); // 注释子 span 创建时优先读取 subagentContext // 否则前台 subagent 的子 span 会被 re-parent 回外层 interaction const subagentContext new AsyncLocalStorageSpanContext | undefined();startLLMRequestSpanWithContext与startToolSpan的 parent 解析采用统一优先级链session-tracing.tsconst parentCtx subagentContext.getStore() ?? toolContext.getStore() ?? interactionParentCtx; const ctx resolveGenAiParentContext(parentCtx);这正是文档 5.1 节双 ALS 显式 parent 解析建议的实现并额外增加了subagentContext一层解决了subagent 内部 LLM span 逃逸回外层 interaction的问题。值得注意的是resolveGenAiParentContext的防御逻辑session-tracing.ts当没有任何 ALS 属主时强制返回ROOT_CONTEXT防止错误 prompt 的 span 被错误地挂到活跃 interaction 之下。6.3 方案 A 落地tool span 前移到 validating 阶段文档推荐的方案 A 在 coreToolScheduler.ts 中按注释原文实现// Open the tool span as soon as the call is validated. This covers // validating → awaiting_approval → executing in one span (#3731 // Phase 2). Every cancel/error path below — and the existing // success path in executeSingleToolCall — must call // finalizeToolSpan(callId, ...) to avoid leaking spans. const toolSpan startToolSpan(canonicalName, { tool.call_id: reqInfo.callId, ... }, ...);即 tool span 从validating状态就打开一个 span 覆盖validating → awaiting_approval → executing完整生命周期span 句柄存入this.toolSpansMap 以便跨状态机阶段终结。审批等待阶段则显式挂 blocked_on_user 子 spancoreToolScheduler.tsthis.setStatusInternal(callId, awaiting_approval, confirmationDetails); // blocked_on_user span as a child of the tool span const blockedSpan startToolBlockedOnUserSpan(toolSpan, { tool_name: canonicalName, call_id: callId, });startToolBlockedOnUserSpan的父级通过显式toolSpan参数解析session-tracing.ts注释明确说明原因该 span 启动于工具主体进入runInToolSpanContext之前此时toolContext.getStore()为空同时显式传 span 对象也规避了参照实现中按 type 反查最后一个 span在并发下的竞态问题。endToolBlockedOnUserSpan记录decisionproceed_once/proceed_always/cancel/aborted/auto_approved/error见 session-tracing.ts与sourcecli/ide/hook/auto/system两个规范属性且 span 状态保持 UNSET——等用户既非 OK 也非 ERROR决策属性才是规范信号。6.4 tool.execution 与 hook span 接线tool.executioncoreToolScheduler.ts 与 #L5305 两处startToolExecutionSpan({ toolName, callId })对应文档 5.4 节只需 3 行接线的预测。helper 内部从toolContext.getStore()取父级session-tracing.ts在runInToolSpanContext外调用时会打 warning 并回退到活跃 OTel span。hook spancoreToolScheduler.ts 中startHookSpan(opts)与endHookSpan(hookSpan, endMeta)成对出现。当前HookEvent类型比文档复核时更丰富覆盖PreToolUse/PostToolUse/PostToolUseFailure/PostToolBatchsession-tracing.tsstartHookSpan的 parent 优先级为toolContext → subagentContext → interactionContextsession-tracing.ts在 subagent 内部、tool 之外触发的 hook 也能正确挂到 subagent 下。并发安全runInToolSpanContextsession-tracing.ts刻意用toolContext.run()otelContext.with()而非enterWith()把上下文作用域限定在单个异步调用树内——这直接回应了文档 5.5 节对进程级enterWith在并发下互相覆盖的担忧。6.5 LLM request span 切换到 typed helperloggingContentGenerator.ts 与非流式/流式路径#L563均已改为startLLMRequestSpanWithContext/endLLMRequestSpan测试文件 loggingContentGenerator.test.ts 对 token 计数、缓存命中、重试上下文attempt/requestSetupMs/retryTotalDelayMs、流空闲超时等终结路径均有断言。endLLMRequestSpan除写入gen_ai.usage.*、ttft_ms、finish_reason等属性外还派生sampling_ms与output_tokens_per_second并按 Phase 4c 记录分阶段直方图session-tracing.ts。6.6 Subagent trace treePhase 3 的独立设计文档 5.5 节建议独立设计、用context.with()隔离并发当前实现源码注释标记#3731 Phase 3给出了具体答案startSubagentSpansession-tracing.ts区分foreground/fork/background三种调用形态foreground作为当前活跃 span通常 AGENT tool span的子节点继承 traceIdfork/background则创建linked-root span——root: true强制新 traceId同时用 OTelLink指向发起方 span注释引用了 OTel 规范对长耗时异步操作使用 Link 的建议理由正是 fire-and-forget subagent 运行数分钟到数小时若挂在父 trace 下会超出多个后端的 trace 容量上限。runInSubagentSpanContextsession-tracing.ts是并发隔离的关键它用subagentContext.run()toolContext.run(undefined, ...)otelContext.with()组合包裹 subagent 主体注释明确说明会主动清空toolContext——否则 subagent 主体内、首个内部 tool 调用之前触发的 hook如 SubagentStart会错误地挂到外层 AGENT tool span 上。全程没有任何enterWith与文档用context.with()替代enterWith()的建议一致。记忆管理上fork/background这类可能运行数小时的调用获得 4 小时长 TTLLONG_TTL_SUBAGENT_KINDSsession-tracing.ts其余 span 默认 30 分钟为tool.blocked_on_user的用户思考时间选取。注释坦陈一个已知限制长 TTL 只作用于 subagent span 本身其内部子 span 仍用 30 分钟默认值长时间后台 agent 的 trace 可能出现前段子 span 被清扫的空洞留作后续工作项。6.7 内存与生命周期管理文档现状表中提到的 AsyncLocalStorage WeakRef TTL cleanup 在当前源码中完整可见activeSpansWeakRef 表与strongSpans防 GC 的强引用表双表管理session-tracing.tssweepStaleSpans每 60 秒巡检一次对被 TTL 清扫的 span 打上qwen-code.span.ttl_expired哨兵属性并按类型补规范属性如 blocked_on_user 补decision: aborted、subagent 补terminate_reason: ttl_swept使后端能把被安全网回收与主动结束但未设状态区分开session-tracing.ts。所有 span 的文本属性经truncateSpanError截断默认 1024 字符、防孤立代理项、剥离 ANSI、脱敏 URL 凭据session-tracing.ts避免超大字段导致后端丢弃整个 span。6.8 修复后的 trace 树形态从当前源码结构看文档理想 trace 树已达成并略有演化每个 interaction 现在是独立的 trace rootstartInteractionSpan显式传入ROOT_CONTEXTsession-tracing.ts旧的 session root 机制已标记deprecated见 tracer.ts跨轮次关联改由session.idspan 属性完成。这样单条 trace 保持有界、可在 ARMS / Jaeger 中正常渲染qwen-code.interaction (trace root) qwen-code.llm_request qwen-code.tool (Bash) qwen-code.tool.blocked_on_user (decision, source, duration_ms) qwen-code.hook (PreToolUse) qwen-code.tool.execution qwen-code.hook (PostToolUse) qwen-code.tool (AGENT) qwen-code.subagent (foreground: 子节点 / fork|background: linked root) qwen-code.llm_request qwen-code.tool qwen-code.tool.execution与文档理想的差异在于subagent 下不再嵌套一层新的interaction而是 subagent span 直接承载内部的 llm_request / tool / hook 子树——这与startSubagentSpan的设计注释Hosts the LLM/tool/hook subtree emitted by the subagent一致语义上等价且更简洁。7. 小结这份设计文档的价值《Workflow 级 Span 粒度不足分析》展示了一种可复用的排障方法论先盘点再补缺口——用组件 × 位置 × 说明表格固化现状基线再列出缺失项 × 影响对照表让每个缺口都有可感知的排障代价如无法区分审批等待 vs 工具执行耗时定位到架构级根因——问题不在个别 helper 缺失而在两套断裂的 span 创建路径导致 parent 解析分叉对照外部实现做逐项复用评估——对每项机制标注可复用程度 / 改动量 / 优先级并诚实标注双方都不完整、不建议照搬的部分subagent tree给出独立设计路线修复方案可对照源码验收——从当前仓库看typed helper 统一创建路径、toolContextALS、方案 A 的前移 tool span、hook span 接线、context.with()化的 subagent 隔离均已落地文档中的 P0/P1/P2 路线与源码注释中的 Phase 标记一一对应。对于任何构建 agent 式产品的团队这套span 词汇表 显式 parent 解析 按阶段建模的思路都能直接借鉴trace 的价值不在于 span 数量而在于能否回答这轮慢在等用户、hook还是 tool 真执行这类排障问题。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
qwen-code Workflow 级 Trace Span 缺口分析用双 ALS 父级解析构建 Agent 执行轨迹树【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code本文以 qwen-code 的设计文档《Workflow 级 Span 粒度不足分析》为主线剖析一个 AI coding agent 在 OpenTelemetry 接入中有 tracing 主干、却没有 workflow 阶段边界的典型困境审批等待、hook、subagent 等阶段如何编码成 trace 树中的独立节点。读完本文你将掌握基于 AsyncLocalStorageALS的 span 父子挂载模型、五种 workflow span 缺口及其修复方案并能对照当前仓库源码验证这些建议的实际落地方式。1. 背景从有 tracing 主干到编码 workflow 阶段边界该分析文档基于 2026-05-13 对 qwen-code origin/main 的复核。当时项目已具备 tracing 基础设施各组件分布如下组件位置说明Span 类型定义session-tracing.tsinteraction、llm_request、tool、tool.executionTracer 工具tracer.tssession root context、withSpan、startSpanWithContext交互入口client.ts顶层交互显式启动interactionspan生命周期管理—AsyncLocalStorage WeakRef TTL cleanup当时的 runtime 中稳定接入的主要是两类 generic spanapi.generateContent/api.generateContentStreamtool.toolName文档的核心结论是已进入有 tracing 主干阶段但尚未把 agent workflow 的阶段边界完整编码进 trace 树。作为对照文档引用了外部项目 claude-code 在src/utils/telemetry/sessionTracing.ts中已实现的六类 spaninteraction、llm_request、tool、tool.blocked_on_user、tool.execution、hook此引用来自原文档的外部对比非本仓库文件。2. 五大缺口workflow 阶段在哪里隐形缺失 span / 机制影响permission_wait/blocked_on_userspan无法区分审批等待 vs 工具执行耗时hookspanhook 耗时被折叠进 tool span定位边界不清subagentroot spansubagent 内部 llm/tool 调用无法形成 trace 子树tool.execution真实接线helper 已定义但主链路未调用稳定的 parent-child wiringspans 多为 session root 下的 sibling 而非层级树2.1 用户审批等待不在 trace 中工具调用等待审批时状态迁移路径为awaiting_approval→scheduled→ 执行。等待用户确认只是状态迁移不是 trace 节点trace 上看不到审批等待耗时工具慢时无法区分是卡在等用户还是工具本身执行慢。2.2 Hook 有事件记录但没有独立 spanPre/Post hook 执行后产出HookCallEvent走logHookCall()记录日志但不建立独立 OTel span。后果是hook 变慢时表现为外层 tool span 变慢hook 失败时表现为tool 失败trace 无法回答时间花在 hook 还是 tool.execution 上。2.3 Subagent 是 log/metric 而非 trace subtreesubagent 启动/完成时记录SubagentExecutionEvent事件名定义见 constants.ts并进入 log/metric但没有形成显式 span 子树。能统计哪个 subagent 跑过但不能顺着 trace 看这个 subagent 触发了哪些 llm/tool 调用并发 subagent 场景下因果链不清。2.4 tool.execution helper 已定义但未接入主链路复核时session-tracing.ts中已有startToolExecutionSpan()/endToolExecutionSpan()但非测试代码中未见调用点。当时的实际 trace 树与理想 trace 树对比如下实际session-root interaction api.generateContent tool.Bash subagent_execution (log/metric) hook_call (event/QwenLogger)理想interaction llm_request tool tool.blocked_on_user hook(pre) tool.execution hook(post) subagent interaction llm_request tool2.5 Parent-child wiring 不够稳定interaction span 已存在但很多运行中的 spans 挂在 session root 下作为 sibling而不是 interaction 的子节点。调用树偏平、节点间因果关系不直观从一个用户轮次追到内部 llm/tool/hook/subagent 的体验不连续。在 Jaeger / Tempo / ARMS 等后端上这样的树比层级清晰的实现更难读。3. 根因剖析两套断裂的 span 创建路径这是文档指出的当前最关键的架构问题层文件用法parent 解析session-tracing 层session-tracing.tsstartInteractionSpan/startLLMRequestSpan/startToolSpan/startToolExecutionSpan显式从interactionContextALS 取 parenttracer 层tracer.tswithSpan/startSpanWithContext从context.active()取 parentfallback 到 session rootruntime 实际调用情况复核时点startInteractionSpan→已接入client.ts写入interactionContextALSstartLLMRequestSpan/endLLMRequestSpan→未接入runtime 用的是withSpan(api.generateContent, ...)在loggingContentGenerator.tsstartToolSpan/endToolSpan→未接入runtime 用的是withSpan(tool.${name}, ...)在coreToolScheduler.tsstartToolExecutionSpan/endToolExecutionSpan→未接入。从源码看withSpan的父级解析函数getParentContext()只返回context.active()tracer.ts它完全不读取interactionContextALS找不到活跃 span 时回退到 session root context。因此 interaction span 与 LLM/tool spans 变成了 session root 下的平级 sibling而不是 parent-child 树session-root ├── interaction (来自 session-tracing, 写入了 interactionContext ALS) ├── api.generateContent (来自 withSpan, 不读 interactionContext → 挂到 session root) ├── tool.Bash (来自 withSpan, 同上) └── tool.Read (来自 withSpan, 同上)而参照实现 claude-code 中只有一套 span 创建路径sessionTracing.ts所有 span 都走同一套 ALS → OTel context 转换逻辑所以树是完整的。4. 参照模型claude-code 的双 ALS span 管理文档对 claude-code 源码做了深度对比其 tracing 架构可概括为interactionContext (ALS) toolContext (ALS) │ │ ▼ ▼ ┌─────────────────────┐ ┌─────────────────────┐ │ interaction span │ │ tool span │ │ (session root) │ │ (child of intxn) │ └─────────────────────┘ └─────────────────────┘ ▲ parent of ▲ parent of │ │ ┌───────┴───────┐ ┌──────────┼──────────┐ │ │ │ │ │ llm_request tool blocked execution hook _on_user核心机制机制实现双 ALSinteractionContext存当前 interaction spantoolContext存当前 tool spanparent 解析每种 span 类型硬编码从哪个 ALS 取 parentllm_request/tool取interactionContextblocked_on_user/execution/hook取toolContexthook有 fallback 到interactionContext生命周期enterWith 注入 → span 运行 → enterWith(undefined) 清除查找 span非 ALS 存储的 span如 blocked_on_user通过activeSpansMap 按span.type反查内存管理ALS 持有的 span 用 WeakRef非 ALS 持有的 span 用 strongRef 防 GCTTL 30min 自动清理tool span 完整生命周期toolExecution.tsstartToolSpan(name, attrs) // → toolContext.enterWith(spanCtx) startToolBlockedOnUserSpan() // → parent toolContext.getStore() [permission resolution / user prompt] endToolBlockedOnUserSpan(decision, source) startToolExecutionSpan() // → parent toolContext.getStore() [tool.call()] endToolExecutionSpan({ success }) endToolSpan(result) // → toolContext.enterWith(undefined)hook spanhooks.tsstartHookSpan(event, name, count, defs) // → parent toolContext ?? interactionContext [parallel hook execution] endHookSpan(span, { success, blocking, ... })5. 逐项复用方案5.1 双 ALS 显式 parent 解析核心修复维度claude-codeqwen-code复核时ALS 数量2interactionContexttoolContext1interactionContext无toolContextparent 解析每种 span 类型显式指定从哪个 ALS 取 parentwithSpan统一走context.active()context 注入trace.setSpan(otelContext.active(), parentCtx.span)withSpan内部由startActiveSpan隐式注入qwen-code 的session-tracing.ts当时已经实现了与 claude-code几乎相同的 parent 解析模式// qwen-code session-tracing.ts (已有但未用) export function startLLMRequestSpan(model, promptId): Span { const parentCtx interactionContext.getStore(); const ctx parentCtx ? trace.setSpan(otelContext.active(), parentCtx.span) : otelContext.active(); // ... }核心修复路径废弃 runtime 中的withSpan(api.*)/withSpan(tool.*)调用改为调用 session-tracing 的 typed helpers。不需要重写 session-tracing 层——它的 API 已经就绪。需要新增的只有增加toolContextALS仿 claude-code增加blocked_on_user和hookspan 类型及 helper 函数。5.2 tool.blocked_on_user适配审批流差异维度claude-codeqwen-code审批位置在toolExecution.ts内tool span 内部在coreToolScheduler._schedule()内tool span 之前审批模式同步等待resolveHookPermissionDecision()状态机驱动validating→awaiting_approval→scheduled→executingspan 覆盖范围tool span 包含 blocked executiontool spanwithSpan只包含 execution从executeSingleToolCall开始关键差异qwen-code 的executeSingleToolCall入口检查toolCall.status ! scheduled才继续——调用到这里时审批已经完成tool span 的withSpan包不住审批等待。文档给出两种适配方案方案 A — 前移 tool span 起点推荐将startToolSpan调用从executeSingleToolCall移到_schedule中审批检查之前使 tool span 覆盖完整生命周期。在进入awaiting_approval状态时startToolBlockedOnUserSpan在审批完成scheduled时endToolBlockedOnUserSpan_schedule(): startToolSpan(name) // ← 新增 startToolBlockedOnUserSpan() // ← 新增进入 awaiting_approval 时 [状态机等待] endToolBlockedOnUserSpan(decision) // ← 新增进入 scheduled 时 executeSingleToolCall(): startToolExecutionSpan() // ← 接入已有 helper [hook execute] endToolExecutionSpan() endToolSpan() // ← 需要在 finally 中方案 B — 保持 tool span 位置不变单独追踪审批在_schedule中独立创建approval_waitspan不作为 tool 的 child挂到 interaction 下。好处是改动更小坏处是与参照模型不一致、trace 树可读性差。建议采用方案 A原因与参照实现的 trace 树结构一致trace 上一个 tool 节点就能看到等了多久 执行了多久状态机驱动的特性只影响 span start/end 的触发时机不影响 parent-child 建模。5.3 hook span可直接复用维度claude-codeqwen-codehook 执行入口executeHooks()inhooks.tsfirePreToolUseHook/firePostToolUseHookviahookEventHandler.ts现有记录方式OTel span Perfetto spanHookCallEvent→QwenLogger无 OTelparenttoolContext ?? interactionContext—复用方案在session-tracing.ts新增startHookSpan/endHookSpanparent toolContext ?? interactionContext在coreToolScheduler.ts的executeSingleToolCall中 pre/post hook 调用前后分别 start/end hook span保留现有logHookCall事件记录两套并行不互斥。改动量低不影响现有 hook 逻辑。5.4 tool.execution已有 helper只需接线startToolExecutionSpan()/endToolExecutionSpan()已经完整实现只需在executeSingleToolCall中调用// coreToolScheduler.ts executeSingleToolCall 内部 const toolSpan startToolSpan(toolName, attrs); // ... hook pre ... const execSpan startToolExecutionSpan(toolSpan); try { // ... invocation.execute() ... endToolExecutionSpan(execSpan, { success: true }); } catch (e) { endToolExecutionSpan(execSpan, { success: false, error: e.message }); } // ... hook post ... endToolSpan(toolSpan);风格差异说明qwen-code 的startToolExecutionSpan原设计接收显式parentToolSpan参数而参照实现从toolContextALS 隐式获取。引入toolContextALS 后可统一为隐式获取。5.5 subagent trace tree不建议直接复用维度claude-codeqwen-codeOTel trace 传播无— subagent 的 interaction 是新 root无— subagent 无显式 trace 传播身份关联Perfetto metadataagent process/threadteammateContextStorageALSsubagentNameContextALS SubagentExecutionEvent并发隔离OTel ALS 有泄漏风险enterWith是进程级并发 subagent 会互覆盖同样的风险claude-code 在 subagent OTel tracing 上自己也没解决好interactionContext.enterWith()是进程级的并发 subagent 会覆盖彼此的 ALS 值真正的 agent 层级树只存在于 Perfetto一个 feature-flagged 的内部系统不在 OTel 中。因此建议短期沿用现有的subagentNameContext 事件日志方案中期在 subagent 启动时创建一个subagentspanparent 当前 toolContext并用context.with()而非enterWith()来隔离并发 subagent 的 OTel context。这是需要独立设计的工作项不建议直接照搬。5.6 LLM request span路径明确复核时点在loggingContentGenerator.ts中用withSpan(api.generateContent, ...)和startSpanWithContext(api.generateContentStream, ...)改为调用startLLMRequestSpan/endLLMRequestSpansession-tracing 层已有实现即可。streaming 场景需注意startLLMRequestSpan返回Span对象需要手动传入endLLMRequestSpan(span, metadata)终结——这与startSpanWithContext的手动管理模式兼容。5.7 复用总结与实施顺序改造项可复用程度改动量优先级统一 span 创建路径废弃 runtimewithSpan用 session-tracing helpers核心修复— 解决 parent-child 断裂中约 5 个调用点P0新增toolContextALS直接照搬参照模式低session-tracing.ts 内部P0tool.blocked_on_user span方案 A 需适配状态机中_scheduleexecuteSingleToolCall协调P1tool.execution 接线helper 已有只需调用低executeSingleToolCall内 3 行P1hook span新增 helper 调用点低P1LLM request span 切换替换 withSpan 为 typed helper低2 个调用点P1subagent trace tree不建议直接复用— 需独立设计高P2Phase 1 — 修复 trace 树结构 (P0) ├── 1a. session-tracing.ts 新增 toolContext ALS blocked_on_user / hook span helpers ├── 1b. loggingContentGenerator.ts: withSpan → startLLMRequestSpan/endLLMRequestSpan └── 1c. coreToolScheduler.ts: withSpan → startToolSpan/endToolSpan Phase 2 — 补齐 workflow span (P1) ├── 2a. coreToolScheduler._schedule: blocked_on_user span 接入 ├── 2b. coreToolScheduler.executeSingleToolCall: tool.execution span 接入 └── 2c. hook pre/post 调用处: hook span 接入 Phase 3 — Subagent trace tree (P2) ├── 3a. 设计 context.with() 隔离方案替代 enterWith ├── 3b. subagent 启动时创建 subagent root span └── 3c. 并发 subagent 场景验证6. 当前仓库源码验证缺口如何被逐一修复设计文档是 2026-05 的快照而当前仓库源码显示上述修复项已基本落地源码注释中引用了 issue #3731 的 Phase 2/3 等推进标记。本节以当前源码为证据说明每项建议的实际实现形态。6.1 Span 词汇表七类 workflow span 全部成为一等公民constants.ts 定义了完整的 span 名常量常量span 名语义SPAN_INTERACTIONqwen-code.interaction一次用户轮次trace rootSPAN_LLM_REQUESTqwen-code.llm_request单次 LLM 请求SPAN_TOOLqwen-code.tool工具调用完整生命周期含审批等待SPAN_TOOL_EXECUTIONqwen-code.tool.execution工具实际执行阶段SPAN_TOOL_BLOCKED_ON_USERqwen-code.tool.blocked_on_userawaiting_approval等待用户的时间SPAN_HOOKqwen-code.hook单个 hook 触发点SPAN_SUBAGENTqwen-code.subagent单次 subagent 调用同时 constants.ts 维护了tool.failure_kind词汇表cancelled、pre_hook_blocked、invocation_guard_denied、timeout、plan_mode_blocked等注释明确要求写入点与文档不能漂移——即 span 语义在 coreToolScheduler、session-tracing 与文档三方共享同一常量源。6.2 双 ALS实为三 ALS与 parent 优先级链session-tracing.ts 中现有三个 AsyncLocalStorageconst interactionContext new AsyncLocalStorageSpanContext | undefined(); const toolContext new AsyncLocalStorageSpanContext | undefined(); // 注释子 span 创建时优先读取 subagentContext // 否则前台 subagent 的子 span 会被 re-parent 回外层 interaction const subagentContext new AsyncLocalStorageSpanContext | undefined();startLLMRequestSpanWithContext与startToolSpan的 parent 解析采用统一优先级链session-tracing.tsconst parentCtx subagentContext.getStore() ?? toolContext.getStore() ?? interactionParentCtx; const ctx resolveGenAiParentContext(parentCtx);这正是文档 5.1 节双 ALS 显式 parent 解析建议的实现并额外增加了subagentContext一层解决了subagent 内部 LLM span 逃逸回外层 interaction的问题。值得注意的是resolveGenAiParentContext的防御逻辑session-tracing.ts当没有任何 ALS 属主时强制返回ROOT_CONTEXT防止错误 prompt 的 span 被错误地挂到活跃 interaction 之下。6.3 方案 A 落地tool span 前移到 validating 阶段文档推荐的方案 A 在 coreToolScheduler.ts 中按注释原文实现// Open the tool span as soon as the call is validated. This covers // validating → awaiting_approval → executing in one span (#3731 // Phase 2). Every cancel/error path below — and the existing // success path in executeSingleToolCall — must call // finalizeToolSpan(callId, ...) to avoid leaking spans. const toolSpan startToolSpan(canonicalName, { tool.call_id: reqInfo.callId, ... }, ...);即 tool span 从validating状态就打开一个 span 覆盖validating → awaiting_approval → executing完整生命周期span 句柄存入this.toolSpansMap 以便跨状态机阶段终结。审批等待阶段则显式挂 blocked_on_user 子 spancoreToolScheduler.tsthis.setStatusInternal(callId, awaiting_approval, confirmationDetails); // blocked_on_user span as a child of the tool span const blockedSpan startToolBlockedOnUserSpan(toolSpan, { tool_name: canonicalName, call_id: callId, });startToolBlockedOnUserSpan的父级通过显式toolSpan参数解析session-tracing.ts注释明确说明原因该 span 启动于工具主体进入runInToolSpanContext之前此时toolContext.getStore()为空同时显式传 span 对象也规避了参照实现中按 type 反查最后一个 span在并发下的竞态问题。endToolBlockedOnUserSpan记录decisionproceed_once/proceed_always/cancel/aborted/auto_approved/error见 session-tracing.ts与sourcecli/ide/hook/auto/system两个规范属性且 span 状态保持 UNSET——等用户既非 OK 也非 ERROR决策属性才是规范信号。6.4 tool.execution 与 hook span 接线tool.executioncoreToolScheduler.ts 与 #L5305 两处startToolExecutionSpan({ toolName, callId })对应文档 5.4 节只需 3 行接线的预测。helper 内部从toolContext.getStore()取父级session-tracing.ts在runInToolSpanContext外调用时会打 warning 并回退到活跃 OTel span。hook spancoreToolScheduler.ts 中startHookSpan(opts)与endHookSpan(hookSpan, endMeta)成对出现。当前HookEvent类型比文档复核时更丰富覆盖PreToolUse/PostToolUse/PostToolUseFailure/PostToolBatchsession-tracing.tsstartHookSpan的 parent 优先级为toolContext → subagentContext → interactionContextsession-tracing.ts在 subagent 内部、tool 之外触发的 hook 也能正确挂到 subagent 下。并发安全runInToolSpanContextsession-tracing.ts刻意用toolContext.run()otelContext.with()而非enterWith()把上下文作用域限定在单个异步调用树内——这直接回应了文档 5.5 节对进程级enterWith在并发下互相覆盖的担忧。6.5 LLM request span 切换到 typed helperloggingContentGenerator.ts 与非流式/流式路径#L563均已改为startLLMRequestSpanWithContext/endLLMRequestSpan测试文件 loggingContentGenerator.test.ts 对 token 计数、缓存命中、重试上下文attempt/requestSetupMs/retryTotalDelayMs、流空闲超时等终结路径均有断言。endLLMRequestSpan除写入gen_ai.usage.*、ttft_ms、finish_reason等属性外还派生sampling_ms与output_tokens_per_second并按 Phase 4c 记录分阶段直方图session-tracing.ts。6.6 Subagent trace treePhase 3 的独立设计文档 5.5 节建议独立设计、用context.with()隔离并发当前实现源码注释标记#3731 Phase 3给出了具体答案startSubagentSpansession-tracing.ts区分foreground/fork/background三种调用形态foreground作为当前活跃 span通常 AGENT tool span的子节点继承 traceIdfork/background则创建linked-root span——root: true强制新 traceId同时用 OTelLink指向发起方 span注释引用了 OTel 规范对长耗时异步操作使用 Link 的建议理由正是 fire-and-forget subagent 运行数分钟到数小时若挂在父 trace 下会超出多个后端的 trace 容量上限。runInSubagentSpanContextsession-tracing.ts是并发隔离的关键它用subagentContext.run()toolContext.run(undefined, ...)otelContext.with()组合包裹 subagent 主体注释明确说明会主动清空toolContext——否则 subagent 主体内、首个内部 tool 调用之前触发的 hook如 SubagentStart会错误地挂到外层 AGENT tool span 上。全程没有任何enterWith与文档用context.with()替代enterWith()的建议一致。记忆管理上fork/background这类可能运行数小时的调用获得 4 小时长 TTLLONG_TTL_SUBAGENT_KINDSsession-tracing.ts其余 span 默认 30 分钟为tool.blocked_on_user的用户思考时间选取。注释坦陈一个已知限制长 TTL 只作用于 subagent span 本身其内部子 span 仍用 30 分钟默认值长时间后台 agent 的 trace 可能出现前段子 span 被清扫的空洞留作后续工作项。6.7 内存与生命周期管理文档现状表中提到的 AsyncLocalStorage WeakRef TTL cleanup 在当前源码中完整可见activeSpansWeakRef 表与strongSpans防 GC 的强引用表双表管理session-tracing.tssweepStaleSpans每 60 秒巡检一次对被 TTL 清扫的 span 打上qwen-code.span.ttl_expired哨兵属性并按类型补规范属性如 blocked_on_user 补decision: aborted、subagent 补terminate_reason: ttl_swept使后端能把被安全网回收与主动结束但未设状态区分开session-tracing.ts。所有 span 的文本属性经truncateSpanError截断默认 1024 字符、防孤立代理项、剥离 ANSI、脱敏 URL 凭据session-tracing.ts避免超大字段导致后端丢弃整个 span。6.8 修复后的 trace 树形态从当前源码结构看文档理想 trace 树已达成并略有演化每个 interaction 现在是独立的 trace rootstartInteractionSpan显式传入ROOT_CONTEXTsession-tracing.ts旧的 session root 机制已标记deprecated见 tracer.ts跨轮次关联改由session.idspan 属性完成。这样单条 trace 保持有界、可在 ARMS / Jaeger 中正常渲染qwen-code.interaction (trace root) qwen-code.llm_request qwen-code.tool (Bash) qwen-code.tool.blocked_on_user (decision, source, duration_ms) qwen-code.hook (PreToolUse) qwen-code.tool.execution qwen-code.hook (PostToolUse) qwen-code.tool (AGENT) qwen-code.subagent (foreground: 子节点 / fork|background: linked root) qwen-code.llm_request qwen-code.tool qwen-code.tool.execution与文档理想的差异在于subagent 下不再嵌套一层新的interaction而是 subagent span 直接承载内部的 llm_request / tool / hook 子树——这与startSubagentSpan的设计注释Hosts the LLM/tool/hook subtree emitted by the subagent一致语义上等价且更简洁。7. 小结这份设计文档的价值《Workflow 级 Span 粒度不足分析》展示了一种可复用的排障方法论先盘点再补缺口——用组件 × 位置 × 说明表格固化现状基线再列出缺失项 × 影响对照表让每个缺口都有可感知的排障代价如无法区分审批等待 vs 工具执行耗时定位到架构级根因——问题不在个别 helper 缺失而在两套断裂的 span 创建路径导致 parent 解析分叉对照外部实现做逐项复用评估——对每项机制标注可复用程度 / 改动量 / 优先级并诚实标注双方都不完整、不建议照搬的部分subagent tree给出独立设计路线修复方案可对照源码验收——从当前仓库看typed helper 统一创建路径、toolContextALS、方案 A 的前移 tool span、hook span 接线、context.with()化的 subagent 隔离均已落地文档中的 P0/P1/P2 路线与源码注释中的 Phase 标记一一对应。对于任何构建 agent 式产品的团队这套span 词汇表 显式 parent 解析 按阶段建模的思路都能直接借鉴trace 的价值不在于 span 数量而在于能否回答这轮慢在等用户、hook还是 tool 真执行这类排障问题。【免费下载链接】qwen-codeAn open-source AI coding agent that lives in your terminal.项目地址: https://gitcode.com/GitHub_Trending/qw/qwen-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
