Design da Árvore de Trace de Subagente (P3 Fase 3)

Issue #3731 — Fase 3 do rastreamento hierárquico de sessão. Adiciona um span qwen-code.subagent para que invocações de subagentes tenham uma estrutura de trace isolada e consultável, em vez de se misturarem silenciosamente sob o span pai qwen-code.interaction.

Baseia-se na Fase 1 (#4126), Fase 1.5 (#4302) e Fase 2 (#4321).

Problema

Hoje, toda execução de AgentTool.execute roda sob o span qwen-code.interaction do pai. Três patologias:

1. Subagentes concorrentes se misturam. coreToolScheduler.ts:728 marca AGENT como seguro para concorrência — Promise.all executa até 10 subagentes em paralelo. Seus spans de LLM-request / tool / hook se anexam todos ao único span de interação pai compartilhado, então exploradores de trace não conseguem distinguir “esta requisição LLM pertence ao subagente A” de “esta pertence ao subagente B”.
2. Nenhum span para a própria fronteira do subagente. Existe um LogRecord qwen-code.subagent_execution (emitido de agent-headless.ts:268,329) conectado a um span de mesmo nome via LogToSpanProcessor, mas é um marcador independente, não um pai que aninhe os spans de LLM / tool / hook do subagente abaixo dele.
3. Subagentes fork / background flutuam soltos. Caminhos fire-and-forget (runInForkContext / background) sobrevivem ao AgentTool.execute pai e emitem spans ao longo de múltiplas interações subsequentes do usuário. O span da tool pai já foi encerrado quando esses spans aparecem, então o context.active() do OTel não ajuda — eles se anexam a qualquer interação que estivesse ativa no momento da execução, ou a nenhuma.

Superfície existente (nenhuma alteração)

Fora do escopo (adiado)

• Agregação de uso de token por subagente (gen_ai.usage.* somados em todos os spans LLM dentro de um subagente). Pertence à Fase 4 (decomposição de requisição LLM).
• Migração do LogRecord qwen-code.subagent_execution para o novo span como eventos de span. RUM e métricas estão fortemente acoplados ao LogRecord; adiado para um follow-up que possa renegociar todos os 3 consumidores juntos.
• Rollup automático de custos. Mesma razão — precisa primeiro do uso de token.
• Remoção do marcador concurrent: true da tool AGENT. Concorrência está correta; nós a instrumentamos, não a restringimos.

Referências (evidência de decisão)

Design — seis decisões, cada uma justificada

D1 — Ciclo de vida do span: chamador abre, calado executa dentro de context.with(span, fn)

agent.ts (chamador) constrói o span. O corpo — seja aguardado (runFramed) ou fire-and-forget (runInForkContext / background) — executa dentro de runInSubagentSpanContext(span, fn), que chama otelContext.with(trace.setSpan(active, span), fn).

Onde exatamente em AgentTool.execute o span abre? Abra-o logo ANTES da configuração específica do tipo de invocação (createAgentHeadless / createForkSubagent etc.) — para que o tempo de setup (construção de config, reconstrução de ToolRegistry, fiação de ContextOverride) SEJA incluído na duração de qwen-code.subagent. Operadores rastreando “por que este subagente está lento?” veem o quadro completo. Setup tipicamente << tempo LLM, então isso é livre de ruído.

Alternativa considerada: abrir após o setup, excluindo o tempo de setup. Rejeitada porque o setup do subagente é em si mesmo trabalho atribuível ao subagente — escondê-lo torna a matemática de duração total errada ao somar todos os spans de subagentes.

Por que não apenas no calado: quando o corpo de fork/background realmente executa, o chamador já retornou. O context.active() do OTel então retorna qualquer contexto ambiente que o runtime assíncrono carregue — que para void fire-and-forget após o fim do pai é não confiável. O span pai já foi fechado; reparentalização posterior é errada.

Por que não apenas no chamador: foreground funciona bem assim, mas spans de fork/background precisam continuar emitindo spans-filho (LLM / tool / hook) após AgentTool.execute retornar. Esses spans-filho precisam que context.active() retorne o span do subagente — o que só acontece se o corpo executar explicitamente dentro de context.with(subagentSpan, body).

Ambas as pontas são necessárias. O design é a ponte — chamador cria span + estratégia de traceId de acordo com o tipo de invocação, então entrega via runInSubagentSpanContext.

D2 — traceId híbrido: foreground = span filho, fork/background = novo traceId + Link

Payload do Link:

tracer.startSpan(
  'qwen-code.subagent',
  {
    kind: SpanKind.INTERNAL,
    links: [
      {
        context: invokerSpanContext,
        attributes: { 'qwen-code.link.kind': 'invoker' },
      },
    ],
  } /* contexto explícito = root, não herdando active */,
);

Capacidade de consulta entre traces via id de sessão: gen_ai.conversation.id é definido em todo span de subagente (foreground e root vinculado igualmente), então uma consulta ARMS por session.id retorna tanto o trace da interação pai QUANTO os traces dos subagentes root vinculados. O Link em si aparece na UI do trace pai como “Spawned: subagent X (other trace)” para que a navegação funcione.

Por que não sempre filho: subagente background de 4 horas infla a duração wall-clock do trace pai para 4 horas; o tamanho do trace cresce além dos limites de vários backends (o limite de 25.000 execuções do LangSmith é o mais claramente documentado). Subagentes foreground que o usuário está realmente aguardando não têm esse problema porque estão temporalmente contidos.

Por que não sempre root vinculado: foreground quebra a árvore de trace natural. Um prompt do usuário que executa um subagente Explore síncrono DEVERIA mostrar uma árvore, não dois traces vinculados.

D3 — TTL: ciente do tipo, subagente fork/background = 4h, outros = 30min

session-tracing.ts:124 define SPAN_TTL_MS = 30 * 60 * 1000. A varredura em :144-152 já trata tool.blocked_on_user especialmente para marcar decision: 'aborted' + source: 'system'. Já é ciente do tipo em espírito.

Mudança: introduzir TTL por tipo:

const SPAN_TTL_MS_DEFAULT = 30 * 60 * 1000; // 30min
const SPAN_TTL_MS_LONG = 4 * 60 * 60 * 1000; // 4h
 
function ttlFor(ctx: SpanContext): number {
  if (
    ctx.type === 'subagent' &&
    ctx.attributes['qwen-code.subagent.invocation_kind'] !== 'foreground'
  ) {
    return SPAN_TTL_MS_LONG;
  }
  return SPAN_TTL_MS_DEFAULT;
}

Na expiração do TTL, spans de subagente recebem marcação:

{
  'qwen-code.span.ttl_expired': true,
  'qwen-code.span.duration_ms': age,
  'qwen-code.subagent.status': 'aborted',
  'qwen-code.subagent.terminate_reason': 'ttl_swept',
}

Por que não 30min fixo: subagentes longos legítimos (análise grande de repositório, builds lentos, tarefas profundas de pesquisa) são marcados incorretamente como expirados por TTL. 4h cobre o percentil 99 sem ser tão frouxo que travamentos reais passem despercebidos.

Por que não sem TTL: crash de processo / OOM / kill -9 → span permanece no mapa activeSpans para sempre. A rede de segurança de 30min protege contra isso; subagente fork/background precisa apenas de uma janela maior, não de remoção.

De onde veio 4h: limite superior pragmático para tarefas não triviais de agente (pesquisa profunda longa / análise de codebase grande). Configurável via constante se dados de produção mostrarem que estamos errados.

D4 — Retenção do LogRecord: manter emissão, pular a ponte LogToSpanProcessor

O LogRecord SubagentExecutionEvent tem 3 consumidores downstream (verificado por auditoria do repositório):

Pulo da ponte (a única mudança no LogToSpanProcessor):

// log-to-span-processor.ts — dentro de onEmit, após deriveSpanName
const skipBridge = new Set<string>([
  EVENT_SUBAGENT_EXECUTION, // coberto pelo span nativo qwen-code.subagent
]);
if (skipBridge.has(eventName)) return;

Impacto no consumidor de trace: dashboards que filtram pelo nome do span qwen-code.subagent_execution começarão a retornar zero resultados. Eles devem ser atualizados para qwen-code.subagent. Notar isso nas notas de release.

Por que não deletar o LogRecord: é a entrada para RUM e métricas. Deletá-lo é um refator de 3 sistemas; fora do escopo aqui.

Por que não manter ambos: o trace mostraria dois spans por subagente (qwen-code.subagent + qwen-code.subagent_execution) carregando informações sobrepostas — confuso para operadores lendo traces, volume duplicado de spans.

D5 — Nome do span + atributos: conformidade híbrida com especificação, prefixo do vendor para extensões

Nome do span: qwen-code.subagent (corresponde à convenção da base de código das Fases 1/2: qwen-code.interaction, qwen-code.tool, qwen-code.hook, …).

A especificação OTel GenAI diz que o nome canônico do span é invoke_agent {gen_ai.agent.name} — mas também diz que “sistemas/frameworks GenAI individuais PODEM especificar formatos de nome de span diferentes.” Usamos nosso próprio nome e definimos gen_ai.operation.name='invoke_agent' para que ferramentas cientes da especificação ainda identifiquem o span. Operadores lendo nossa árvore de trace veem nomenclatura consistente qwen-code.*.

Tipo do span: INTERNAL (invocação de subagente intra-processo, conforme especificação).

Conjunto de atributos:

• status === 'completed' → SpanStatus { code: OK }
• status === 'failed' → SpanStatus { code: ERROR, message: truncated(error.message) }
• status === 'cancelled' ou 'aborted' → SpanStatus { code: UNSET } (segue a convenção da Fase 2)

Por que dual-emit em id + name: a spec está em Desenvolvimento (um passo antes do Experimental). OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental existe para opt-in. Os nomes dos atributos da spec podem ser renomeados antes do Stable. Dual-emit é o mesmo padrão que a Fase 2 usou para call_id → tool.call_id; remova a chave do fornecedor quando a spec atingir o Stable.

Por que qwen-code.subagent.* (não qwen.subagent.*): toda chave existente com prefixo do fornecedor em constants.ts usa qwen-code.* (qwen-code.user_prompt, qwen-code.tool_call, etc.). Consistência interna > preferência de nomenclatura OTel, já que operadores consultam ARMS por prefixo.

Cardinalidade: atributos de span não são labels de métricas no OTel; atributos com chave UUID (id, parent_agent_id, invoking_request_id) são seguros na camada de span. Não os promova a labels de métricas depois.

~10-15 atributos por span (dependendo do tipo de invocação, falha, aninhamento). Mesma ordem que qwen-code.tool.

D6 — Campo AgentContext.depth adicionado diretamente

AgentContext (agent-context.ts:32) não é exportado — apenas os helpers (getCurrentAgentId, runWithAgentContext, getRuntimeContentGenerator, runWithRuntimeContentGenerator) são. Zero quebra downstream no TypeScript. Os 6 leitores conhecidos via getCurrentAgentId() só leem agentId; adicionar depth?: number é invisível para eles.

interface AgentContext {
  agentId: string;
  subagentName: string;
  invokingRequestId: string;
  invocationKind: 'spawn' | 'resume';
  isBuiltIn: boolean;
  depth?: number; // NOVO — padrão 0 nos leitores
}

runWithAgentContext já usa spread { ...current, agentId }, então depth sobrevive inalterado nos locais de chamada existentes. Atualize runWithAgentContext para incrementar depth automaticamente internamente — nenhum chamador precisa saber sobre depth:

function runWithAgentContext<T>(agentId: string, fn: () => T): T {
  const parent = agentContextStorage.getStore();
  const next: AgentContext = {
    ...parent,
    agentId,
    depth: (parent?.depth ?? -1) + 1, // incremento automático
  };
  return agentContextStorage.run(next, fn);
}

Subagent de nível superior: sem ALS pai → depth: 0. Aninhado: depth do pai +1.

Um novo accessor mínimo getCurrentAgentDepth(): number retorna agentContextStorage.getStore()?.depth ?? 0 — usado por startSubagentSpan para preencher qwen-code.subagent.depth.

Por que não um ALS separado apenas para telemetria: duplicaria a mesma forma de contexto que já mantemos. Ruim. Reutilize o existente.

API Helper (session-tracing.ts)

// constants.ts
export const SPAN_SUBAGENT = 'qwen-code.subagent';
 
// session-tracing.ts
export interface StartSubagentSpanOptions {
  agentId: string;
  subagentName: string;
  invocationKind: 'foreground' | 'fork' | 'background';
  isBuiltIn: boolean;
  parentAgentId?: string;
  depth: number;
  invokingRequestId?: string;
  sessionId: string;
  modelOverride?: string;
  invokerSpanContext?: SpanContext; // necessário para fork / background (fonte do Link)
}
 
export interface SubagentSpanMetadata {
  status: 'completed' | 'failed' | 'cancelled' | 'aborted';
  terminateReason?: string;
  resultSummaryPresent?: boolean;
  error?: string;
  errorType?: string;
}
 
export function startSubagentSpan(opts: StartSubagentSpanOptions): Span;
export function endSubagentSpan(
  span: Span,
  metadata: SubagentSpanMetadata,
): void;
export function runInSubagentSpanContext<T>(
  span: Span,
  fn: () => Promise<T>,
): Promise<T>;

runInSubagentSpanContext é a primitiva de isolamento:

export function runInSubagentSpanContext<T>(
  span: Span,
  fn: () => Promise<T>,
): Promise<T> {
  const ctx = trace.setSpan(otelContext.active(), span);
  return otelContext.with(ctx, fn);
}

startSubagentSpan internamente ramifica com base em invocationKind:

function startSubagentSpan(opts: StartSubagentSpanOptions): Span {
  const attributes = buildSpanAttributes(opts);
  const tracer = getTracer();
 
  if (opts.invocationKind === 'foreground') {
    // Filho do span ativo atual (span da ferramenta do chamador)
    return tracer.startSpan(SPAN_SUBAGENT, {
      kind: SpanKind.INTERNAL,
      attributes,
    });
  }
 
  // fork / background: raiz linkada
  return tracer.startSpan(SPAN_SUBAGENT, {
    kind: SpanKind.INTERNAL,
    attributes,
    links: opts.invokerSpanContext
      ? [
          {
            context: opts.invokerSpanContext,
            attributes: { 'qwen-code.link.kind': 'invoker' },
          },
        ]
      : undefined,
    root: true, // força novo traceId; ignora contexto ativo como pai
  });
}

Conexão do Ciclo de Vida

Foreground nomeado (o caminho comum)

// agent.ts:~2154
// Pega o frame ALS pai para definir parentAgentId no span. A profundidade do novo filho
// é calculada dentro de runWithAgentContext automaticamente (D6) — a lemos
// via getCurrentAgentDepth() uma vez que estamos DENTRO do frame ALS filho.
// Duas etapas:
const parentAgentId = getCurrentAgentId();  // ANTES de entrar no frame filho
 
// ... chamada runFramed existente entra em runWithAgentContext(hookOpts.agentId, ...) ...
 
// DENTRO de runFramed, podemos ler a profundidade do filho:
//   const depth = getCurrentAgentDepth();
//
// Posicionamento prático: passe `depth` como variável de closure, definida após
// runWithAgentContext surtir efeito — OU calcule como
// `(getCurrentAgentDepth() externo) + 1` do lado do chamador (mais simples).
const depth = getCurrentAgentDepth();  // fora do frame; o filho será este + 1
// (define qwen-code.subagent.depth = depth nos args de startSubagentSpan)
 
const span = startSubagentSpan({
  agentId, subagentName, invocationKind: 'foreground',
  isBuiltIn, parentAgentId, depth, invokingRequestId, sessionId,
  modelOverride,
  // invokerSpanContext omitido — foreground herda naturalmente via context.with
});
let metadata: SubagentSpanMetadata = { status: 'aborted' };
try {
  await runInSubagentSpanContext(span, () =>
    runFramed(() => this.runSubagentWithHooks(...)),
  );
  metadata = { status: 'completed' /* + resultSummaryPresent */ };
} catch (error) {
  metadata = {
    status: signal.aborted ? 'aborted' : 'failed',
    error: error instanceof Error ? error.message : String(error),
    errorType: error?.constructor?.name,
  };
  throw error;
} finally {
  endSubagentSpan(span, metadata);
}

Fork (fire-and-forget)

const invokerSpanContext = trace.getSpan(otelContext.active())?.spanContext();
const span = startSubagentSpan({
  ..., invocationKind: 'fork', invokerSpanContext,
});
void runInForkContext(() =>
  runInSubagentSpanContext(span, async () => {
    let metadata: SubagentSpanMetadata = { status: 'aborted' };
    try {
      await runFramedFork();
      metadata = { status: 'completed' };
    } catch (error) {
      metadata = {
        status: signal.aborted ? 'aborted' : 'failed',
        error: error instanceof Error ? error.message : String(error),
      };
    } finally {
      endSubagentSpan(span, metadata);
    }
  }),
);
// AgentTool.execute retorna FORK_PLACEHOLDER_RESULT imediatamente;
// o span vive por interações subsequentes da sessão pai.

Background

Mesma forma do fork, com invocationKind: 'background' e bgEventEmitter no lugar de eventEmitter. TTL é 4h (igual ao fork — regra de tipo do D3).

Isolamento concorrente — a garantia principal

Três invocações concorrentes de subagent a partir de um prompt de usuário (o modelo emite 3 blocos AGENT tool_use → coreToolScheduler.runConcurrently executa 3 executeSingleToolCall em paralelo; cada uma abre seu próprio span qwen-code.tool conforme Fase 2):

qwen-code.interaction                         [traceId=T0]
├─ qwen-code.tool [chamada de agente #A]
│  └─ qwen-code.subagent (A, foreground)     [traceId=T0, filho]
│     ├─ qwen-code.llm_request
│     └─ qwen-code.tool [...]
│        └─ qwen-code.tool.execution
├─ qwen-code.tool [chamada de agente #B]
│  └─ qwen-code.subagent (B, foreground)     [traceId=T0, filho]
│     └─ qwen-code.llm_request
└─ qwen-code.tool [chamada de agente #C]
   └─ qwen-code.subagent (C, fork)           [traceId=T1, raiz linkada]
      └─ qwen-code.llm_request                [traceId=T1]
         └─ ...                               [traceId=T1, pode emitir horas depois]

context.with(span, runX) para cada um de A, B, C executa concorrentemente. AsyncLocalStorageContextManager (já registrado automaticamente pelo NodeSDK em sdk.ts:273) escopa por fiber; sem interferência. Os spans filhos LLM / ferramenta / hook de cada subagent veem span via context.active() dentro de sua própria cadeia async.

Fork (C) é um trace separado — seus spans filhos herdam traceId=T1 mesmo quando emitidos em múltiplas interações subsequentes da sessão pai. ARMS consulta por session.id retorna tanto T0 quanto T1; o Link da raiz de T1 → span qwen-code.tool invocador de C fornece navegação explícita.

Arquivos a modificar

Total: 9 arquivos, ~430 LOC. Maior que commits típicos da Fase 2, mas justificado — alteração TTL toca um arquivo separado, bypass do LogToSpanProcessor é um arquivo separado, e os arquivos de teste dobram. Dividir resultaria numa superfície de telemetria incompleta.

Se a revisão rejeitar o tamanho: dividir em 2 PRs — (A) helpers de telemetria + testes, (B) conexão agent.ts + testes e2e. Helpers lançados primeiro não alteram comportamento em tempo de execução.

Estratégia de teste

Casos limite

Rollback

A mudança é aditiva no nível OTel — dashboards existentes que não filtram por nomes de span relacionados a subagentes continuam funcionando. Consumidores de trace que agrupam por span pai verão novos nós qwen-code.subagent entre qwen-code.tool e qwen-code.llm_request; documentar nas notas de release.

A mudança que afeta o comportamento é a omissão do LogToSpanProcessor — dashboards que anteriormente consumiam o span qwen-code.subagent_execution retornam zero. Mitigação: manter o LogRecord intacto (RUM + métricas ainda o veem); apenas a ponte de span é removida. Consultas existentes baseadas em log não são afetadas.

Caminho de rollback: reverter o único PR. Os novos helpers de span são invocados apenas a partir de agent.ts; remover a fiação + a omissão do LogToSpanProcessor restaura o comportamento anterior 1:1.

Implicações de amostragem

Para o padrão atual do qwen-code (conforme tracer.ts:shouldForceSampled() — parentbased + always_on senão always_on), todo span é amostrado, então a divergência não afeta. Para implantações que usam amostradores probabilísticos (ex.: traceidratio=0.1), isso significa:

• Um prompt de usuário pode ser amostrado (T0 totalmente capturado), mas seu fork (T1) pode ser descartado, ou vice-versa.
• Operadores lendo o T0 pai veem “Link: subagent C (T1)” — clicar pode resultar em 404 se T1 não foi amostrado.

Mitigação: documentar para operadores. Se a captura completa do subagente for importante, forçar a amostragem para fork/background por meio de um futuro knob de configuração. Fora do escopo aqui.

Atributos sensíveis (integração #4097)

Reutilizar o gate includeSensitiveSpanAttributes existente. Quando verdadeiro, definir no span do subagente nos hooks de ciclo de vida onde os dados estão disponíveis:

Todos esses já estão protegidos por gate; o padrão da #4097 é chamar o helper addSubagentSensitiveAttributes(span, opts) de dentro do corpo. Detalhe de implementação — o design apenas observa o ponto de integração.

Sequenciamento

• Independente da #4367 (atributos de recurso — em revisão). Sem restrição de ordem de merge, mas gen_ai.conversation.id em spans de subagente se beneficia da #4367 com session.id movido do recurso. Recomendamos integrar a #4367 primeiro para que a fonte da verdade de getSessionId() seja estabelecida.
• Independente da Fase 4 (decomposição de requisição LLM / TTFT). A Fase 4 se anexa a spans qwen-code.llm_request independentemente de estarem sob um subagente ou uma interação. Recomendamos a Fase 3 antes da Fase 4 para que as métricas por tentativa da Fase 4 possam ser agregadas por subagente.

Perguntas em aberto

1. gen_ai.provider.name: a especificação exige, mas escreve a descrição para provedor LLM, não para framework de agente. Definir como 'qwen-code' é a melhor interpretação; se uma revisão futura da especificação adicionar uma variante agent.provider.name, devemos trocar.
2. Nome do span qwen-code.subagent vs especificação invoke_agent {name}: optamos por consistência interna. Se a adoção de ferramentas que entendem GenAI crescer e invoke_agent ${name} se tornar crítico para descoberta automática, podemos trocar — o nome do span é a coisa mais rebrandável no OTel.
3. Aviso suave na profundidade ≥ 5: número arbitrário. Pode ser um knob de configuração. Adiar até que dados de produção mostrem necessidade.
4. A saída LLM completa de SubagentExecutionEvent.result é grande: hoje incha o volume de LogRecord. O plano de migração (LogRecord → eventos de span) é adiado, mas vale a pena fazer quando a agregação de uso de token chegar na Fase 4.
5. Spans de ponte de log dentro de um fork acabam no traceId derivado da sessão, não no T1 do fork: ver casos de borda. A correção é o problema mais amplo “span de interação não herda contexto raiz da sessão” levantado no tópico sessionId-vs-traceId — um design separado que afeta todos os spans nativos, não apenas subagente. Fora do escopo.