feat(node): Use process.on('SIGTERM') for flushing in Vercel functions

dev-packages/node-integration-tests/suites/vercel/sigterm-flush/scenario.ts

@@ -0,0 +1,36 @@
+import type { BaseTransportOptions, Envelope, Transport, TransportMakeRequestResponse } from '@sentry/core';
+import * as Sentry from '@sentry/node';
+
+function bufferedLoggingTransport(_options: BaseTransportOptions): Transport {
+  const bufferedEnvelopes: Envelope[] = [];
+
+  return {
+    send(envelope: Envelope): Promise<TransportMakeRequestResponse> {
+      bufferedEnvelopes.push(envelope);
+      return Promise.resolve({ statusCode: 200 });
+    },
+    flush(_timeout?: number): PromiseLike<boolean> {
+      // Print envelopes once flushed to verify they were sent.
+      for (const envelope of bufferedEnvelopes.splice(0, bufferedEnvelopes.length)) {
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify(envelope));
+      }
+
+      return Promise.resolve(true);
+    },
+  };
+}
+
+Sentry.init({
+  dsn: 'https://public@dsn.ingest.sentry.io/1337',
+  transport: bufferedLoggingTransport,
+});
+
+Sentry.captureMessage('SIGTERM flush message');
+
+// Signal that we're ready to receive SIGTERM.
+// eslint-disable-next-line no-console
+console.log('READY');
+
+// Keep the process alive so the integration test can send SIGTERM.
+setInterval(() => undefined, 1_000);

dev-packages/node-integration-tests/suites/vercel/sigterm-flush/test.ts

@@ -0,0 +1,39 @@
+import { afterAll, expect, test } from 'vitest';
+import { cleanupChildProcesses, createRunner } from '../../../utils/runner';
+
+afterAll(() => {
+  cleanupChildProcesses();
+});
+
+test('flushes buffered events when SIGTERM is received on Vercel', async () => {
+  const runner = createRunner(__dirname, 'scenario.ts')
+    .withEnv({ VERCEL: '1' })
+    .expect({
+      event: {
+        message: 'SIGTERM flush message',
+      },
+    })
+    .start();
+
+  // Wait for the scenario to signal it's ready (SIGTERM handler is registered).
+  const waitForReady = async (): Promise<void> => {
+    const maxWait = 10_000;
+    const start = Date.now();
+    while (Date.now() - start < maxWait) {
+      if (runner.getLogs().some(line => line.includes('READY'))) {
+        return;
+      }
+      await new Promise<void>(resolve => setTimeout(resolve, 50));
+    }
+    throw new Error('Timed out waiting for scenario to be ready');
+  };
+
+  await waitForReady();
+
+  runner.sendSignal('SIGTERM');
+
+  await runner.completed();
+
+  // Check that the child didn't crash (it may be killed by the runner after completion).
+  expect(runner.getLogs().join('\n')).not.toMatch(/Error starting child process/i);
+});

dev-packages/node-integration-tests/utils/runner.ts

