Implement enhanced stack traces (#820)

Co-authored-by: Nik B <bashkirov.office@gmail.com>
Co-authored-by: James Watkins-Harvey <mjameswh@users.noreply.github.com>

Author: 3 people

package-lock.json

@@ -32,8 +32,3 @@ export function cleanStackTrace(stack: string): string {
   const cleaned = su.clean(stack).trimEnd();
   return stack.split('\n')[0] + '\n' + (cleaned && cleaned.replace(/:\d+:\d+/g, '').replace(/^/gms, '    at '));
 }
-
-export function containsMatching(strings: string[], regex: RegExp): boolean {
-  console.log('strings:', strings);
-  return strings.some((str) => regex.test(str));
-}

packages/test/src/helpers.ts

@@ -1,4 +1,5 @@
 /* eslint @typescript-eslint/no-non-null-assertion: 0 */
+import path from 'node:path';
 import {
   ActivityFailure,
   ApplicationFailure,
@@ -41,6 +42,7 @@ import { ConnectionInjectorInterceptor } from './activities/interceptors';
 import { cleanOptionalStackTrace, u8 } from './helpers';
 import * as workflows from './workflows';
 import { withZeroesHTTPServer } from './zeroes-http-server';
+import { readFileSync } from 'node:fs';
 
 const { EVENT_TYPE_TIMER_STARTED, EVENT_TYPE_TIMER_FIRED, EVENT_TYPE_TIMER_CANCELED } =
   iface.temporal.api.enums.v1.EventType;
@@ -80,6 +82,7 @@ export function runIntegrationTests(codec?: PayloadCodec): void {
       interceptors: {
         activityInbound: [() => new ConnectionInjectorInterceptor(connection, loadDataConverter(dataConverter))],
       },
+      showStackTraceSources: true,
     });
 
     const runPromise = worker.run();
@@ -402,7 +405,8 @@ export function runIntegrationTests(codec?: PayloadCodec): void {
     await workflow.result();
     await t.throwsAsync(workflow.query('not found'), {
       instanceOf: QueryNotRegisteredError,
-      message: 'Workflow did not register a handler for not found. Registered queries: [__stack_trace isBlocked]',
+      message:
+        'Workflow did not register a handler for not found. Registered queries: [__stack_trace __enhanced_stack_trace isBlocked]',
     });
   });
 
