fix: add exit handler to profiler (#1221)

Author: BioPhoton

packages/utils/docs/profiler.md

@@ -6,6 +6,15 @@
 
 The `Profiler` class provides a clean, type-safe API for performance monitoring that integrates seamlessly with Chrome DevTools. It supports both synchronous and asynchronous operations with smart defaults for custom track visualization, enabling developers to track performance bottlenecks and optimize application speed.
 
+### Features
+
+- **Type-Safe API**: Fully typed UserTiming API for [Chrome DevTools Extensibility API](https://developer.chrome.com/docs/devtools/performance/extension)
+- **Measure API**: Easy-to-use methods for measuring synchronous and asynchronous code execution times.
+- **Custom Track Configuration**: Fully typed reusable configurations for custom track visualization.
+- **Process buffered entries**: Captures and processes buffered profiling entries.
+- **3rd Party Profiling**: Automatically processes third-party performance entries.
+- **Clean measure names**: Automatically adds prefixes to measure names, as well as start/end postfix to marks, for better organization.
+
 ## Getting started
 
 1. If you haven't already, install [@code-pushup/utils](../../README.md).
@@ -257,10 +266,23 @@ const saved = profiler.measure('save-user', () => saveToDb(user), {
 
 ## NodeJSProfiler
 
-This profiler extends all options and API from Profiler with automatic process exit handling for buffered performance data.
+### Features
+
+- **Crash-safe Write Ahead Log**: Ensures profiling data is saved even if the application crashes.
+- **Recoverable Profiles**: Ability to resume profiling sessions after interruptions or crash.
+- **Automatic Trace Generation**: Generates trace files compatible with Chrome DevTools for in-depth performance analysis.
+- **Multiprocess Support**: Designed to handle profiling over sharded WAL.
+- **Controllable over env vars**: Easily enable or disable profiling through environment variables.
 
+This profiler extends all options and API from Profiler with automatic process exit handling for buffered performance data.
 The NodeJSProfiler automatically subscribes to performance observation and installs exit handlers that flush buffered data on process termination (signals, fatal errors, or normal exit).
 
+### Exit Handlers
+
+The profiler automatically subscribes to process events (`exit`, `SIGINT`, `SIGTERM`, `SIGQUIT`, `uncaughtException`, `unhandledRejection`) during construction. When any of these occur, the handlers call `close()` to ensure buffered data is flushed.
+
+The `close()` method is idempotent and safe to call from exit handlers. It unsubscribes from exit handlers, closes the WAL sink, and unsubscribes from the performance observer, ensuring all buffered performance data is written before process termination.
+
 ## Configuration
 
 ```ts

packages/utils/mocks/sink.mock.ts

@@ -51,4 +51,8 @@ export class MockTraceEventFileSink extends MockAppendableSink {
   repack = vi.fn((): void => {});
 
   finalize = vi.fn((): void => {});
+
+  getPath = vi.fn((): string => {
+    return '/test/tmp/profiles/default/trace.default.jsonl';
+  });
 }

packages/utils/src/lib/exit-process.int.test.ts

@@ -1,7 +1,7 @@
 import process from 'node:process';
-import { SIGNAL_EXIT_CODES, installExitHandlers } from './exit-process.js';
+import { SIGNAL_EXIT_CODES, subscribeProcessExit } from './exit-process.js';
 
-describe('installExitHandlers', () => {
+describe('subscribeProcessExit', () => {
   const onError = vi.fn();
   const onExit = vi.fn();
   const processOnSpy = vi.spyOn(process, 'on');
@@ -25,7 +25,7 @@ describe('installExitHandlers', () => {
   });
 
   it('should install event listeners for all expected events', () => {
-    expect(() => installExitHandlers({ onError, onExit })).not.toThrow();
+    expect(() => subscribeProcessExit({ onError, onExit })).not.toThrow();
 
     expect(processOnSpy).toHaveBeenCalledWith(
       'uncaughtException',
@@ -42,7 +42,7 @@ describe('installExitHandlers', () => {
   });
 
   it('should call onError with error and kind for uncaughtException', () => {
-    expect(() => installExitHandlers({ onError })).not.toThrow();
+    expect(() => subscribeProcessExit({ onError })).not.toThrow();
 
     const testError = new Error('Test uncaught exception');
 
@@ -54,7 +54,7 @@ describe('installExitHandlers', () => {
   });
 
   it('should call onError with reason and kind for unhandledRejection', () => {
-    expect(() => installExitHandlers({ onError })).not.toThrow();
+    expect(() => subscribeProcessExit({ onError })).not.toThrow();
 
     const testReason = 'Test unhandled rejection';
 
@@ -66,7 +66,7 @@ describe('installExitHandlers', () => {
   });
 
   it('should call onExit and exit with code 0 for SIGINT', () => {
-    expect(() => installExitHandlers({ onExit })).not.toThrow();
+    expect(() => subscribeProcessExit({ onExit })).not.toThrow();
 
     (process as any).emit('SIGINT');
 
@@ -79,7 +79,7 @@ describe('installExitHandlers', () => {
   });
 
   it('should call onExit and exit with code 0 for SIGTERM', () => {
-    expect(() => installExitHandlers({ onExit })).not.toThrow();
+    expect(() => subscribeProcessExit({ onExit })).not.toThrow();
 
     (process as any).emit('SIGTERM');
 
@@ -92,7 +92,7 @@ describe('installExitHandlers', () => {
   });
 
   it('should call onExit and exit with code 0 for SIGQUIT', () => {
-    expect(() => installExitHandlers({ onExit })).not.toThrow();
+    expect(() => subscribeProcessExit({ onExit })).not.toThrow();
 
     (process as any).emit('SIGQUIT');
 
@@ -105,7 +105,7 @@ describe('installExitHandlers', () => {
   });
 
   it('should call onExit for successful process termination with exit code 0', () => {
-    expect(() => installExitHandlers({ onExit })).not.toThrow();
+    expect(() => subscribeProcessExit({ onExit })).not.toThrow();
 
     (process as any).emit('exit', 0);
 
@@ -116,7 +116,7 @@ describe('installExitHandlers', () => {
   });
 
   it('should call onExit for failed process termination with exit code 1', () => {
-    expect(() => installExitHandlers({ onExit })).not.toThrow();
+    expect(() => subscribeProcessExit({ onExit })).not.toThrow();
 
     (process as any).emit('exit', 1);
 

packages/utils/src/lib/exit-process.ts

@@ -38,7 +38,20 @@ export type ExitHandlerOptions = {
   fatalExitCode?: number;
 };
 
-export function installExitHandlers(options: ExitHandlerOptions = {}): void {
+/**
+ *
+ * @param options - Options for the exit handler
+ * @param options.onExit - Callback to be called when the process exits
+ * @param options.onError - Callback to be called when an error occurs
+ * @param options.exitOnFatal - Whether to exit the process on fatal errors
+ * @param options.exitOnSignal - Whether to exit the process on signals
+ * @param options.fatalExitCode - The exit code to use for fatal errors
+ * @returns A function to unsubscribe from the exit handlers
+ */
+// eslint-disable-next-line max-lines-per-function
+export function subscribeProcessExit(
+  options: ExitHandlerOptions = {},
+): () => void {
   // eslint-disable-next-line functional/no-let
   let closedReason: CloseReason | undefined;
   const {
@@ -57,40 +70,57 @@ export function installExitHandlers(options: ExitHandlerOptions = {}): void {
     onExit?.(code, reason);
   };
 
-  process.on('uncaughtException', err => {
+  const uncaughtExceptionHandler = (err: unknown) => {
     onError?.(err, 'uncaughtException');
     if (exitOnFatal) {
       close(fatalExitCode, {
         kind: 'fatal',
         fatal: 'uncaughtException',
       });
     }
-  });
+  };
 
-  process.on('unhandledRejection', reason => {
+  const unhandledRejectionHandler = (reason: unknown) => {
     onError?.(reason, 'unhandledRejection');
     if (exitOnFatal) {
       close(fatalExitCode, {
         kind: 'fatal',
         fatal: 'unhandledRejection',
       });
     }
-  });
+  };
 
-  (['SIGINT', 'SIGTERM', 'SIGQUIT'] as const).forEach(signal => {
-    process.on(signal, () => {
-      close(SIGNAL_EXIT_CODES()[signal], { kind: 'signal', signal });
-      if (exitOnSignal) {
-        // eslint-disable-next-line n/no-process-exit
-        process.exit(SIGNAL_EXIT_CODES()[signal]);
-      }
-    });
-  });
+  const signalHandlers = (['SIGINT', 'SIGTERM', 'SIGQUIT'] as const).map(
+    signal => {
+      const handler = () => {
+        close(SIGNAL_EXIT_CODES()[signal], { kind: 'signal', signal });
+        if (exitOnSignal) {
+          // eslint-disable-next-line unicorn/no-process-exit,n/no-process-exit
+          process.exit(SIGNAL_EXIT_CODES()[signal]);
+        }
+      };
+      process.on(signal, handler);
+      return { signal, handler };
+    },
+  );
 
-  process.on('exit', code => {
+  const exitHandler = (code: number) => {
     if (closedReason) {
       return;
     }
     close(code, { kind: 'exit' });
-  });
+  };
+
+  process.on('uncaughtException', uncaughtExceptionHandler);
+  process.on('unhandledRejection', unhandledRejectionHandler);
+  process.on('exit', exitHandler);
+
+  return () => {
+    process.removeListener('uncaughtException', uncaughtExceptionHandler);
+    process.removeListener('unhandledRejection', unhandledRejectionHandler);
+    process.removeListener('exit', exitHandler);
+    signalHandlers.forEach(({ signal, handler }) => {
+      process.removeListener(signal, handler);
+    });
+  };
 }

packages/utils/src/lib/exit-process.unit.test.ts

@@ -1,8 +1,8 @@
 import os from 'node:os';
 import process from 'node:process';
-import { SIGNAL_EXIT_CODES, installExitHandlers } from './exit-process.js';
+import { SIGNAL_EXIT_CODES, subscribeProcessExit } from './exit-process.js';
 
-describe('exit-process tests', () => {
+describe('subscribeProcessExit', () => {
   const onError = vi.fn();
   const onExit = vi.fn();
   const processOnSpy = vi.spyOn(process, 'on');
@@ -26,7 +26,7 @@ describe('exit-process tests', () => {
   });
 
   it('should install event listeners for all expected events', () => {
-    expect(() => installExitHandlers({ onError, onExit })).not.toThrow();
+    expect(() => subscribeProcessExit({ onError, onExit })).not.toThrow();
 
     expect(processOnSpy).toHaveBeenCalledWith(
       'uncaughtException',
@@ -43,7 +43,7 @@ describe('exit-process tests', () => {
   });
 
   it('should call onError with error and kind for uncaughtException', () => {
-    expect(() => installExitHandlers({ onError })).not.toThrow();
+    expect(() => subscribeProcessExit({ onError })).not.toThrow();
 
     const testError = new Error('Test uncaught exception');
 
@@ -55,7 +55,7 @@ describe('exit-process tests', () => {
   });
 
   it('should call onError with reason and kind for unhandledRejection', () => {
-    expect(() => installExitHandlers({ onError })).not.toThrow();
+    expect(() => subscribeProcessExit({ onError })).not.toThrow();
 
     const testReason = 'Test unhandled rejection';
 
@@ -68,7 +68,7 @@ describe('exit-process tests', () => {
 
   it('should call onExit with correct code and reason for SIGINT', () => {
     expect(() =>
-      installExitHandlers({ onExit, exitOnSignal: true }),
+      subscribeProcessExit({ onExit, exitOnSignal: true }),
     ).not.toThrow();
 
     (process as any).emit('SIGINT');
@@ -84,7 +84,7 @@ describe('exit-process tests', () => {
 
   it('should call onExit with correct code and reason for SIGTERM', () => {
     expect(() =>
-      installExitHandlers({ onExit, exitOnSignal: true }),
+      subscribeProcessExit({ onExit, exitOnSignal: true }),
     ).not.toThrow();
 
     (process as any).emit('SIGTERM');
@@ -100,7 +100,7 @@ describe('exit-process tests', () => {
 
   it('should call onExit with correct code and reason for SIGQUIT', () => {
     expect(() =>
-      installExitHandlers({ onExit, exitOnSignal: true }),
+      subscribeProcessExit({ onExit, exitOnSignal: true }),
     ).not.toThrow();
 
     (process as any).emit('SIGQUIT');
@@ -116,7 +116,7 @@ describe('exit-process tests', () => {
 
   it('should not exit process when exitOnSignal is false', () => {
     expect(() =>
-      installExitHandlers({ onExit, exitOnSignal: false }),
+      subscribeProcessExit({ onExit, exitOnSignal: false }),
     ).not.toThrow();
 
     (process as any).emit('SIGINT');
@@ -131,7 +131,7 @@ describe('exit-process tests', () => {
   });
 
   it('should not exit process when exitOnSignal is not set', () => {
-    expect(() => installExitHandlers({ onExit })).not.toThrow();
+    expect(() => subscribeProcessExit({ onExit })).not.toThrow();
 
     (process as any).emit('SIGTERM');
 
@@ -145,7 +145,7 @@ describe('exit-process tests', () => {
   });
 
   it('should call onExit with exit code and reason for normal exit', () => {
-    expect(() => installExitHandlers({ onExit })).not.toThrow();
+    expect(() => subscribeProcessExit({ onExit })).not.toThrow();
 
     const exitCode = 42;
     (process as any).emit('exit', exitCode);
@@ -158,7 +158,7 @@ describe('exit-process tests', () => {
 
   it('should call onExit with fatal reason when exitOnFatal is true', () => {
     expect(() =>
-      installExitHandlers({ onError, onExit, exitOnFatal: true }),
+      subscribeProcessExit({ onError, onExit, exitOnFatal: true }),
     ).not.toThrow();
 
     const testError = new Error('Test uncaught exception');
@@ -176,7 +176,7 @@ describe('exit-process tests', () => {
 
   it('should use custom fatalExitCode when exitOnFatal is true', () => {
     expect(() =>
-      installExitHandlers({
+      subscribeProcessExit({
         onError,
         onExit,
         exitOnFatal: true,
@@ -199,7 +199,7 @@ describe('exit-process tests', () => {
 
   it('should call onExit with fatal reason for unhandledRejection when exitOnFatal is true', () => {
     expect(() =>
-      installExitHandlers({ onError, onExit, exitOnFatal: true }),
+      subscribeProcessExit({ onError, onExit, exitOnFatal: true }),
     ).not.toThrow();
 
     const testReason = 'Test unhandled rejection';
@@ -243,7 +243,7 @@ describe('exit-process tests', () => {
 
   it('should call onExit only once even when close is called multiple times', () => {
     expect(() =>
-      installExitHandlers({ onExit, exitOnSignal: true }),
+      subscribeProcessExit({ onExit, exitOnSignal: true }),
     ).not.toThrow();
 
     (process as any).emit('SIGINT');

packages/utils/src/lib/profiler/__snapshots__/comprehensive-stats-trace-events.jsonl

@@ -0,0 +1,8 @@
+{"cat":"blink.user_timing","ph":"i","name":"stats-profiler:operation-1:start","pid":10001,"tid":1,"ts":1700000005000000,"args":{"detail":"{\"devtools\":{\"track\":\"Stats\",\"dataType\":\"track-entry\"}}"}}
+{"cat":"blink.user_timing","ph":"b","name":"stats-profiler:operation-1","id2":{"local":"0x1"},"pid":10001,"tid":1,"ts":1700000005000001,"args":{"data":{"detail":"{\"devtools\":{\"track\":\"Stats\",\"dataType\":\"track-entry\"}}"}}}
+{"cat":"blink.user_timing","ph":"e","name":"stats-profiler:operation-1","id2":{"local":"0x1"},"pid":10001,"tid":1,"ts":1700000005000002,"args":{"data":{"detail":"{\"devtools\":{\"track\":\"Stats\",\"dataType\":\"track-entry\"}}"}}}
+{"cat":"blink.user_timing","ph":"i","name":"stats-profiler:operation-1:end","pid":10001,"tid":1,"ts":1700000005000003,"args":{"detail":"{\"devtools\":{\"track\":\"Stats\",\"dataType\":\"track-entry\"}}"}}
+{"cat":"blink.user_timing","ph":"i","name":"stats-profiler:operation-2:start","pid":10001,"tid":1,"ts":1700000005000004,"args":{"detail":"{\"devtools\":{\"track\":\"Stats\",\"dataType\":\"track-entry\"}}"}}
+{"cat":"blink.user_timing","ph":"b","name":"stats-profiler:operation-2","id2":{"local":"0x2"},"pid":10001,"tid":1,"ts":1700000005000005,"args":{"data":{"detail":"{\"devtools\":{\"track\":\"Stats\",\"dataType\":\"track-entry\"}}"}}}
+{"cat":"blink.user_timing","ph":"e","name":"stats-profiler:operation-2","id2":{"local":"0x2"},"pid":10001,"tid":1,"ts":1700000005000006,"args":{"data":{"detail":"{\"devtools\":{\"track\":\"Stats\",\"dataType\":\"track-entry\"}}"}}}
+{"cat":"blink.user_timing","ph":"i","name":"stats-profiler:operation-2:end","pid":10001,"tid":1,"ts":1700000005000007,"args":{"detail":"{\"devtools\":{\"track\":\"Stats\",\"dataType\":\"track-entry\"}}"}}

packages/utils/src/lib/profiler/__snapshots__/custom-tracks-trace-events.jsonl

@@ -0,0 +1,4 @@
+{"cat":"blink.user_timing","ph":"i","name":"api-server:user-lookup:start","pid":10001,"tid":1,"ts":1700000005000000,"args":{"detail":"{\"devtools\":{\"track\":\"cache\",\"dataType\":\"track-entry\"}}"}}
+{"cat":"blink.user_timing","ph":"b","name":"api-server:user-lookup","id2":{"local":"0x1"},"pid":10001,"tid":1,"ts":1700000005000001,"args":{"data":{"detail":"{\"devtools\":{\"track\":\"cache\",\"dataType\":\"track-entry\"}}"}}}
+{"cat":"blink.user_timing","ph":"e","name":"api-server:user-lookup","id2":{"local":"0x1"},"pid":10001,"tid":1,"ts":1700000005000002,"args":{"data":{"detail":"{\"devtools\":{\"track\":\"cache\",\"dataType\":\"track-entry\"}}"}}}
+{"cat":"blink.user_timing","ph":"i","name":"api-server:user-lookup:end","pid":10001,"tid":1,"ts":1700000005000003,"args":{"detail":"{\"devtools\":{\"track\":\"cache\",\"dataType\":\"track-entry\"}}"}}

packages/utils/src/lib/profiler/__snapshots__/sharded-path-trace-events.jsonl

@@ -0,0 +1,4 @@
+{"cat":"blink.user_timing","ph":"i","name":"write-test:test-operation:start","pid":10001,"tid":1,"ts":1700000005000000,"args":{"detail":"{\"devtools\":{\"track\":\"Test\",\"dataType\":\"track-entry\"}}"}}
+{"cat":"blink.user_timing","ph":"b","name":"write-test:test-operation","id2":{"local":"0x1"},"pid":10001,"tid":1,"ts":1700000005000001,"args":{"data":{"detail":"{\"devtools\":{\"track\":\"Test\",\"dataType\":\"track-entry\"}}"}}}
+{"cat":"blink.user_timing","ph":"e","name":"write-test:test-operation","id2":{"local":"0x1"},"pid":10001,"tid":1,"ts":1700000005000002,"args":{"data":{"detail":"{\"devtools\":{\"track\":\"Test\",\"dataType\":\"track-entry\"}}"}}}
+{"cat":"blink.user_timing","ph":"i","name":"write-test:test-operation:end","pid":10001,"tid":1,"ts":1700000005000003,"args":{"detail":"{\"devtools\":{\"track\":\"Test\",\"dataType\":\"track-entry\"}}"}}