Allow product-specific step span attributes

.changeset/project-step-provenance.md

@@ -0,0 +1,5 @@
+---
+'@workflow/web-shared': patch
+---
+
+Allow trace callers to add product-specific attributes to event-derived step spans.

packages/web-shared/src/components/trace-viewer.tsx

@@ -8,6 +8,7 @@ import {
 } from './sidebar/sidebar-data-context';
 import { TraceViewerSkeleton } from './trace-viewer/components/trace-viewer-skeleton';
 import { TraceViewer as TraceViewerComponent } from './trace-viewer/trace-viewer';
+import type { GetStepAttributes } from './workflow-traces/trace-span-construction';
 
 const TraceViewer = ({
   run,
@@ -17,6 +18,7 @@ const TraceViewer = ({
   hasMore,
   isLoadingMore,
   loading = false,
+  getStepAttributes,
 }: {
   run: WorkflowRun;
   events: Event[];
@@ -25,6 +27,8 @@ const TraceViewer = ({
   hasMore?: boolean;
   isLoadingMore?: boolean;
   loading?: boolean;
+  /** Adds product-specific attributes to event-derived step span data. */
+  getStepAttributes?: GetStepAttributes;
 }) => {
   const trace: TraceWithMeta | undefined = useMemo(() => {
     if (!run?.runId) {
@@ -35,9 +39,10 @@ const TraceViewer = ({
     // repeats with the whole log in hand.
     return buildTrace(run, events, new Date(), {
       isCompleteHistory: !hasMore,
+      getStepAttributes,
     });
     // eslint-disable-next-line react-hooks/exhaustive-deps -- `new Date()` is intentionally not a dep
-  }, [run, events, hasMore]);
+  }, [run, events, hasMore, getStepAttributes]);
 
   // The sidebar shows one entity's slice of the log, so it takes the trace's
   // answer rather than recomputing one from the slice.

packages/web-shared/src/components/workflow-traces/trace-span-construction.ts

@@ -150,6 +150,10 @@ export function waitToSpan(
   };
 }
 
+export type GetStepAttributes = (
+  events: Event[]
+) => Record<string, unknown> | undefined;
+
 export const stepEventsToStepEntity = (
   events: Event[]
 ): {
@@ -231,7 +235,11 @@ export const stepEventsToStepEntity = (
 /**
  * Converts step events to an OpenTelemetry Span
  */
-export function stepToSpan(stepEvents: Event[], maxEndTime: Date): Span | null {
+export function stepToSpan(
+  stepEvents: Event[],
+  maxEndTime: Date,
+  getStepAttributes?: GetStepAttributes
+): Span | null {
   const step = stepEventsToStepEntity(stepEvents);
   if (!step) {
     return null;
@@ -242,7 +250,11 @@ export function stepToSpan(stepEvents: Event[], maxEndTime: Date): Span | null {
 
   const attributes = {
     resource: 'step' as const,
-    data: step,
+    data: {
+      ...getStepAttributes?.(stepEvents),
+      // Canonical event-derived fields cannot be overridden by extensions.
+      ...step,
+    },
   };
 
   const resource = 'step';

packages/web-shared/src/lib/trace-builder.test.ts

@@ -9,7 +9,11 @@ let nextId = 0;
 
 function event(
   eventType: EventType,
-  options: { correlationId?: string; at: number }
+  options: {
+    correlationId?: string;
+    at: number;
+    externalAttemptId?: string;
+  }
 ): Event {
   nextId += 1;
   return {
@@ -20,6 +24,7 @@ function event(
     createdAt: new Date(BASE_TIME + options.at * 1000),
     occurredAt: new Date(BASE_TIME + options.at * 1000),
     eventData: eventType === 'step_created' ? { stepName: 'doWork' } : {},
+    externalAttemptId: options.externalAttemptId,
   } as unknown as Event;
 }
 
@@ -31,6 +36,42 @@ const run = {
 } as unknown as WorkflowRun;
 
 describe('buildTrace', () => {
+  it('adds caller-derived attributes to step span data', () => {
+    const events = [
+      event('run_created', { at: 0 }),
+      event('run_started', { at: 0 }),
+      event('step_created', { correlationId: 'step_a', at: 1 }),
+      event('step_started', {
+        correlationId: 'step_a',
+        at: 2,
+        externalAttemptId: 'attempt_first',
+      }),
+      event('step_retrying', { correlationId: 'step_a', at: 3 }),
+      event('step_started', {
+        correlationId: 'step_a',
+        at: 4,
+        externalAttemptId: 'attempt_latest',
+      }),
+    ];
+
+    const trace = buildTrace(run, events, new Date(BASE_TIME + 5000), {
+      getStepAttributes(stepEvents) {
+        const latestStart = stepEvents
+          .slice()
+          .reverse()
+          .find((candidate) => candidate.eventType === 'step_started') as
+          | (Event & { externalAttemptId?: string })
+          | undefined;
+        return { externalAttemptId: latestStart?.externalAttemptId };
+      },
+    });
+    const stepSpan = trace.spans.find((span) => span.resource === 'step');
+
+    expect(stepSpan?.attributes.data).toMatchObject({
+      externalAttemptId: 'attempt_latest',
+    });
+  });
+
   it('ends a step span on the terminal event the run acted on', () => {
     const events = [
       event('run_created', { at: 0 }),

packages/web-shared/src/lib/trace-builder.ts

@@ -14,6 +14,7 @@ import {
   type WorkflowRun,
 } from '@workflow/world';
 import {
+  type GetStepAttributes,
   getEventTimestamp,
   hookToSpan,
   runToSpan,
@@ -137,7 +138,8 @@ function buildSpans(
   run: WorkflowRun,
   groupedEvents: GroupedEvents,
   now: Date,
-  latestKnownTime: Date
+  latestKnownTime: Date,
+  getStepAttributes?: GetStepAttributes
 ) {
   // Active child spans cap at latestKnownTime so they don't extend into
   // unknown territory. Even when the run is completed, we may not have loaded
@@ -146,7 +148,7 @@ function buildSpans(
   const runMaxEnd = run.completedAt ?? now;
 
   const stepSpans = Array.from(groupedEvents.eventsByStepId.values())
-    .map((events) => stepToSpan(events, childMaxEnd))
+    .map((events) => stepToSpan(events, childMaxEnd, getStepAttributes))
     .filter((span): span is Span => span !== null);
 
   const hookSpans = Array.from(groupedEvents.hookEvents.values())
@@ -208,7 +210,13 @@ export function buildTrace(
    * from the only copy the caller was given, and dropping the wrong one moves
    * a span. See {@link findDuplicateEventIds}.
    */
-  { isCompleteHistory = false }: { isCompleteHistory?: boolean } = {}
+  {
+    isCompleteHistory = false,
+    getStepAttributes,
+  }: {
+    isCompleteHistory?: boolean;
+    getStepAttributes?: GetStepAttributes;
+  } = {}
 ): TraceWithMeta {
   // Span geometry comes from what the run acted on. A repeat of a class the
   // log already records is read past by every replay, and letting one through
@@ -232,7 +240,8 @@ export function buildTrace(
     run,
     groupedEvents,
     now,
-    latestKnownTime
+    latestKnownTime,
+    getStepAttributes
   );
   const sortedCascadingSpans = cascadeSpans(runSpan, spans);