Проектирование дерева трасс суб-агентов (P3, фаза 3)

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

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

Проблема

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

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

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

Вне рамок (отложено)

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

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

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

D1 — Продолжительность жизненного цикла: вызывающий открывает, вызываемый выполняется внутри 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. Операторы, отслеживающие “почему этот сабагент медленный?”, увидят полную картину. Подготовка обычно << время LLM, так что это не создает шума.

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

Почему не только вызываемый: к моменту, когда тело fork / background действительно запускается, вызывающий уже вернул управление. otelContext.active() тогда возвращает тот контекст, который несет асинхронная среда выполнения — что для void fire-and-forget после завершения родителя ненадежно. Родительский span уже закрыт; перепривязка после факта некорректна.

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

Оба конца необходимы. Дизайн — это мост — вызывающий создает span + стратегию traceId в зависимости от типа вызова, затем передает управление через runInSubagentSpanContext.

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

Полезная нагрузка Link:

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

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

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

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

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

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 спаны саб-агентов получают отметку:

{
  '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 минут: легитимные долгие саб-агенты (анализ большого репозитория, медленные сборки, глубокие исследовательские задачи) ошибочно помечаются как TTL-просроченные. 4 часа покрывают 99-й перцентиль, не будучи настолько большими, чтобы реальные зависания остались незамеченными.

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

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

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

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

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

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

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

Почему не удалить LogRecord: он является входом для RUM и метрик. Удаление потребует рефакторинга трёх систем; выходит за рамки данной задачи.

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

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

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

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

Вид спана: INTERNAL (внутрипроцессный вызов саб-агента, по спецификации).

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

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

Почему двойная эмиссия по id + name: спецификация находится в стадии Development (на один шаг раньше, чем Experimental). Существует OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental для опционального включения. Имена атрибутов спецификации могут быть переименованы до перехода в Stable. Двойная эмиссия — это тот же паттерн, который Фаза 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 по префиксу.

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

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

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

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

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

runWithAgentContext уже использует разворот { ...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. Вложенный: parent depth+1.

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

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

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') {
    // Дочерний от текущего активного span (span инструмента вызывающего)
    return tracer.startSpan(SPAN_SUBAGENT, {
      kind: SpanKind.INTERNAL,
      attributes,
    });
  }
 
  // fork / background: связанный корневой span
  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 named (основной путь)

// agent.ts:~2154
// Извлекаем родительский ALS frame для установки parentAgentId на span. Глубина нового дочернего
// вычисляется внутри runWithAgentContext автоматически (D6) — мы
// читаем её через getCurrentAgentDepth(), когда уже НАХОДИМСЯ внутри дочернего ALS
// frame. Два шага:
const parentAgentId = getCurrentAgentId();  // ДО входа в дочерний frame
 
// ... существующий вызов runFramed заходит в runWithAgentContext(hookOpts.agentId, ...) ...
 
// ВНУТРИ runFramed мы можем прочитать глубину дочернего:
//   const depth = getCurrentAgentDepth();
//
// Практическое расположение: передать `depth` как переменную замыкания, установленную после
// того, как runWithAgentContext вступит в силу — ИЛИ вычислить её как
// `(getCurrentAgentDepth() снаружи) + 1` со стороны вызывающего (проще).
const depth = getCurrentAgentDepth();  // вне frame; дочерний будет this + 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 немедленно;
// span живёт на протяжении последующих взаимодействий родительской сессии.

Фоновый режим

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

Параллельная изоляция — главное преимущество

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

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

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

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

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

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

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

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

Откат

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

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

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

Влияние на сэмплирование

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

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

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

Чувствительные атрибуты (интеграция #4097)

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

Всё это уже зашлюзовано; паттерн #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 vs спецификация invoke_agent {name}: выбрали внутреннюю согласованность. Если использование GenAI-совместимых инструментов вырастет и invoke_agent ${name} станет критичным для автообнаружения, можно переключиться — имя спана — наиболее переименовываемая вещь в OTel.
3. Мягкое предупреждение на глубине ≥ 5: произвольное число. Может быть ручкой конфигурации. Отложить, пока данные с продакшена не покажут необходимость.
4. SubagentExecutionEvent.result содержит полный вывод LLM, что объёмно: сегодня это раздувает объём LogRecord. План миграции (LogRecord → события спанов) отложен, но стоит выполнить, когда в Фазе 4 появится агрегация использования токенов.
5. Спаны лог-моста внутри fork попадают на traceId, полученный из сессии, а не на T1 форка: см. граничные случаи. Исправление — более широкая проблема «span взаимодействия не наследует контекст корня сессии», поднятая в ветке sessionId-vs-traceId — отдельный дизайн, затрагивающий все нативные спаны, не только субагента. Выходит за рамки.