@outputai/core 0.2.1-next.fd72d95.0 → 0.3.0

package/src/tracing/processors/local/index.js

@@ -2,6 +2,7 @@ import { appendFileSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFile
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'url';
 import buildTraceTree from '../../tools/build_trace_tree.js';
+import { safeFormatJSON } from '../../tools/utils.js';
 import { EOL } from 'node:os';
 
 const __dirname = dirname( fileURLToPath( import.meta.url ) );
@@ -13,12 +14,32 @@ const callerDir = process.argv[2];
 
 const tempTraceFilesDir = join( __dirname, 'temp', 'traces' );
 
-const accumulate = ( { entry, executionContext: { workflowId, startTime } } ) => {
-  const path = join( tempTraceFilesDir, `${startTime}_${workflowId}.trace` );
-  appendFileSync( path, JSON.stringify( entry ) + EOL, 'utf-8' );
-  return readFileSync( path, 'utf-8' ).split( EOL ).slice( 0, -1 ).map( v => JSON.parse( v ) );
-};
+/**
+ * Builds the temp file path to accumulate trace entries
+ *
+ * @param {object} executionContext - The execution context around a given trace entry
+ * @returns {string}
+ */
+const createTempFilePath = ( { workflowId, startTime } ) => join( tempTraceFilesDir, `${startTime}_${workflowId}.trace` );
 
+/**
+ * Adds a trace entry to the accumulation file.
+ * @param {object} entry - The trace entry
+ * @param {string} path - Accumulation file path
+ */
+const addEntry = ( entry, path ) => appendFileSync( path, JSON.stringify( entry ) + EOL, 'utf-8' );
+
+/**
+ * Reads the accumulation file and returns all the entries, each serialized to JSON
+ * @param {string} path - Accumulation file path
+ * @returns {object[]} Trace entries
+ */
+const getEntries = path => readFileSync( path, 'utf-8' ).split( EOL ).slice( 0, -1 ).map( v => JSON.parse( v ) );
+
+/**
+ * Deletes old accumulation files
+ * @param {number} [threshold] Timestamp in ms epoch. All files below this date are considered old
+ */
 const cleanupOldTempFiles = ( threshold = Date.now() - tempFilesTTL ) =>
   readdirSync( tempTraceFilesDir )
     .filter( f => +f.split( '_' )[0] < threshold )
@@ -79,21 +100,33 @@ export const init = () => {
 /**
  * Execute this processor:
  *
- * Persist a trace tree file to local file system, updating upon each new entry
+ * Appends each trace entry to a temp file.
+ *
+ * When the root workflow ends or the entry is an error action, build the trace tree and write the JSON file.
  *
  * @param {object} args
- * @param {object} entry - Trace event phase
- * @param {object} executionContext - Execution info: workflowId, workflowName, startTime
+ * @param {object} args.entry - The trace entry to append.
+ * @param {object} args.executionContext - Execution info: workflowId, workflowName, startTime
  * @returns {void}
  */
 export const exec = ( { entry, executionContext } ) => {
   const { workflowId, workflowName, startTime } = executionContext;
-  const content = buildTraceTree( accumulate( { entry, executionContext } ) );
+  const tempFilePath = createTempFilePath( executionContext );
+  addEntry( entry, tempFilePath );
+
+  const isRootWorkflowEnd = entry.id === workflowId && entry.action !== 'start';
+  const isError = entry.action === 'error';
+
+  if ( !isRootWorkflowEnd && !isError ) {
+    return;
+  }
+
+  const content = buildTraceTree( getEntries( tempFilePath ) );
   const dir = resolveIOPath( workflowName );
   const path = join( dir, buildTraceFilename( { startTime, workflowId } ) );
 
   mkdirSync( dir, { recursive: true } );
-  writeFileSync( path, JSON.stringify( content, undefined, 2 ) + EOL, 'utf-8' );
+  writeFileSync( path, safeFormatJSON( content ) + EOL, 'utf-8' );
 };
 
 /**

package/src/tracing/processors/local/index.spec.js

@@ -1,4 +1,5 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { EOL } from 'node:os';
 
 // In-memory fs mock store
 const store = { files: new Map() };
@@ -24,12 +25,17 @@ vi.mock( 'node:fs', () => ( {
 const buildTraceTreeMock = vi.fn( entries => ( { count: entries.length } ) );
 vi.mock( '../../tools/build_trace_tree.js', () => ( { default: buildTraceTreeMock } ) );
 
+/** Flush happens when the root id matches workflowId and action is not 'start', or when action is 'error'. */
+const rootStart = ( workflowId, ts ) => ( { id: workflowId, action: 'start', timestamp: ts } );
+const rootEnd = ( workflowId, ts ) => ( { id: workflowId, action: 'end', timestamp: ts } );
+const childTick = ( id, ts ) => ( { id, action: 'tick', timestamp: ts } );
+
 describe( 'tracing/processors/local', () => {
   beforeEach( () => {
     vi.clearAllMocks();
     store.files.clear();
     process.argv[2] = '/tmp/project';
-    delete process.env.OUTPUT_TRACE_HOST_PATH; // Clear OUTPUT_TRACE_HOST_PATH for clean tests
+    delete process.env.OUTPUT_TRACE_HOST_PATH;
   } );
 
   it( 'init(): creates temp dir and cleans up old files', async () => {
@@ -40,34 +46,63 @@ describe( 'tracing/processors/local', () => {
 
     init();
 
-    // Should create temp dir relative to module location using __dirname
     expect( mkdirSyncMock ).toHaveBeenCalledWith( expect.stringMatching( /temp\/traces$/ ), { recursive: true } );
     expect( rmSyncMock ).toHaveBeenCalledTimes( 1 );
   } );
 
-  it( 'exec(): accumulates entries and writes aggregated tree', async () => {
+  it( 'exec(): appends each entry and writes aggregated tree once on root workflow end', async () => {
     const { exec, init } = await import( './index.js' );
     init();
 
     const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
-    const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
+    const workflowId = 'id1';
+    const ctx = { executionContext: { workflowId, workflowName: 'WF', startTime } };
 
-    exec( { ...ctx, entry: { name: 'A', phase: 'start', timestamp: startTime } } );
-    exec( { ...ctx, entry: { name: 'A', phase: 'tick', timestamp: startTime + 1 } } );
-    exec( { ...ctx, entry: { name: 'A', phase: 'end', timestamp: startTime + 2 } } );
+    exec( { ...ctx, entry: rootStart( workflowId, startTime ) } );
+    exec( { ...ctx, entry: childTick( 'child-1', startTime + 1 ) } );
+    exec( { ...ctx, entry: rootEnd( workflowId, startTime + 2 ) } );
 
-    // buildTraceTree called with 1, 2, 3 entries respectively
-    expect( buildTraceTreeMock ).toHaveBeenCalledTimes( 3 );
-    expect( buildTraceTreeMock.mock.calls.at( -1 )[0].length ).toBe( 3 );
+    expect( buildTraceTreeMock ).toHaveBeenCalledTimes( 1 );
+    expect( buildTraceTreeMock.mock.calls[0][0] ).toHaveLength( 3 );
 
-    expect( writeFileSyncMock ).toHaveBeenCalledTimes( 3 );
-    const [ writtenPath, content ] = writeFileSyncMock.mock.calls.at( -1 );
-    // Changed: Now uses process.cwd() + '/logs' fallback when OUTPUT_TRACE_HOST_PATH not set
-    expect( writtenPath ).toMatch( /\/runs\/WF\// );
+    expect( writeFileSyncMock ).toHaveBeenCalledTimes( 1 );
+    const [ writtenPath, content ] = writeFileSyncMock.mock.calls[0];
+    expect( writtenPath ).toMatch( /\/tmp\/project\/logs\/runs\/WF\// );
     expect( JSON.parse( content.trim() ).count ).toBe( 3 );
   } );
 
-  it( 'getDestination(): returns absolute path', async () => {
+  it( 'exec(): does not build or write on non-flush entries', async () => {
+    const { exec, init } = await import( './index.js' );
+    init();
+
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const workflowId = 'id1';
+    const ctx = { executionContext: { workflowId, workflowName: 'WF', startTime } };
+
+    exec( { ...ctx, entry: rootStart( workflowId, startTime ) } );
+    exec( { ...ctx, entry: childTick( 'child-1', startTime + 1 ) } );
+
+    expect( buildTraceTreeMock ).not.toHaveBeenCalled();
+    expect( writeFileSyncMock ).not.toHaveBeenCalled();
+  } );
+
+  it( 'exec(): flushes on error action before root end', async () => {
+    const { exec, init } = await import( './index.js' );
+    init();
+
+    const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
+    const workflowId = 'id1';
+    const ctx = { executionContext: { workflowId, workflowName: 'WF', startTime } };
+
+    exec( { ...ctx, entry: rootStart( workflowId, startTime ) } );
+    exec( { ...ctx, entry: { id: 'step-1', action: 'error', timestamp: startTime + 1 } } );
+
+    expect( buildTraceTreeMock ).toHaveBeenCalledTimes( 1 );
+    expect( buildTraceTreeMock.mock.calls[0][0] ).toHaveLength( 2 );
+    expect( writeFileSyncMock ).toHaveBeenCalledTimes( 1 );
+  } );
+
+  it( 'getDestination(): returns absolute path under callerDir logs', async () => {
     const { getDestination } = await import( './index.js' );
 
     const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
@@ -76,36 +111,36 @@ describe( 'tracing/processors/local', () => {
 
     const destination = getDestination( { startTime, workflowId, workflowName } );
 
-    // Should return an absolute path
-    expect( destination ).toMatch( /^\/|^[A-Z]:\\/i ); // Starting with / or Windows drive letter
-    expect( destination ).toContain( '/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
+    expect( destination ).toMatch( /^\/|^[A-Z]:\\/i );
+    expect( destination ).toBe(
+      '/tmp/project/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json'
+    );
   } );
 
-  it( 'exec(): writes to container path regardless of OUTPUT_TRACE_HOST_PATH', async () => {
+  it( 'exec(): writes under process.argv[2] logs even when OUTPUT_TRACE_HOST_PATH is set', async () => {
     const { exec, init } = await import( './index.js' );
 
-    // Set OUTPUT_TRACE_HOST_PATH to simulate Docker environment
     process.env.OUTPUT_TRACE_HOST_PATH = '/host/path/logs';
 
     init();
 
     const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
-    const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
+    const workflowId = 'id1';
+    const ctx = { executionContext: { workflowId, workflowName: 'WF', startTime } };
 
-    exec( { ...ctx, entry: { name: 'A', phase: 'start', timestamp: startTime } } );
+    exec( { ...ctx, entry: rootStart( workflowId, startTime ) } );
+    exec( { ...ctx, entry: rootEnd( workflowId, startTime + 1 ) } );
 
     expect( writeFileSyncMock ).toHaveBeenCalledTimes( 1 );
-    const [ writtenPath ] = writeFileSyncMock.mock.calls.at( -1 );
+    const [ writtenPath ] = writeFileSyncMock.mock.calls[0];
 
-    // Should write to process.cwd()/logs, NOT to OUTPUT_TRACE_HOST_PATH
     expect( writtenPath ).not.toContain( '/host/path/logs' );
-    expect( writtenPath ).toMatch( /logs\/runs\/WF\// );
+    expect( writtenPath ).toMatch( /\/tmp\/project\/logs\/runs\/WF\// );
   } );
 
   it( 'getDestination(): returns OUTPUT_TRACE_HOST_PATH when set', async () => {
     const { getDestination } = await import( './index.js' );
 
-    // Set OUTPUT_TRACE_HOST_PATH to simulate Docker environment
     process.env.OUTPUT_TRACE_HOST_PATH = '/host/path/logs';
 
     const startTime = Date.parse( '2020-01-02T03:04:05.678Z' );
@@ -114,14 +149,12 @@ describe( 'tracing/processors/local', () => {
 
     const destination = getDestination( { startTime, workflowId, workflowName } );
 
-    // Should return OUTPUT_TRACE_HOST_PATH-based path for reporting
     expect( destination ).toBe( '/host/path/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
   } );
 
   it( 'separation of write and report paths works correctly', async () => {
     const { exec, getDestination, init } = await import( './index.js' );
 
-    // Set OUTPUT_TRACE_HOST_PATH to simulate Docker environment
     process.env.OUTPUT_TRACE_HOST_PATH = '/Users/ben/project/logs';
 
     init();
@@ -131,19 +164,16 @@ describe( 'tracing/processors/local', () => {
     const workflowName = 'test-workflow';
     const ctx = { executionContext: { workflowId, workflowName, startTime } };
 
-    // Execute to write file
-    exec( { ...ctx, entry: { name: 'A', phase: 'start', timestamp: startTime } } );
+    exec( { ...ctx, entry: rootStart( workflowId, startTime ) } );
+    exec( { ...ctx, entry: rootEnd( workflowId, startTime + 1 ) } );
 
-    // Get destination for reporting
     const destination = getDestination( { startTime, workflowId, workflowName } );
 
-    // Verify write path is local
-    const [ writtenPath ] = writeFileSyncMock.mock.calls.at( -1 );
+    const [ writtenPath, payload ] = writeFileSyncMock.mock.calls[0];
     expect( writtenPath ).not.toContain( '/Users/ben/project' );
-    expect( writtenPath ).toMatch( /logs\/runs\/test-workflow\// );
+    expect( writtenPath ).toMatch( /\/tmp\/project\/logs\/runs\/test-workflow\// );
+    expect( payload.endsWith( EOL ) ).toBe( true );
 
-    // Verify report path uses OUTPUT_TRACE_HOST_PATH
     expect( destination ).toBe( '/Users/ben/project/logs/runs/test-workflow/2020-01-02-03-04-05-678Z_workflow-id-123.json' );
   } );
 } );
-

package/src/tracing/processors/s3/index.js

@@ -4,6 +4,7 @@ import buildTraceTree from '../../tools/build_trace_tree.js';
 import { EOL } from 'node:os';
 import { loadEnv, getVars } from './configs.js';
 import { createChildLogger } from '#logger';
+import { safeFormatJSON } from '../../tools/utils.js';
 
 const log = createChildLogger( 'S3 Processor' );
 
@@ -66,11 +67,15 @@ export const init = async () => {
 };
 
 /**
- * Execute this processor: send a complete trace tree file to S3 when the workflow finishes
+ * Execute this processor:
+ *
+ * Appends each trace entry to Redis.
+ *
+ * When the root workflow ends or the entry is an error action, it builds the trace tree and uploads it to S3.
  *
  * @param {object} args
- * @param {object} entry - Trace event phase
- * @param {object} executionContext - Execution info: workflowId, workflowName, startTime
+ * @param {object} args.entry - The trace entry to append
+ * @param {object} args.executionContext - Execution info: workflowId, workflowName, startTime
  */
 export const exec = async ( { entry, executionContext } ) => {
   const { workflowName, workflowId, startTime } = executionContext;
@@ -78,7 +83,7 @@ export const exec = async ( { entry, executionContext } ) => {
 
   await addEntry( entry, cacheKey );
 
-  const isRootWorkflowEnd = entry.id === workflowId && entry.phase !== 'start';
+  const isRootWorkflowEnd = entry.id === workflowId && entry.action !== 'start';
   if ( !isRootWorkflowEnd ) {
     return;
   }
@@ -97,7 +102,7 @@ export const exec = async ( { entry, executionContext } ) => {
   }
   await upload( {
     key: getS3Key( { workflowId, workflowName, startTime } ),
-    content: JSON.stringify( content, undefined, 2 ) + EOL
+    content: safeFormatJSON( content ) + EOL
   } );
   await bustEntries( cacheKey );
 };

package/src/tracing/processors/s3/index.spec.js

@@ -52,9 +52,9 @@ describe( 'tracing/processors/s3', () => {
 
     redisMulti.exec.mockResolvedValue( [] );
 
-    const workflowStart = { id: 'id1', name: 'WF', kind: 'workflow', phase: 'start', details: {}, timestamp: startTime };
-    const activityStart = { id: 'act-1', name: 'DoSomething', kind: 'step', parentId: 'id1', phase: 'start', details: {}, timestamp: startTime + 1 };
-    const workflowEnd = { id: 'id1', phase: 'end', details: { ok: true }, timestamp: startTime + 2 };
+    const workflowStart = { id: 'id1', name: 'WF', kind: 'workflow', action: 'start', details: {}, timestamp: startTime };
+    const activityStart = { id: 'act-1', name: 'DoSomething', kind: 'step', parentId: 'id1', action: 'start', details: {}, timestamp: startTime + 1 };
+    const workflowEnd = { id: 'id1', action: 'end', details: { ok: true }, timestamp: startTime + 2 };
     zRangeMock.mockResolvedValue( [
       JSON.stringify( workflowStart ),
       JSON.stringify( activityStart ),
@@ -97,7 +97,7 @@ describe( 'tracing/processors/s3', () => {
 
     redisMulti.exec.mockResolvedValue( [] );
     const workflowStart = {
-      kind: 'workflow', id: 'id1', name: 'WF', parentId: undefined, phase: 'start', details: {}, timestamp: startTime
+      kind: 'workflow', id: 'id1', name: 'WF', parentId: undefined, action: 'start', details: {}, timestamp: startTime
     };
     zRangeMock.mockResolvedValue( [ JSON.stringify( workflowStart ) ] );
 
@@ -113,8 +113,8 @@ describe( 'tracing/processors/s3', () => {
     const ctx = { executionContext: { workflowId: 'id1', workflowName: 'WF', startTime } };
 
     redisMulti.exec.mockResolvedValue( [] );
-    const workflowStart = { id: 'id1', name: 'WF', kind: 'workflow', phase: 'start', details: {}, timestamp: startTime };
-    const stepEndNoParent = { id: 'step-1', phase: 'end', details: { done: true }, timestamp: startTime + 1 };
+    const workflowStart = { id: 'id1', name: 'WF', kind: 'workflow', action: 'start', details: {}, timestamp: startTime };
+    const stepEndNoParent = { id: 'step-1', action: 'end', details: { done: true }, timestamp: startTime + 1 };
     zRangeMock.mockResolvedValue( [
       JSON.stringify( workflowStart ),
       JSON.stringify( stepEndNoParent )
@@ -136,7 +136,7 @@ describe( 'tracing/processors/s3', () => {
 
     redisMulti.exec.mockResolvedValue( [] );
     const workflowEnd = {
-      kind: 'workflow', id: 'id1', name: 'WF', parentId: undefined, phase: 'end', details: {}, timestamp: startTime
+      kind: 'workflow', id: 'id1', name: 'WF', parentId: undefined, action: 'end', details: {}, timestamp: startTime
     };
     zRangeMock.mockResolvedValue( [ JSON.stringify( workflowEnd ) ] );
     buildTraceTreeMock.mockReturnValueOnce( null );

package/src/tracing/tools/build_trace_tree.js

@@ -1,3 +1,4 @@
+import { EventAction } from '../trace_consts.js';
 /**
  * @typedef {object} NodeEntry
  * @property {string} id
@@ -27,19 +28,21 @@ const createEntry = id => ( {
   input: undefined,
   output: undefined,
   error: undefined,
-  children: []
+  children: [],
+  attributes: {}
 } );
 
 /**
- * Build a tree of nodes from a list of entries
+ * Builds a tree of nodes from a list of entries.
  *
  * Each node will have: id, name, kind, children, input, output or error, startedAt, endedAt.
  *
- * Entries with same id will be combined according to their phase (start, end OR error).
- * - The details of the start phase becomes input, timestamp becomes startedAt;
- * - The details of the end phase become output, timestamp becomes endedAt;
- * - The details of the error phase become error, timestamp becomes endedAt;
- * - Only start phase's kind and name are used;
+ * Entries with the same id are combined according to their actions.
+ * - The details of the START action become input, and timestamp becomes startedAt;
+ * - The details of the END action become output, timestamp becomes endedAt;
+ * - The details of the ERROR action become error, timestamp becomes endedAt;
+ * - The details of the ADD_ATTR action are attached to `.attributes`;
+ * - Only the START action's `kind` and `name` fields are used;
  *
  *
  * Children are added according to the parentId of each entry.
@@ -53,18 +56,20 @@ export default entries => {
   const ensureNode = id => nodes.get( id ) ?? nodes.set( id, createEntry( id ) ).get( id );
 
   for ( const entry of entries ) {
-    const { kind, id, name, parentId, details, phase, timestamp } = entry;
+    const { kind, id, name, parentId, details, action, timestamp } = entry;
     const node = ensureNode( id );
 
-    if ( phase === 'start' ) {
+    if ( action === EventAction.START ) {
       Object.assign( node, { input: details, startedAt: timestamp, kind, name } );
-    } else if ( phase === 'end' ) {
+    } else if ( action === EventAction.ADD_ATTR ) {
+      node.attributes[details.name] = details.value;
+    } else if ( action === EventAction.END ) {
       Object.assign( node, { output: details, endedAt: timestamp } );
-    } else if ( phase === 'error' ) {
+    } else if ( action === EventAction.ERROR ) {
       Object.assign( node, { error: details, endedAt: timestamp } );
     }
 
-    if ( parentId && phase === 'start' ) {
+    if ( parentId && action === EventAction.START ) {
       const parent = ensureNode( parentId );
       parent.children.push( node );
       parent.children.sort( ( a, b ) => a.startedAt - b.startedAt );

package/src/tracing/tools/build_trace_tree.spec.js

@@ -1,4 +1,5 @@
 import { describe, it, expect } from 'vitest';
+import { EventAction } from '../trace_consts.js';
 import buildTraceTree from './build_trace_tree.js';
 
 describe( 'build_trace_tree', () => {
@@ -6,9 +7,9 @@ describe( 'build_trace_tree', () => {
     expect( buildTraceTree( [] ) ).toBeNull();
   } );
 
-  it( 'sets root output with a fixed message when workflow has no end/error phase yet', () => {
+  it( 'sets root output with a fixed message when workflow has no end/error action yet', () => {
     const entries = [
-      { kind: 'workflow', id: 'wf', parentId: undefined, phase: 'start', name: 'wf', details: {}, timestamp: 1000 }
+      { kind: 'workflow', id: 'wf', parentId: undefined, action: EventAction.START, name: 'wf', details: {}, timestamp: 1000 }
     ];
     const result = buildTraceTree( entries );
     expect( result ).not.toBeNull();
@@ -19,17 +20,52 @@ this can indicate it timed out or was interrupted.>>' );
 
   it( 'returns null when there is no root (all entries have parentId)', () => {
     const entries = [
-      { id: 'a', parentId: 'x', phase: 'start', name: 'a', timestamp: 1 },
-      { id: 'b', parentId: 'a', phase: 'start', name: 'b', timestamp: 2 }
+      { id: 'a', parentId: 'x', action: EventAction.START, name: 'a', timestamp: 1 },
+      { id: 'b', parentId: 'a', action: EventAction.START, name: 'b', timestamp: 2 }
     ];
     expect( buildTraceTree( entries ) ).toBeNull();
   } );
 
-  it( 'error phase sets error and endedAt on node', () => {
+  it( 'add_attr action merges details.name and details.value into node.attributes', () => {
     const entries = [
-      { kind: 'wf', id: 'r', parentId: undefined, phase: 'start', name: 'root', details: {}, timestamp: 100 },
-      { kind: 'step', id: 's', parentId: 'r', phase: 'start', name: 'step', details: {}, timestamp: 200 },
-      { id: 's', phase: 'error', details: { message: 'failed' }, timestamp: 300 }
+      { kind: 'workflow', id: 'wf', parentId: undefined, action: EventAction.START, name: 'wf', details: {}, timestamp: 100 },
+      { kind: 'step', id: 's', parentId: 'wf', action: EventAction.START, name: 'step', details: {}, timestamp: 200 },
+      { id: 's', action: EventAction.ADD_ATTR, details: { name: 'latency_ms', value: 42 }, timestamp: 250 },
+      { id: 's', action: EventAction.ADD_ATTR, details: { name: 'retries', value: 1 }, timestamp: 260 },
+      { id: 'wf', action: EventAction.END, details: {}, timestamp: 300 }
+    ];
+    const result = buildTraceTree( entries );
+    expect( result ).not.toBeNull();
+    expect( result.children[0].attributes ).toEqual( { latency_ms: 42, retries: 1 } );
+  } );
+
+  it( 'add_attr action overwrites prior value for the same attribute name', () => {
+    const entries = [
+      { kind: 'workflow', id: 'wf', parentId: undefined, action: EventAction.START, name: 'wf', details: {}, timestamp: 1 },
+      { id: 'wf', action: EventAction.ADD_ATTR, details: { name: 'x', value: 1 }, timestamp: 2 },
+      { id: 'wf', action: EventAction.ADD_ATTR, details: { name: 'x', value: 2 }, timestamp: 3 },
+      { id: 'wf', action: EventAction.END, details: {}, timestamp: 4 }
+    ];
+    const result = buildTraceTree( entries );
+    expect( result.attributes ).toEqual( { x: 2 } );
+  } );
+
+  it( 'add_attr does not attach nodes as children (only start does)', () => {
+    const entries = [
+      { kind: 'workflow', id: 'wf', parentId: undefined, action: EventAction.START, name: 'wf', details: {}, timestamp: 1 },
+      { id: 'orphan', parentId: 'wf', action: EventAction.ADD_ATTR, details: { name: 'k', value: 'v' }, timestamp: 2 },
+      { id: 'wf', action: EventAction.END, details: {}, timestamp: 3 }
+    ];
+    const result = buildTraceTree( entries );
+    expect( result.children ).toHaveLength( 0 );
+    expect( result.attributes ).toEqual( {} );
+  } );
+
+  it( 'error action sets error and endedAt on node', () => {
+    const entries = [
+      { kind: 'wf', id: 'r', parentId: undefined, action: EventAction.START, name: 'root', details: {}, timestamp: 100 },
+      { kind: 'step', id: 's', parentId: 'r', action: EventAction.START, name: 'step', details: {}, timestamp: 200 },
+      { id: 's', action: EventAction.ERROR, details: { message: 'failed' }, timestamp: 300 }
     ];
     const result = buildTraceTree( entries );
     expect( result ).not.toBeNull();
@@ -41,27 +77,28 @@ this can indicate it timed out or was interrupted.>>' );
   it( 'builds a tree from workflow/step/IO entries with grouping and sorting', () => {
     const entries = [
       // workflow start
-      { kind: 'workflow', phase: 'start', name: 'wf', id: 'wf', parentId: undefined, details: { a: 1 }, timestamp: 1000 },
+      { kind: 'workflow', action: EventAction.START, name: 'wf', id: 'wf', parentId: undefined, details: { a: 1 }, timestamp: 1000 },
       // evaluator start/stop
-      { kind: 'evaluator', phase: 'start', name: 'eval', id: 'eval', parentId: 'wf', details: { z: 0 }, timestamp: 1500 },
-      { id: 'eval', phase: 'end', details: { z: 1 }, timestamp: 1600 },
+      { kind: 'evaluator', action: EventAction.START, name: 'eval', id: 'eval', parentId: 'wf', details: { z: 0 }, timestamp: 1500 },
+      { id: 'eval', action: EventAction.END, details: { z: 1 }, timestamp: 1600 },
       // step1 start
-      { kind: 'step', phase: 'start', name: 'step-1', id: 's1', parentId: 'wf', details: { x: 1 }, timestamp: 2000 },
+      { kind: 'step', action: EventAction.START, name: 'step-1', id: 's1', parentId: 'wf', details: { x: 1 }, timestamp: 2000 },
+      { id: 's1', action: EventAction.ADD_ATTR, details: { name: 'step_tag', value: 'alpha' }, timestamp: 2050 },
       // IO under step1
-      { kind: 'IO', phase: 'start', name: 'test-1', id: 'io1', parentId: 's1', details: { y: 2 }, timestamp: 2300 },
+      { kind: 'IO', action: EventAction.START, name: 'test-1', id: 'io1', parentId: 's1', details: { y: 2 }, timestamp: 2300 },
       // step2 start
-      { kind: 'step', phase: 'start', name: 'step-2', id: 's2', parentId: 'wf', details: { x: 2 }, timestamp: 2400 },
+      { kind: 'step', action: EventAction.START, name: 'step-2', id: 's2', parentId: 'wf', details: { x: 2 }, timestamp: 2400 },
       // IO under step2
-      { kind: 'IO', phase: 'start', name: 'test-2', id: 'io2', parentId: 's2', details: { y: 3 }, timestamp: 2500 },
-      { id: 'io2', phase: 'end', details: { y: 4 }, timestamp: 2600 },
+      { kind: 'IO', action: EventAction.START, name: 'test-2', id: 'io2', parentId: 's2', details: { y: 3 }, timestamp: 2500 },
+      { id: 'io2', action: EventAction.END, details: { y: 4 }, timestamp: 2600 },
       // IO under step1 ends
-      { id: 'io1', phase: 'end', details: { y: 5 }, timestamp: 2700 },
+      { id: 'io1', action: EventAction.END, details: { y: 5 }, timestamp: 2700 },
       // step1 end
-      { id: 's1', phase: 'end', details: { done: true }, timestamp: 2800 },
+      { id: 's1', action: EventAction.END, details: { done: true }, timestamp: 2800 },
       // step2 end
-      { id: 's2', phase: 'end', details: { done: true }, timestamp: 2900 },
+      { id: 's2', action: EventAction.END, details: { done: true }, timestamp: 2900 },
       // workflow end
-      { id: 'wf', phase: 'end', details: { ok: true }, timestamp: 3000 }
+      { id: 'wf', action: EventAction.END, details: { ok: true }, timestamp: 3000 }
     ];
 
     const result = buildTraceTree( entries );
@@ -74,6 +111,7 @@ this can indicate it timed out or was interrupted.>>' );
       endedAt: 3000,
       input: { a: 1 },
       output: { ok: true },
+      attributes: {},
       children: [
         {
           id: 'eval',
@@ -83,6 +121,7 @@ this can indicate it timed out or was interrupted.>>' );
           endedAt: 1600,
           input: { z: 0 },
           output: { z: 1 },
+          attributes: {},
           children: []
         },
         {
@@ -93,6 +132,7 @@ this can indicate it timed out or was interrupted.>>' );
           endedAt: 2800,
           input: { x: 1 },
           output: { done: true },
+          attributes: { step_tag: 'alpha' },
           children: [
             {
               id: 'io1',
@@ -102,6 +142,7 @@ this can indicate it timed out or was interrupted.>>' );
               endedAt: 2700,
               input: { y: 2 },
               output: { y: 5 },
+              attributes: {},
               children: []
             }
           ]
@@ -114,6 +155,7 @@ this can indicate it timed out or was interrupted.>>' );
           endedAt: 2900,
           input: { x: 2 },
           output: { done: true },
+          attributes: {},
           children: [
             {
               id: 'io2',
@@ -123,6 +165,7 @@ this can indicate it timed out or was interrupted.>>' );
               endedAt: 2600,
               input: { y: 3 },
               output: { y: 4 },
+              attributes: {},
               children: []
             }
           ]

package/src/tracing/tools/utils.js

@@ -19,3 +19,31 @@ export const serializeError = error =>
     message: error.message,
     stack: error.stack
   };
+
+/**
+ * Tries to stringify an object to an indented JSON string.
+ * If its byte size is bigger than threshold returns a plain JSON string without formatting.
+ *
+ * @param {object|array} content
+ * @param {*} [threshold] - The max allowed size to try to stringify with formatting (in bytes). Default is 50mb
+ * @returns {string} String representation of the object
+ */
+export const safeFormatJSON = ( content, threshold = 50 * 1024 * 1024 /* 50mb */ ) => {
+  const plainString = JSON.stringify( content );
+  const plainStringSize = Buffer.byteLength( plainString, 'utf8' );
+
+  if ( plainStringSize > threshold ) {
+    return plainString;
+  }
+  try {
+    return JSON.stringify( content, undefined, 2 );
+  } catch ( error ) {
+    // Only handles this specific error because other common parsing errors like:
+    // "TypeError: cyclic object value" and "RangeError: Maximum call stack size exceeded"
+    // would have been thrown on the first parsing.
+    if ( error instanceof RangeError && error.message === 'Invalid string length' ) {
+      return plainString;
+    }
+    throw error;
+  }
+};