fix: propagate diagnostics timeline phase

shakkernerd · shakkernerd · commit c795a1a8ef19 · 2026-05-06T17:33:46.000+01:00
diff --git a/src/infra/diagnostics-timeline.test.ts b/src/infra/diagnostics-timeline.test.ts
@@ -215,4 +215,47 @@ describe("diagnostics timeline", () => {
       name: "plugins.metadata.scan",
     });
   });
+
+  it("lets nested spans inherit the active timeline phase and parent span", async () => {
+    const { env, path } = await createTimelineEnv();
+
+    const result = await measureDiagnosticsTimelineSpan(
+      "reply.run_agent_turn",
+      () =>
+        measureDiagnosticsTimelineSpanSync("plugins.metadata.scan", () => 42, {
+          env,
+        }),
+      {
+        env,
+        phase: "agent-turn",
+      },
+    );
+
+    expect(result).toBe(42);
+    const events = await readTimeline(path);
+    expect(events).toHaveLength(4);
+    const [parentStart, childStart, childEnd, parentEnd] = events;
+    expect(parentStart).toMatchObject({
+      type: "span.start",
+      name: "reply.run_agent_turn",
+      phase: "agent-turn",
+    });
+    expect(childStart).toMatchObject({
+      type: "span.start",
+      name: "plugins.metadata.scan",
+      phase: "agent-turn",
+      parentSpanId: parentStart?.spanId,
+    });
+    expect(childEnd).toMatchObject({
+      type: "span.end",
+      name: "plugins.metadata.scan",
+      phase: "agent-turn",
+      parentSpanId: parentStart?.spanId,
+    });
+    expect(parentEnd).toMatchObject({
+      type: "span.end",
+      name: "reply.run_agent_turn",
+      phase: "agent-turn",
+    });
+  });
 });
diff --git a/src/infra/diagnostics-timeline.ts b/src/infra/diagnostics-timeline.ts
@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { randomUUID } from "node:crypto";
 import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
@@ -60,8 +61,17 @@ type DiagnosticsTimelineOptions = {
   env?: NodeJS.ProcessEnv;
 };
 
+export type ActiveDiagnosticsTimelineSpan = {
+  name: string;
+  phase?: string;
+  spanId: string;
+  parentSpanId?: string;
+  attributes?: DiagnosticsTimelineAttributes;
+};
+
 let warnedAboutTimelineWrite = false;
 const createdTimelineDirs = new Set<string>();
+const activeDiagnosticsTimelineSpan = new AsyncLocalStorage<ActiveDiagnosticsTimelineSpan>();
 
 function resolveDiagnosticsTimelineOptions(
   options: DiagnosticsTimelineOptions = {},
@@ -177,6 +187,10 @@ export function emitDiagnosticsTimelineEvent(
   }
 }
 
