Subagent Trace Tree Design (P3 Phase 3)

Issue #3731 — Фаза 3 иерархической трассировки сессий. Добавляет span qwen-code.subagent, чтобы вызовы subagent’ов получали изолированную, запрашиваемую структуру трассы вместо бесшумного перемешивания под родительским span’ом qwen-code.interaction.

Основана на Фазе 1 (#4126), Фазе 1.5 (#4302) и Фазе 2 (#4321).

Проблема

Сегодня каждый вызов AgentTool.execute выполняется под родительским span’ом qwen-code.interaction. Три патологии:

1. Конкурирующие subagent’ы перемешиваются. coreToolScheduler.ts:728 помечает AGENT как безопасный для конкурентного выполнения — Promise.all запускает до 10 subagent’ов параллельно. Их LLM-request / tool / hook span’ы все прикрепляются к одному общему родительскому interaction span’у, поэтому инструменты просмотра трасс не могут отличить «этот LLM-запрос принадлежит subagent’у A» от «этот — subagent’у B».
2. Нет span’а для самой границы subagent’а. Существует LogRecord qwen-code.subagent_execution (создаётся в agent-headless.ts:268,329), который мостится к span’у с тем же именем через LogToSpanProcessor, но это самостоятельная метка, а не родитель, в который вкладываются LLM / tool / hook span’ы subagent’а.
3. Fork / background subagent’ы свободно плавают. Пути «забыл и забыл» (runInForkContext / background) переживают родительский AgentTool.execute и создают span’ы во время нескольких последующих пользовательских обращений. Родительский tool span уже завершён к моменту появления этих span’ов, поэтому context.active() OTel не помогает — они прикрепляются к тому interaction’у, который случайно был активен в момент запуска, или ни к какому.

Существующая поверхность (без изменений)

Вне области видимости (отложено)

• Агрегация использования токенов на subagent (gen_ai.usage.*, суммированные по всем LLM span’ам внутри subagent’а). Относится к Фазе 4 (декомпозиция LLM-запросов).
• Миграция LogRecord qwen-code.subagent_execution на новый span как события span’а. RUM и метрики тесно связаны с LogRecord; отложено до последующего изменения, которое сможет пересогласовать всех 3 потребителей вместе.
• Автоматический подсчёт стоимости. То же — сначала нужен usage токенов.
• Удаление маркера concurrent: true у AGENT-tool. Конкурентность верна; мы её инструментируем, а не ограничиваем.

Ссылки (обоснование решений)

Дизайн — шесть решений, каждое обосновано

D1 — Жизненный цикл span’а: вызывающий открывает, вызываемый выполняется внутри context.with(span, fn)

agent.ts (вызывающий) создаёт span. Тело — будь то ожидание (runFramed) или «забыл и забыл» (runInForkContext / background) — выполняется внутри runInSubagentSpanContext(span, fn), который вызывает otelContext.with(trace.setSpan(active, span), fn).

Где именно в AgentTool.execute открывается span? Открывать его НЕПОСРЕДСТВЕННО ПЕРЕД настройкой, специфичной для типа вызова (createAgentHeadless / createForkSubagent и т.д.) — чтобы время настройки (сборка конфига, пересборка ToolRegistry, подключение ContextOverride) включалось в длительность qwen-code.subagent. Операторы, отслеживающие «почему этот subagent медленный?», видят полную картину. Настройка обычно << времени LLM, так что это без помех.

Рассматривалась альтернатива: открывать после настройки, исключив время настройки. Отклонено, потому что настройка subagent’а — это тоже работа, относимая к subagent’у — её скрытие делает математику общей длительности неверной при суммировании всех span’ов subagent’ов.

Почему не только вызываемый: к тому моменту, когда тело fork / background действительно выполняется, вызывающий уже вернул управление. context.active() OTel тогда возвращает контекст, который несёт асинхронный runtime — что для void «забыл и забыл» после завершения родителя ненадёжно. Родительский span уже закрыт; переназначение родителя post factum неверно.

Почему не только вызывающий: foreground отлично работает таким образом, но fork / background span’ы должны продолжать создавать дочерние span’ы (LLM / tool / hook) после возврата из AgentTool.execute. Этим дочерним span’ам нужно, чтобы context.active() возвращал span subagent’а — что происходит только если тело явно выполняется внутри context.with(subagentSpan, body).

Нужны обе стороны. Дизайн — это мост — вызывающий создаёт span + traceId-стратегию, зависящую от типа вызова, затем передаёт управление через runInSubagentSpanContext.

D2 — Гибридный traceId: foreground = дочерний span, fork/background = новый traceId + Link

Payload Link’а:

tracer.startSpan(
  'qwen-code.subagent',
  {
    kind: SpanKind.INTERNAL,
    links: [
      {
        context: invokerSpanContext,
        attributes: { 'qwen-code.link.kind': 'invoker' },
      },
    ],
  } /* явный context = root, не наследует активный */,
);

Возможность запросов между трассами через идентификатор сессии: gen_ai.conversation.id устанавливается на каждом span’е subagent’а (как для foreground, так и для связанных корневых), так что запрос ARMS по session.id вернёт и трассу родительского interaction’а, и трассы связанных корневых subagent’ов. Сам Link отображается в UI родительской трассы как «Порождён: subagent X (другая трасса)», обеспечивая навигацию.

Почему не всегда дочерний: background subagent на 4 часа раздувает длительность родительской трассы по wall-clock до 4 часов; размер трассы превышает лимиты некоторых бэкендов (лимит LangSmith в 25 000 runs — самый чёткий задокументированный порог). Foreground subagent’ы, которых пользователь действительно ожидает, не имеют этой проблемы, потому что они временно заключены внутри родителя.

Почему не всегда связанный корневой: foreground ломает естественное дерево трассы. Пользовательский запрос, который запускает синхронный Explore subagent, ДОЛЖЕН показывать одно дерево, а не две связанные трассы.

D3 — TTL: с учётом типа, subagent fork/background = 4ч, остальные = 30 мин

session-tracing.ts:124 определяет SPAN_TTL_MS = 30 * 60 * 1000. Очистка в :144-152 уже обрабатывает tool.blocked_on_user особым образом, устанавливая decision: 'aborted' + source: 'system'. Она уже по духу осведомлена о типе.

Изменение: ввести TTL по типу:

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;
}

