サブエージェントトレースツリー設計 (P3 フェーズ 3)

Issue #3731 — 階層型セッショントレーシングのフェーズ 3。qwen-code.subagent スパンを追加することで、サブエージェント呼び出しが分離され、クエリ可能なトレース構造になり、親の qwen-code.interaction スパンに暗黙的に混在することがなくなります。

フェーズ 1 (#4126)、フェーズ 1.5 (#4302)、フェーズ 2 (#4321) の上に構築されます。

問題

現在、すべての AgentTool.execute 呼び出しは親の qwen-code.interaction スパンの下で実行されます。3つの問題があります：

1. 並行するサブエージェントが混在する。 coreToolScheduler.ts:728 は AGENT を同時実行安全としてマークします — Promise.all は最大10個のサブエージェントを並行して実行します。それらの LLM リクエスト / ツール / フック スパンはすべて、単一の共有親インタラクションスパンにアタッチされるため、トレースエクスプローラは「この LLM リクエストはサブエージェント A に属する」と「これはサブエージェント B に属する」を区別できません。
2. サブエージェント境界自体のスパンがない。 qwen-code.subagent_execution LogRecord (agent-headless.ts:268,329 から発行) があり、LogToSpanProcessor を介して同じ名前のスパンにブリッジされますが、これはスタンドアロンのマーカーであり、サブエージェントの LLM / ツール / フック スパンをネストする親ではありません。
3. フォーク / バックグラウンドサブエージェントが宙に浮く。 ファイア・アンド・フォーゲットパス (runInForkContext / バックグラウンド) は親の AgentTool.execute よりも長生きし、複数の後続のユーザーターンにわたってスパンを発行します。それらのスパンが表示される頃には親のツールスパンは既に終了しているため、OTel の context.active() は役に立ちません。それらは発火時にたまたまアクティブだったインタラクションにアタッチされるか、どこにもアタッチされません。

既存の表面 (変更なし)

スコープ外 (延期)

• サブエージェントごとのトークン使用量集計 (gen_ai.usage.* をサブエージェント内のすべての LLM スパンで合計)。フェーズ 4 (LLM リクエスト分解) に属します。
• qwen-code.subagent_execution LogRecord を新しいスパンのスパンイベントとして移行する。 RUM とメトリクスは LogRecord に密結合されています。3つのコンシューマすべてをまとめて再交渉できるフォローアップに延期します。
• 自動コストロールアップ。 同じ理由 — まずトークン使用量が必要です。
• AGENT ツールの concurrent: true マーカーを削除する。 並行性は正しいです。制約するのではなく、計装します。

参考文献 (意思決定の根拠)

設計 — 6つの決定、それぞれ正当化

D1 — スパンライフサイクル: 呼び出し元が開始し、呼び出し先は context.with(span, fn) 内で実行

agent.ts (呼び出し元) がスパンを構築します。本体 — await 待機 (runFramed) かファイア・アンド・フォーゲット (runInForkContext / バックグラウンド) か — は runInSubagentSpanContext(span, fn) 内で実行され、これは otelContext.with(trace.setSpan(active, span), fn) を呼び出します。

AgentTool.execute 内のどこでスパンが開かれるか？ 呼び出しフレーバー固有のセットアップ (createAgentHeadless / createForkSubagent など) の直前に開きます — これにより、セットアップ時間 (設定ビルド、ToolRegistry 再構築、ContextOverride 配線) が qwen-code.subagent の期間に含まれます。「なぜこのサブエージェントは遅いのか？」を追跡するオペレーターは全体像を見ることができます。セットアップは通常 LLM 時間よりもはるかに短いため、これはノイズになりません。

検討した代替案: セットアップ後に開き、セットアップ時間を除外する。却下: サブエージェントのセットアップはサブエージェントに帰属する作業そのものです。それを隠すと、すべてのサブエージェントスパンを合計するときに合計時間の計算が間違ってしまいます。

呼び出し先のみではダメな理由: フォーク/バックグラウンド本体が実際に実行される頃には、呼び出し元はすでに戻っています。OTel の context.active() は、非同期ランタイムが引き継ぐ任意のアンビエントコンテキストを返します — これは、親が終了した後の void ファイア・アンド・フォーゲットでは信頼できません。親スパンはすでに閉じられています。事後的に再ペアレントすることは誤りです。

呼び出し元のみではダメな理由: フォアグラウンドはそれでうまく動作しますが、フォーク/バックグラウンドスパンは AgentTool.execute が戻った後も子スパン (LLM / ツール / フック) を発行し続ける必要があります。これらの子スパンは context.active() がサブエージェントスパンを返す必要があります — これは、本体が明示的に context.with(subagentSpan, body) 内で実行された場合にのみ発生します。

両方の端が必要です。設計は橋渡しです — 呼び出し元がスパン + invocationKind 対応 traceId 戦略を作成し、runInSubagentSpanContext を介してハンドオフします。

D2 — ハイブリッド traceId: フォアグラウンド = 子スパン、フォーク/バックグラウンド = 新しい traceId + Link

Link ペイロード:

tracer.startSpan(
  'qwen-code.subagent',
  {
    kind: SpanKind.INTERNAL,
    links: [
      {
        context: invokerSpanContext,
        attributes: { 'qwen-code.link.kind': 'invoker' },
      },
    ],
  } /* 明示的コンテキスト = ルート、アクティブは継承しない */,
);

セッション ID によるクロストレース検索: gen_ai.conversation.id はすべてのサブエージェントスパン (フォアグラウンドとリンクされたルートの両方) に設定されるため、session.id で ARMS クエリを実行すると、親インタラクションのトレースとリンクされたルートサブエージェントトレースの両方が返されます。Link 自体は親トレースの UI に「Spawned: subagent X (other trace)」として表示されるため、ナビゲーションが機能します。

常に子ではない理由: 4時間のバックグラウンドサブエージェントは親トレースの壁掛け時間を4時間に引き伸ばし、トレースサイズがいくつかのバックエンドの上限 (LangSmith の25,000実行制限が最も明確に文書化された境界) を超えます。ユーザーが実際に待っているフォアグラウンドサブエージェントは、時間的に包含されているためこの問題はありません。

常にリンクされたルートではない理由: フォアグラウンドは自然なトレースツリーを壊します。同期的な Explore サブエージェントを実行するユーザープロンプトは、2つのリンクされたトレースではなく、1つのツリーを表示するべきです。

D3 — TTL: タイプ認識、サブエージェントフォーク/バックグラウンド = 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分のセーフティネットはこれを防ぎます; サブエージェントフォーク/バックグラウンドはより広いウィンドウが必要なだけで、削除ではありません。

4時間の根拠: 非自明なエージェントタスク (長期深層リサーチ / 大規模コードベース分析) の実用的な上限。本番データが間違いを示した場合、定数で設定可能です。

D4 — LogRecord 保持: 発行は維持し、LogToSpanProcessor ブリッジはスキップ

SubagentExecutionEvent LogRecord には3つの下流コンシューマがあります (リポジトリ監査で確認):

ブリッジスキップ (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 に更新する必要があります。リリースノートに記載します。

LogRecord を削除しない理由: RUM とメトリクスの入力です。削除は3システムのリファクタリングになります。ここではスコープ外です。

両方を維持しない理由: トレースではサブエージェントあたり2つのスパン (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 } (Phase 2 の慣例に従う)

id + name で dual-emit する理由: 仕様は Development 段階 (Experimental より一段階手前)。OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental でオプトイン可能。仕様の属性名は Stable になる前に変更される可能性がある。Dual-emit は Phase 2 が call_id → tool.call_id で使用したのと同じパターン。仕様が Stable に達したら vendor key を削除する。

なぜ qwen-code.subagent.* なのか (qwen.subagent.* ではないのか): constants.ts 内の既存の vendor 接頭辞付きキーはすべて qwen-code.* を使用している (qwen-code.user_prompt, qwen-code.tool_call など)。OTel の命名規則の好みよりも内部の一貫性を優先する。これは、オペレーターが ARMS で接頭辞によるクエリを実行するため。

カーディナリティ: OTel では span 属性はメトリクスラベルではない。UUID をキーとする属性 (id, parent_agent_id, invoking_request_id) は span レイヤーでは安全。後でメトリクスラベルに昇格させないこと。

span あたり約 10～15 属性 (呼び出しの種類、失敗、ネストによって異なる)。qwen-code.tool と同じ順序。

D6 — AgentContext.depth フィールドを直接追加

AgentContext (agent-context.ts:32) は エクスポートされていない — ヘルパー (getCurrentAgentId、runWithAgentContext、getRuntimeContentGenerator、runWithRuntimeContentGenerator) のみがエクスポートされている。TypeScript レベルでの下流への影響はゼロ。getCurrentAgentId() を介した 6 つの既知の読み取り元は agentId のみを読み取る。depth?: number を追加してもそれらには影響しない。

interface AgentContext {
  agentId: string;
  subagentName: string;
  invokingRequestId: string;
  invocationKind: 'spawn' | 'resume';
  isBuiltIn: boolean;
  depth?: number; // NEW — デフォルトは読み取り元で 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。ネスト: 親 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 フレームを取得して、parentAgentId を span に設定する。新しい子の
// depth は runWithAgentContext 内で自動的に計算される (D6)。
// 子の ALS フレームの **内部** に入ったら getCurrentAgentDepth() で読み取る。
// 2 ステップ:
const parentAgentId = getCurrentAgentId();  // 子フレームに入る前
 
// ... 既存の runFramed 呼び出しが runWithAgentContext(hookOpts.agentId, ...) に入る ...
 
// runFramed の内部で、子の depth を読み取れる:
//   const depth = getCurrentAgentDepth();
//
// 実用的な配置: depth をクロージャ変数として渡し、runWithAgentContext が有効になった後に設定する
// または、呼び出し側で `(外側の getCurrentAgentDepth()) + 1` として計算する (よりシンプル)。
const depth = getCurrentAgentDepth();  // フレームの外側; 子はこれ + 1 になる
// (startSubagentSpan の引数で qwen-code.subagent.depth = depth を設定)
 
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 (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 は直ちに FORK_PLACEHOLDER_RESULT を返す;
// span は親セッションのその後のインタラクションにわたって存続する。

Background

fork と同じ形状で、invocationKind: 'background' と eventEmitter の代わりに bgEventEmitter を使用する。TTL は 4h (fork と同じ — D3 の型ルール)。

並行分離 — 主要な保証

1 つのユーザープロンプトからの 3 つの並行サブエージェント呼び出し (モデルが 3 つの AGENT tool_use ブロックを出力 → coreToolScheduler.runConcurrently が 3 つの executeSingleToolCall を並行実行。それぞれが Phase 2 に従って自身の qwen-code.tool span を開始):

qwen-code.interaction                         [traceId=T0]
├─ qwen-code.tool [agent call #A]
│  └─ qwen-code.subagent (A, foreground)     [traceId=T0, child]
│     ├─ qwen-code.llm_request
│     └─ qwen-code.tool [...]
│        └─ qwen-code.tool.execution
├─ qwen-code.tool [agent call #B]
│  └─ qwen-code.subagent (B, foreground)     [traceId=T0, child]
│     └─ qwen-code.llm_request
└─ qwen-code.tool [agent call #C]
   └─ qwen-code.subagent (C, fork)           [traceId=T1, linked root]
      └─ qwen-code.llm_request                [traceId=T1]
         └─ ...                               [traceId=T1, 数時間後に出力される可能性あり]

A、B、C のそれぞれに対して context.with(span, runX) が並行実行される。AsyncLocalStorageContextManager (NodeSDK によって sdk.ts:273 で既に自動登録済み) がファイバーごとにスコープするため、クロストークは発生しない。各サブエージェントの子 LLM / tool / hook span は、自身の非同期チェーン内で context.active() を介して span を認識する。

fork (C) は別のトレース — その子 span は、親セッションのその後の複数のインタラクションにわたって出力される場合でも traceId=T1 を継承する。session.id による ARMS クエリは T0 と T1 の両方を返す。T1 のルートから C の呼び出し元 qwen-code.tool span への Link が明示的なナビゲーションを提供する。

変更するファイル

合計: 9 ファイル、約 430 LOC。通常の Phase 2 コミットよりも大きいが、正当化される — TTL の変更は別のファイル、LogToSpanProcessor のスキップは別のファイル、テストファイルは倍増している。分割すると不完全なテレメトリーサーフェスになってしまう。

レビューでサイズが問題になった場合: 2 つの PR に分割 — (A) テレメトリーヘルパー + テスト、(B) agent.ts の配線 + e2e テスト。先にマージされたヘルパーはランタイムの動作を変更しない。

テスト戦略

エッジケース

ロールバック

この変更はOTelレベルでは追加的なものであり、subagentに関連するスパン名でフィルタリングしていない既存のダッシュボードは引き続き動作します。親スパンでグループ化するトレースコンシューマは、qwen-code.tool と qwen-code.llm_request の間に新しい qwen-code.subagent ノードを確認するようになります。リリースノートに記載してください。

動作に影響を与える変更は、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)」を参照しますが、T1がサンプリングされていない場合、クリックすると404になる可能性があります。

軽減策: オペレーター向けに文書化します。subagentの完全なキャプチャが重要な場合は、将来の設定ノブを介してfork/backgroundの強制サンプリングを行います。ここでは対象外です。

機密属性（#4097 統合）

既存の includeSensitiveSpanAttributes ゲートを再利用します。trueの場合、データが利用可能なライフサイクルフックでsubagentスパンに設定します：

これらはすべてすでにゲートされています。#4097のパターンは、ボディ内部から addSubagentSensitiveAttributes(span, opts) ヘルパーを呼び出すことです。実装の詳細 — 設計では統合ポイントを記すだけです。

順序

• #4367（リソース属性 — レビュー中）とは独立。マージ順序の制約はありませんが、subagentスパンの gen_ai.conversation.id は、#4367で session.id がリソースから移動されることの恩恵を受けます。#4367を先にマージすることを推奨 し、getSessionId() の信頼できる情報源を確定させます。
• フェーズ4（LLMリクエスト分解 / TTFT）とは独立。フェーズ4は、subagent配下かインタラクション配下かに関わらず、qwen-code.llm_request スパンにアタッチされます。フェーズ3の後にフェーズ4を行うことを推奨します。これにより、フェーズ4の試行ごとのメトリクスをsubagentごとに集計できます。

未解決の質問

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. フォーク内のログブリッジスパンは、フォークのT1ではなくセッション由来のtraceIdになる: エッジケースを参照。修正は、sessionId-vs-traceIdスレッドで提起されたより広範な「インタラクションスパンがセッションルートコンテキストを継承しない」問題です。これはsubagentだけでなくすべてのネイティブスパンに影響する別の設計であり、スコープ外です。