+export function getActiveDiagnosticsTimelineSpan(): ActiveDiagnosticsTimelineSpan | undefined {
+  return activeDiagnosticsTimelineSpan.getStore();
+}
+
 export async function measureDiagnosticsTimelineSpan<T>(
   name: string,
   run: () => Promise<T> | T,
@@ -186,28 +200,40 @@ export async function measureDiagnosticsTimelineSpan<T>(
   if (!isDiagnosticsTimelineEnabled({ config: options.config, env })) {
     return await run();
   }
+  const activeSpan = getActiveDiagnosticsTimelineSpan();
   const spanId = randomUUID();
+  const phase = options.phase ?? activeSpan?.phase;
+  const parentSpanId = options.parentSpanId ?? activeSpan?.spanId;
   const startedAt = performance.now();
   emitDiagnosticsTimelineEvent(
     {
       type: "span.start",
       name,
-      phase: options.phase,
+      phase,
       spanId,
-      parentSpanId: options.parentSpanId,
+      parentSpanId,
       attributes: options.attributes,
     },
     { config: options.config, env },
   );
   try {
-    const result = await run();
+    const result = await activeDiagnosticsTimelineSpan.run(
+      {
+        name,
+        ...(phase ? { phase } : {}),
+        spanId,
+        ...(parentSpanId ? { parentSpanId } : {}),
+        ...(options.attributes ? { attributes: options.attributes } : {}),
+      },
+      () => run(),
+    );
     emitDiagnosticsTimelineEvent(
       {
         type: "span.end",
         name,
-        phase: options.phase,
+        phase,
         spanId,
-        parentSpanId: options.parentSpanId,
+        parentSpanId,
         durationMs: performance.now() - startedAt,
         attributes: options.attributes,
       },
@@ -219,9 +245,9 @@ export async function measureDiagnosticsTimelineSpan<T>(
       {
         type: "span.error",
         name,
-        phase: options.phase,
+        phase,
         spanId,
-        parentSpanId: options.parentSpanId,
+        parentSpanId,
         durationMs: performance.now() - startedAt,
         attributes: options.attributes,
         errorName: error instanceof Error ? error.name : typeof error,
@@ -242,28 +268,40 @@ export function measureDiagnosticsTimelineSpanSync<T>(
   if (!isDiagnosticsTimelineEnabled({ config: options.config, env })) {
     return run();
   }
+  const activeSpan = getActiveDiagnosticsTimelineSpan();
   const spanId = randomUUID();
+  const phase = options.phase ?? activeSpan?.phase;
+  const parentSpanId = options.parentSpanId ?? activeSpan?.spanId;
   const startedAt = performance.now();
   emitDiagnosticsTimelineEvent(
     {
       type: "span.start",
       name,
-      phase: options.phase,
+      phase,
       spanId,
-      parentSpanId: options.parentSpanId,
+      parentSpanId,
       attributes: options.attributes,
     },
     { config: options.config, env },
   );
   try {
-    const result = run();
+    const result = activeDiagnosticsTimelineSpan.run(
+      {
+        name,
+        ...(phase ? { phase } : {}),
+        spanId,
+        ...(parentSpanId ? { parentSpanId } : {}),
+        ...(options.attributes ? { attributes: options.attributes } : {}),
+      },
+      run,
+    );
     emitDiagnosticsTimelineEvent(
       {
         type: "span.end",
         name,
-        phase: options.phase,
+        phase,
         spanId,
-        parentSpanId: options.parentSpanId,
+        parentSpanId,
         durationMs: performance.now() - startedAt,
         attributes: options.attributes,
       },
@@ -275,9 +313,9 @@ export function measureDiagnosticsTimelineSpanSync<T>(
       {
         type: "span.error",
         name,
-        phase: options.phase,
+        phase,
         spanId,
-        parentSpanId: options.parentSpanId,
+        parentSpanId,
         durationMs: performance.now() - startedAt,
         attributes: options.attributes,
         errorName: error instanceof Error ? error.name : typeof error,
diff --git a/src/plugins/plugin-metadata-snapshot.ts b/src/plugins/plugin-metadata-snapshot.ts
@@ -1,5 +1,8 @@
 import type { OpenClawConfig } from "../config/types.openclaw.js";
-import { measureDiagnosticsTimelineSpanSync } from "../infra/diagnostics-timeline.js";
+import {
+  getActiveDiagnosticsTimelineSpan,
+  measureDiagnosticsTimelineSpanSync,
+} from "../infra/diagnostics-timeline.js";
 import { resolveInstalledPluginIndexPolicyHash } from "./installed-plugin-index-policy.js";
 import type { InstalledPluginIndex } from "./installed-plugin-index.js";
 import {
@@ -173,11 +176,12 @@ export function listPluginOriginsFromMetadataSnapshot(
 export function loadPluginMetadataSnapshot(
   params: LoadPluginMetadataSnapshotParams,
 ): PluginMetadataSnapshot {
+  const activeTimelineSpan = getActiveDiagnosticsTimelineSpan();
   return measureDiagnosticsTimelineSpanSync(
     "plugins.metadata.scan",
     () => loadPluginMetadataSnapshotImpl(params),
     {
-      phase: "startup",
+      phase: activeTimelineSpan?.phase ?? "startup",
       config: params.config,
       env: params.env,
       attributes: {