По истечении TTL span’ы subagent’ов получают пометку:

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

Почему не 30 минут ровно: законные долгие subagent’ы (анализ большой репы, медленные сборки, задачи глубокого исследования) получают ошибочную пометку как TTL-истекшие. 4 часа покрывают 99-й перцентиль, не будучи настолько свободными, чтобы реальные зависания остались незамеченными.

Почему не без TTL: сбой процесса / OOM / kill -9 → span остаётся в Map activeSpans навсегда. Защитная сетка в 30 минут предотвращает это; subagent fork/background просто требует более широкого окна, а не удаления TTL.

Откуда 4 часа: прагматичная верхняя граница для нетривиальных задач агентов (длительное глубокое исследование / анализ большой кодовой базы). Настраивается через константу, если производственные данные покажут, что мы ошиблись.

D4 — Сохранение LogRecord: оставить эмиссию, пропустить мост LogToSpanProcessor

LogRecord SubagentExecutionEvent имеет 3 потребителя (проверено аудитом репозитория):

Пропуск моста (единственное изменение в LogToSpanProcessor):

// log-to-span-processor.ts — внутри onEmit, после deriveSpanName
const skipBridge = new Set<string>([
  EVENT_SUBAGENT_EXECUTION, // покрывается нативным span'ом qwen-code.subagent
]);
if (skipBridge.has(eventName)) return;

Влияние на потребителей трасс: дашборды, фильтрующие по имени span’а qwen-code.subagent_execution, начнут возвращать ноль результатов. Их следует обновить на qwen-code.subagent. Отметить это в release notes.

Почему не удалить LogRecord: это вход для RUM и метрик. Его удаление — это рефакторинг трёх систем; вне области видимости.

Почему не оставить оба: в трассе будет отображаться два span’а на subagent (qwen-code.subagent + qwen-code.subagent_execution) с перекрывающейся информацией — запутывает операторов при чтении трасс, дублирует объём span’ов.

D5 — Имя span’а + атрибуты: гибридное соответствие спецификации, с вендорным префиксом для расширений

Имя span’а: qwen-code.subagent (соответствует соглашению кодовой базы Фаз 1/2: qwen-code.interaction, qwen-code.tool, qwen-code.hook, …).