@@ -172,6 +172,7 @@ type StartResult = {
   childHasExited(): boolean;
   getLogs(): string[];
   getPort(): number | undefined;
+  sendSignal(signal: NodeJS.Signals): void;
   makeRequest<T>(
     method: 'get' | 'post' | 'put' | 'delete' | 'patch',
     path: string,
@@ -668,6 +669,9 @@ export function createRunner(...paths: string[]) {
         getPort(): number | undefined {
           return scenarioServerPort;
         },
+        sendSignal(signal: NodeJS.Signals): void {
+          child?.kill(signal);
+        },
         makeRequest: async function <T>(
           method: 'get' | 'post' | 'put' | 'delete' | 'patch',
           path: string,

packages/core/src/utils/flushIfServerless.ts

@@ -51,6 +51,8 @@ export async function flushIfServerless(
     return;
   }
 
+  // Note: vercelWaitUntil only does something in Vercel Edge runtime
+  // In Node runtime, we use process.on('SIGTERM') instead
   // @ts-expect-error This is not typed
   if (GLOBAL_OBJ[Symbol.for('@vercel/request-context')]) {
     // Vercel has a waitUntil equivalent that works without execution context

packages/core/src/utils/vercelWaitUntil.ts

@@ -1,5 +1,7 @@
 import { GLOBAL_OBJ } from './worldwide';
 
+declare const EdgeRuntime: string | undefined;
+
 interface VercelRequestContextGlobal {
   get?():
     | {
@@ -14,6 +16,11 @@ interface VercelRequestContextGlobal {
  * Vendored from https://www.npmjs.com/package/@vercel/functions
  */
 export function vercelWaitUntil(task: Promise<unknown>): void {
+  // We only flush manually in Vercel Edge runtime
+  // In Node runtime, we use process.on('SIGTERM') instead
+  if (typeof EdgeRuntime !== 'string') {
+    return;
+  }
   const vercelRequestContextGlobal: VercelRequestContextGlobal | undefined =
     // @ts-expect-error This is not typed
     GLOBAL_OBJ[Symbol.for('@vercel/request-context')];

packages/core/test/lib/utils/vercelWaitUntil.test.ts

@@ -1,40 +1,63 @@
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { vercelWaitUntil } from '../../../src/utils/vercelWaitUntil';
 import { GLOBAL_OBJ } from '../../../src/utils/worldwide';
 
 describe('vercelWaitUntil', () => {
+  const VERCEL_REQUEST_CONTEXT_SYMBOL = Symbol.for('@vercel/request-context');
+  const globalWithEdgeRuntime = globalThis as typeof globalThis & { EdgeRuntime?: string };
+  const globalWithVercelRequestContext = GLOBAL_OBJ as unknown as Record<symbol, unknown>;
+
+  // `vercelWaitUntil` only runs in Vercel Edge runtime, which is detected via the global `EdgeRuntime` variable.
+  // In tests we set it explicitly so the logic is actually exercised.
+  const originalEdgeRuntime = globalWithEdgeRuntime.EdgeRuntime;
+
+  beforeEach(() => {
+    globalWithEdgeRuntime.EdgeRuntime = 'edge-runtime';
+  });
+
+  afterEach(() => {
+    if (originalEdgeRuntime === undefined) {
+      delete globalWithEdgeRuntime.EdgeRuntime;
+    } else {
+      globalWithEdgeRuntime.EdgeRuntime = originalEdgeRuntime;
+    }
+  });
+
   it('should do nothing if GLOBAL_OBJ does not have the @vercel/request-context symbol', () => {
     const task = Promise.resolve();
     vercelWaitUntil(task);
     // No assertions needed, just ensuring no errors are thrown
   });
 
   it('should do nothing if get method is not defined', () => {
-    // @ts-expect-error - Not typed
-    GLOBAL_OBJ[Symbol.for('@vercel/request-context')] = {};
+    const originalRequestContext = globalWithVercelRequestContext[VERCEL_REQUEST_CONTEXT_SYMBOL];
+    globalWithVercelRequestContext[VERCEL_REQUEST_CONTEXT_SYMBOL] = {};
     const task = Promise.resolve();
     vercelWaitUntil(task);
     // No assertions needed, just ensuring no errors are thrown
+    globalWithVercelRequestContext[VERCEL_REQUEST_CONTEXT_SYMBOL] = originalRequestContext;
   });
 
   it('should do nothing if waitUntil method is not defined', () => {
-    // @ts-expect-error - Not typed
-    GLOBAL_OBJ[Symbol.for('@vercel/request-context')] = {
+    const originalRequestContext = globalWithVercelRequestContext[VERCEL_REQUEST_CONTEXT_SYMBOL];
+    globalWithVercelRequestContext[VERCEL_REQUEST_CONTEXT_SYMBOL] = {
       get: () => ({}),
     };
     const task = Promise.resolve();
     vercelWaitUntil(task);
     // No assertions needed, just ensuring no errors are thrown
+    globalWithVercelRequestContext[VERCEL_REQUEST_CONTEXT_SYMBOL] = originalRequestContext;
   });
 
   it('should call waitUntil method if it is defined', () => {
+    const originalRequestContext = globalWithVercelRequestContext[VERCEL_REQUEST_CONTEXT_SYMBOL];
     const waitUntilMock = vi.fn();
-    // @ts-expect-error - Not typed
-    GLOBAL_OBJ[Symbol.for('@vercel/request-context')] = {
+    globalWithVercelRequestContext[VERCEL_REQUEST_CONTEXT_SYMBOL] = {
       get: () => ({ waitUntil: waitUntilMock }),
     };
     const task = Promise.resolve();
     vercelWaitUntil(task);
     expect(waitUntilMock).toHaveBeenCalledWith(task);
+    globalWithVercelRequestContext[VERCEL_REQUEST_CONTEXT_SYMBOL] = originalRequestContext;
   });
 });

packages/node-core/src/sdk/index.ts

@@ -143,6 +143,15 @@ function _init(
   enhanceDscWithOpenTelemetryRootSpanName(client);
   setupEventContextTrace(client);
 
+  // Ensure we flush events when vercel functions are ended
+  // See: https://vercel.com/docs/functions/functions-api-reference#sigterm-signal
+  if (process.env.VERCEL) {
+    process.on('SIGTERM', async () => {
+      // We have 500ms for processing here, so we try to make sure to have enough time to send the events
+      await client.flush(200);
+    });
+  }
+
   return client;
 }
 

packages/node-core/test/sdk/init.test.ts

@@ -111,6 +111,64 @@ describe('init()', () => {
     expect(client).toBeInstanceOf(NodeClient);
   });
 
+  it('registers a SIGTERM handler on Vercel', () => {
+    const originalVercelEnv = process.env.VERCEL;
+    process.env.VERCEL = '1';
+
+    const baselineListeners = process.listeners('SIGTERM');
+
+    init({ dsn: PUBLIC_DSN, skipOpenTelemetrySetup: true });
+
+    const postInitListeners = process.listeners('SIGTERM');
+    const addedListeners = postInitListeners.filter(l => !baselineListeners.includes(l));
+
+    expect(addedListeners).toHaveLength(1);
+
+    // Cleanup: remove the handler we added in this test.
+    process.off('SIGTERM', addedListeners[0] as any);
+    process.env.VERCEL = originalVercelEnv;
+  });
+
+  it('flushes when SIGTERM is received on Vercel', () => {
+    const originalVercelEnv = process.env.VERCEL;
+    process.env.VERCEL = '1';
+
+    const baselineListeners = process.listeners('SIGTERM');
+
+    const client = init({ dsn: PUBLIC_DSN, skipOpenTelemetrySetup: true });
+    expect(client).toBeInstanceOf(NodeClient);
+
+    const flushSpy = vi.spyOn(client as NodeClient, 'flush').mockResolvedValue(true);
+
+    const postInitListeners = process.listeners('SIGTERM');
+    const addedListeners = postInitListeners.filter(l => !baselineListeners.includes(l));
+    expect(addedListeners).toHaveLength(1);
+
+    process.emit('SIGTERM');
+
+    expect(flushSpy).toHaveBeenCalledWith(200);
+
+    // Cleanup: remove the handler we added in this test.
+    process.off('SIGTERM', addedListeners[0] as any);
+    process.env.VERCEL = originalVercelEnv;
+  });
+
+  it('does not register a SIGTERM handler when not running on Vercel', () => {
+    const originalVercelEnv = process.env.VERCEL;
+    delete process.env.VERCEL;
+
+    const baselineListeners = process.listeners('SIGTERM');
+
+    init({ dsn: PUBLIC_DSN, skipOpenTelemetrySetup: true });
+
+    const postInitListeners = process.listeners('SIGTERM');
+    const addedListeners = postInitListeners.filter(l => !baselineListeners.includes(l));
+
+    expect(addedListeners).toHaveLength(0);
+
+    process.env.VERCEL = originalVercelEnv;
+  });
+
   describe('environment variable options', () => {
     const originalProcessEnv = { ...process.env };