@@ -1207,6 +1211,68 @@ export function runIntegrationTests(codec?: PayloadCodec): void {
     at stackTracer (test/src/workflows/stack-tracer.ts)`
       );
     });
+
+    test('Enhanced stack trace returns trace that makes sense', async (t) => {
+      const { client } = t.context;
+      const workflowId = uuid4();
+
+      const enhancedStack = await client.execute(workflows.enhancedStackTracer, {
+        taskQueue: 'test',
+        workflowId,
+      });
+
+      const stacks = enhancedStack.stacks.map((s) => ({
+        locations: s.locations.map((l) => ({
+          ...l,
+          ...(l.filePath ? { filePath: l.filePath.replace(path.resolve(__dirname, '../../../'), '') } : undefined),
+        })),
+      }));
+      t.is(enhancedStack.sdk.name, 'typescript');
+      t.is(enhancedStack.sdk.version, pkg.version); // Expect workflow and worker versions to match
+      t.deepEqual(stacks, [
+        {
+          locations: [
+            {
+              functionName: 'Function.all',
+            },
+            {
+              filePath: '/packages/test/src/workflows/stack-tracer.ts',
+              functionName: 'enhancedStackTracer',
+              line: 32,
+              column: 35,
+            },
+          ],
+        },
+        {
+          locations: [
+            {
+              filePath: '/packages/test/src/workflows/stack-tracer.ts',
+              functionName: 'enhancedStackTracer',
+              line: 32,
+              column: 35,
+            },
+          ],
+        },
+        {
+          locations: [
+            {
+              functionName: 'Promise.then',
+            },
+            {
+              filePath: '/packages/workflow/src/trigger.ts',
+              functionName: 'Trigger.then',
+              line: 47,
+              column: 24,
+            },
+          ],
+        },
+      ]);
+      const expectedSources = ['../src/workflows/stack-tracer.ts', '../../workflow/src/trigger.ts'].map((p) => [
+        path.resolve(__dirname, p),
+        [{ content: readFileSync(path.resolve(__dirname, p), 'utf8'), lineOffset: 0 }],
+      ]);
+      t.deepEqual(Object.entries(enhancedStack.sources), expectedSources);
+    });
   }
 
   test('issue-731', async (t) => {

packages/test/src/integration-tests.ts

@@ -97,6 +97,7 @@ async function createWorkflow(
     randomnessSeed: Long.fromInt(1337).toBytes(),
     now: startTime,
     patches: [],
+    showStackTraceSources: true,
   })) as VMWorkflow;
   return workflow;
 }

packages/test/src/test-workflows.ts

@@ -3,6 +3,7 @@
  * @module
  */
 import * as wf from '@temporalio/workflow';
+import type { EnhancedStackTrace } from '@temporalio/workflow/src/interfaces';
 import type * as activities from '../activities';
 import { unblockOrCancel } from './unblock-or-cancel';
 
@@ -24,3 +25,17 @@ export async function stackTracer(): Promise<[string, string]> {
   const second = await queryOwnWf(wf.stackTraceQuery);
   return [first, second];
 }
+
+export async function enhancedStackTracer(): Promise<EnhancedStackTrace> {
+  const trigger = new wf.Trigger<EnhancedStackTrace>();
+
+  const [enhStack] = await Promise.all([
+    trigger,
+    Promise.race([
+      queryOwnWf(wf.enhancedStackTraceQuery).then((stack) => trigger.resolve(stack)),
+      wf.executeChild(unblockOrCancel),
+      wf.sleep(100_000),
+    ]),
+  ]);
+  return enhStack;
+}

packages/test/src/workflows/stack-tracer.ts

@@ -244,6 +244,13 @@ export interface WorkerOptions {
    */
   enableSDKTracing?: boolean;
 
+  /**
+   * Whether or not to send the sources in enhanced stack trace query responses
+   *
+   * @default false
+   */
+  showStackTraceSources?: boolean;
+
   /**
    * If `true` Worker runs Workflows in the same thread allowing debugger to
    * attach to Workflow instances.
@@ -292,6 +299,7 @@ export type WorkerOptionsWithDefaults = WorkerOptions &
       | 'maxHeartbeatThrottleInterval'
       | 'defaultHeartbeatThrottleInterval'
       | 'enableSDKTracing'
+      | 'showStackTraceSources'
       | 'debugMode'
     >
   > & {
@@ -418,7 +426,7 @@ export function appendDefaultInterceptors(
 }
 
 export function addDefaultWorkerOptions(options: WorkerOptions): WorkerOptionsWithDefaults {
-  const { maxCachedWorkflows, debugMode, ...rest } = options;
+  const { maxCachedWorkflows, showStackTraceSources, debugMode, ...rest } = options;
 
   return {
     namespace: 'default',
@@ -437,6 +445,7 @@ export function addDefaultWorkerOptions(options: WorkerOptions): WorkerOptionsWi
     maxCachedWorkflows:
       maxCachedWorkflows ?? Math.floor(Math.max(v8.getHeapStatistics().heap_size_limit / GiB - 1, 1) * 250),
     enableSDKTracing: false,
+    showStackTraceSources: showStackTraceSources ?? false,
     debugMode: debugMode ?? false,
     interceptors: appendDefaultInterceptors({}),
     sinks: defaultSinks(),

packages/worker/src/worker-options.ts

@@ -1133,6 +1133,7 @@ export class Worker {
                           randomnessSeed: randomnessSeed.toBytes(),
                           now: tsToMs(activation.timestamp),
                           patches,
+                          showStackTraceSources: this.options.showStackTraceSources,
                         });
                       });