Спецификация OTel GenAI говорит, что каноническое имя span’а — invoke_agent {gen_ai.agent.name} — но также говорит «отдельные GenAI системы/фреймворки МОГУТ указывать другие форматы имён span’ов». Мы используем своё имя и устанавливаем gen_ai.operation.name='invoke_agent', чтобы инструменты, знающие спецификацию, всё равно идентифицировали span. Операторы, читающие наше дерево трасс, видят согласованное именование qwen-code.*.

Span kind: INTERNAL (внутрипроцессный вызов subagent’а, согласно спецификации).

Набор атрибутов:

• status === 'completed' → SpanStatus { code: OK }
• status === 'failed' → SpanStatus { code: ERROR, message: truncated(error.message) }
• status === 'cancelled' или 'aborted' → SpanStatus { code: UNSET } (соответствует соглашению из Phase 2)

Почему двойная эмиссия по id + name: спецификация находится в стадии Development (на один шаг раньше Experimental). Существует OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental для опционального включения. Имена атрибутов в спецификации могут быть переименованы до перехода в Stable. Двойная эмиссия — это тот же паттерн, который Phase 2 использовал для call_id → tool.call_id; удалите вендорный ключ, когда спецификация достигнет Stable.

Почему qwen-code.subagent.* (а не qwen.subagent.*): все существующие ключи с префиксом вендора в constants.ts используют qwen-code.* (qwen-code.user_prompt, qwen-code.tool_call, и т.д.). Внутренняя согласованность важнее предпочтений OTel по именованию, так как операторы запрашивают ARMS по префиксу.

Кардинальность: атрибуты спана не являются метками метрик в OTel; атрибуты с ключами в формате UUID (id, parent_agent_id, invoking_request_id) безопасны на уровне спана. Не продвигайте их в метки метрик в дальнейшем.

~10–15 атрибутов на спан (в зависимости от вида вызова, ошибок, вложенности). То же количество, что и у qwen-code.tool.

D6 — поле AgentContext.depth добавлено напрямую

AgentContext (agent-context.ts:32) не экспортируется — только хелперы (getCurrentAgentId, runWithAgentContext, getRuntimeContentGenerator, runWithRuntimeContentGenerator). Нулевое количество сломанных downstream-компонентов на уровне TypeScript. 6 известных читателей через getCurrentAgentId() читают только agentId; добавление depth?: number невидимо для них.

interface AgentContext {
  agentId: string;
  subagentName: string;
  invokingRequestId: string;
  invocationKind: 'spawn' | 'resume';
  isBuiltIn: boolean;
  depth?: number; // НОВОЕ — по умолчанию 0 в читателях
}

runWithAgentContext уже использует spread { ...current, agentId }, поэтому depth сохраняется без изменений в существующих местах вызова. Обновите runWithAgentContext, чтобы он автоматически увеличивал depth — вызывающий код не должен знать о depth:

function runWithAgentContext<T>(agentId: string, fn: () => T): T {
  const parent = agentContextStorage.getStore();
  const next: AgentContext = {
    ...parent,
    agentId,
    depth: (parent?.depth ?? -1) + 1, // автоинкремент
  };
  return agentContextStorage.run(next, fn);
}

Суб-агент верхнего уровня: нет родительского ALS → depth: 0. Вложенный: depth = parent.depth + 1.

Новый маленький аксессор getCurrentAgentDepth(): number возвращает agentContextStorage.getStore()?.depth ?? 0 — используется в startSubagentSpan для заполнения qwen-code.subagent.depth.

Почему не отдельный ALS только для телеметрии: это дублировало бы ту же форму контекста, которую мы уже поддерживаем. Плохо. Используем существующий.

Helper API (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; // требуется для fork / background (источник 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 — примитив изоляции:

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

startSubagentSpan внутренне ветвится по invocationKind:

function startSubagentSpan(opts: StartSubagentSpanOptions): Span {
  const attributes = buildSpanAttributes(opts);
  const tracer = getTracer();
 
  if (opts.invocationKind === 'foreground') {
    // Дочерний от текущего активного спана (спан инструмента вызывающего)
    return tracer.startSpan(SPAN_SUBAGENT, {
      kind: SpanKind.INTERNAL,
      attributes,
    });
  }
 
  // fork / background: корневой спан с Link
  return tracer.startSpan(SPAN_SUBAGENT, {
    kind: SpanKind.INTERNAL,
    attributes,
    links: opts.invokerSpanContext
      ? [
          {
            context: opts.invokerSpanContext,
            attributes: { 'qwen-code.link.kind': 'invoker' },
          },
        ]
      : undefined,
    root: true, // принудительно новый traceId; игнорирует активный контекст как родительский
  });
}

Подключение жизненного цикла

Foreground именованный (общий путь)

// agent.ts:~2154
// Извлекаем родительский фрейм ALS, чтобы установить parentAgentId на спане. Глубина нового
// дочернего элемента вычисляется автоматически внутри runWithAgentContext (D6) — мы
// читаем её через getCurrentAgentDepth(), когда уже находимся ВНУТРИ дочернего фрейма ALS.
// Два шага:
const parentAgentId = getCurrentAgentId();  // ДО входа в дочерний фрейм
 
// ... существующий вызов runFramed входит в runWithAgentContext(hookOpts.agentId, ...) ...
 
// ВНУТРИ runFramed можно прочитать depth потомка:
//   const depth = getCurrentAgentDepth();
//
// Практическое размещение: передать depth как замыкательную переменную, установить после
// того, как сработает runWithAgentContext — ИЛИ вычислить как
// `(getCurrentAgentDepth() снаружи) + 1` со стороны вызывающего (проще).
const depth = getCurrentAgentDepth();  // вне фрейма; дочерний будет depth + 1
// (установить qwen-code.subagent.depth = depth в аргументах startSubagentSpan)
 
const span = startSubagentSpan({
  agentId, subagentName, invocationKind: 'foreground',
  isBuiltIn, parentAgentId, depth, invokingRequestId, sessionId,
  modelOverride,
  // invokerSpanContext опущен — foreground наследует естественным образом через 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 (запустил и забыл)

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 возвращает FORK_PLACEHOLDER_RESULT немедленно;
// спан живёт на протяжении последующих взаимодействий родительской сессии.

Background

Та же форма, что и fork, с invocationKind: 'background' и bgEventEmitter вместо eventEmitter. TTL = 4ч (то же, что и fork — правило типов из D3).

Параллельная изоляция — ключевая гарантия

Три одновременных вызова суб-агента из одного пользовательского промпта (модель генерирует 3 блока AGENT tool_use → coreToolScheduler.runConcurrently запускает 3 executeSingleToolCall параллельно; каждый открывает свой спан qwen-code.tool согласно Phase 2):

qwen-code.interaction                         [traceId=T0]
├─ qwen-code.tool [agent call #A]
│  └─ qwen-code.subagent (A, foreground)     [traceId=T0, дочерний]
│     ├─ qwen-code.llm_request
│     └─ qwen-code.tool [...]
│        └─ qwen-code.tool.execution
├─ qwen-code.tool [agent call #B]
│  └─ qwen-code.subagent (B, foreground)     [traceId=T0, дочерний]
│     └─ qwen-code.llm_request
└─ qwen-code.tool [agent call #C]
   └─ qwen-code.subagent (C, fork)           [traceId=T1, корневой с Link]
      └─ qwen-code.llm_request                [traceId=T1]
         └─ ...                               [traceId=T1, может быть создан спустя часы]

context.with(span, runX) для каждого из A, B, C выполняется параллельно. AsyncLocalStorageContextManager (уже автоматически зарегистрирован NodeSDK в sdk.ts:273) разграничивает по волокнам; перекрёстных помех нет. Дочерние LLM / tool / hook спаны каждого суб-агента видят span через context.active() внутри своей собственной асинхронной цепочки.

Fork (C) — это отдельный trace; его дочерние спаны наследуют traceId=T1, даже если они испускаются в течение нескольких последующих взаимодействий родительской сессии. Запрос ARMS по session.id возвращает и T0, и T1; Link от корня T1 к вызывающему спану qwen-code.tool для C обеспечивает явную навигацию.

Файлы для изменения

Всего: 9 файлов, ~430 LOC. Больше, чем типичные коммиты Phase 2, но оправдано — изменение TTL затрагивает отдельный файл, пропуск LogToSpanProcessor — отдельный файл, и тестовые файлы удваиваются. Разделение оставило бы неполную поверхность телеметрии.

Если ревьюеры будут против размера: разделить на 2 PR — (A) хелперы телеметрии + тесты, (B) подключение в agent.ts + e2e-тесты. Хелперы, внесённые первыми, не изменяют поведение во время выполнения.

Стратегия тестирования

Граничные случаи

Откат

Изменение является аддитивным на уровне OTel — существующие дашборды, которые не фильтруют по именам спанов, связанным с субагентом, продолжают работать. Потребители трейсов, группирующие по родительскому спану, увидят новые узлы qwen-code.subagent между qwen-code.tool и qwen-code.llm_request; задокументировать в примечаниях к релизу.

Изменение, влияющее на поведение — пропуск LogToSpanProcessor. Дашборды, ранее потреблявшие спан qwen-code.subagent_execution, получат ноль. Смягчение: оставить LogRecord нетронутым (RUM + метрики всё ещё его видят); убирается только мост спанов. Существующие запросы на основе логов не затронуты.

Путь отката: откатить единственный PR. Новые вспомогательные функции для спанов вызываются только из agent.ts; удаление разводки + пропуска LogToSpanProcessor восстанавливает предыдущее поведение 1:1.

Последствия для сэмплирования

Для текущих настроек qwen-code по умолчанию (см. tracer.ts:shouldForceSampled() — parentbased + always_on иначе always_on) каждый спан сэмплируется, поэтому расхождение не проявляется. Для развёртываний, использующих вероятностные сэмплеры (например, traceidratio=0.1), это означает:

• Пользовательский запрос может быть сэмплирован (T0 полностью захвачен), но его форк (T1) может быть отброшен, или наоборот.
• Операторы, читающие родительский T0, видят «Link: subagent C (T1)» — переход может привести к 404, если T1 не был сэмплирован.

Смягчение: задокументировать для операторов. Если важен полный захват субагента, принудительно включить сэмплирование для fork/background через будущую настройку. Выходит за рамки этой задачи.

Конфиденциальные атрибуты (интеграция #4097)

Повторно использовать существующий флаг includeSensitiveSpanAttributes. Когда true, устанавливается на спан субагента в точках жизненного цикла, где данные доступны:

Все они уже защищены флагом; паттерн #4097 — вызывать хелпер addSubagentSensitiveAttributes(span, opts) из тела. Детали реализации — дизайн лишь отмечает точку интеграции.

Последовательность

• Независимо от #4367 (атрибуты ресурса — на ревью). Нет ограничения на порядок слияния, но gen_ai.conversation.id на спанах субагента выигрывает от переноса session.id из ресурса в #4367. Рекомендуется сначала принять #4367, чтобы источник истины getSessionId() был зафиксирован.
• Независимо от Фазы 4 (декомпозиция запроса к LLM / TTFT). Фаза 4 прикрепляется к спанам qwen-code.llm_request независимо от того, находятся ли они под субагентом или под взаимодействием. Рекомендуется Фаза 3 перед Фазой 4, чтобы метрики за попытку из Фазы 4 можно было агрегировать по субагенту.

Открытые вопросы

1. gen_ai.provider.name: спецификация требует его, но пишет описание для провайдера LLM, а не для фреймворка агентов. Установка в 'qwen-code' — наилучшая интерпретация; если будущая редакция спецификации добавит вариант agent.provider.name, следует переключиться.
2. Имя спана qwen-code.subagent против спецификации invoke_agent {name}: выбрана внутренняя согласованность. Если инструментарий, понимающий GenAI, станет популярнее и invoke_agent ${name} станет критичным для автоматического обнаружения, можно переключиться — имя спана — самый заменяемый элемент в OTel.
3. Мягкое предупреждение при глубине ≥ 5: произвольное число. Может быть настройкой. Отложить, пока данные с продакшена не покажут необходимость.
4. SubagentExecutionEvent.result содержит полный вывод LLM — объёмный: сегодня это раздувает объём LogRecord. План миграции (LogRecord → события спанов) отложен, но стоит выполнить, когда в Фазе 4 появится агрегация использования токенов.
5. Спаны лог-моста внутри форка попадают на traceId, полученный из сессии, а не на T1 форка: см. граничные случаи. Исправление — более широкая проблема «спан взаимодействия не наследует корневой контекст сессии», поднятая в обсуждении sessionId-против-traceId — отдельный дизайн, затрагивающий все нативные спаны, а не только субагента. Выходит за рамки.