fix(node-core): Fix race condition in local variables integration

The `LocalVariables` integrations `setupOnce` method was `async`, which violates the `Integration` interface. This caused a race condition where events could be processed before the integration was fully initialized, leading to missed local variables.

This commit fixes the race condition by:
- Making `setupOnce` synchronous to adhere to the interface contract.
- Moving the asynchronous initialization logic to a separate `setup` function.
- Making `processEvent` asynchronous and awaiting the result of the `setup` function, ensuring that the integration is fully initialized before processing any events.
- Updating the tests to correctly `await` the `processEvent` method.

Author: JealousGx

packages/node-core/src/integrations/local-variables/local-variables-sync.ts

@@ -291,120 +291,128 @@ const _localVariablesSyncIntegration = ((
 
   const testHelperMethods = localVariablesTestHelperMethods(cachedFrames);
 
-  return {
-    name: INTEGRATION_NAME,
-    async setupOnce() {
-      const client = getClient<NodeClient>();
-      const clientOptions = client?.getOptions();
-
-      if (!clientOptions?.includeLocalVariables) {
-        return;
-      }
+  let setupPromise: Promise<void> | undefined;
 
-      // Only setup this integration if the Node version is >= v18
-      // https://github.com/getsentry/sentry-javascript/issues/7697
-      const unsupportedNodeVersion = NODE_MAJOR < 18;
-
-      if (unsupportedNodeVersion) {
-        debug.log('The `LocalVariables` integration is only supported on Node >= v18.');
-        return;
-      }
-
-      if (await isDebuggerEnabled()) {
-        debug.warn('Local variables capture has been disabled because the debugger was already enabled');
-        return;
-      }
+  async function setup(): Promise<void> {
+    const client = getClient<NodeClient>();
+    const clientOptions = client?.getOptions();
 
-      try {
-        const session = await AsyncSession.create(sessionOverride);
-
-        const handlePaused = (
-          stackParser: StackParser,
-          { params: { reason, data, callFrames } }: InspectorNotification<PausedExceptionEvent>,
-          complete: () => void,
-        ): void => {
-          if (reason !== 'exception' && reason !== 'promiseRejection') {
-            complete();
-            return;
-          }
+    if (!clientOptions?.includeLocalVariables) {
+      return;
+    }
 
-          rateLimiter?.();
+    // Only setup this integration if the Node version is >= v18
+    // https://github.com/getsentry/sentry-javascript/issues/7697
+    const unsupportedNodeVersion = NODE_MAJOR < 18;
 
-          // data.description contains the original error.stack
-          const exceptionHash = hashFromStack(stackParser, data.description);
+    if (unsupportedNodeVersion) {
+      debug.log('The `LocalVariables` integration is only supported on Node >= v18.');
+      return;
+    }
 
-          if (exceptionHash == undefined) {
-            complete();
-            return;
-          }
+    if (await isDebuggerEnabled()) {
+      debug.warn('Local variables capture has been disabled because the debugger was already enabled');
+      return;
+    }
 
-          const { add, next } = createCallbackList<FrameVariables[]>(frames => {
-            cachedFrames.set(exceptionHash, frames);
-            complete();
-          });
+    try {
+      const session = await AsyncSession.create(sessionOverride);
+
+      const handlePaused = (
+        stackParser: StackParser,
+        { params: { reason, data, callFrames } }: InspectorNotification<PausedExceptionEvent>,
+        complete: () => void,
+      ): void => {
+        if (reason !== 'exception' && reason !== 'promiseRejection') {
+          complete();
+          return;
+        }
 
-          // Because we're queuing up and making all these calls synchronously, we can potentially overflow the stack
-          // For this reason we only attempt to get local variables for the first 5 frames
-          for (let i = 0; i < Math.min(callFrames.length, 5); i++) {
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            const { scopeChain, functionName, this: obj } = callFrames[i]!;
+        rateLimiter?.();
 
-            const localScope = scopeChain.find(scope => scope.type === 'local');
+        // data.description contains the original error.stack
+        const exceptionHash = hashFromStack(stackParser, data.description);
 
-            // obj.className is undefined in ESM modules
-            const fn = obj.className === 'global' || !obj.className ? functionName : `${obj.className}.${functionName}`;
+        if (exceptionHash == undefined) {
+          complete();
+          return;
+        }
 
-            if (localScope?.object.objectId === undefined) {
-              add(frames => {
-                frames[i] = { function: fn };
+        const { add, next } = createCallbackList<FrameVariables[]>(frames => {
+          cachedFrames.set(exceptionHash, frames);
+          complete();
+        });
+
+        // Because we're queuing up and making all these calls synchronously, we can potentially overflow the stack
+        // For this reason we only attempt to get local variables for the first 5 frames
+        for (let i = 0; i < Math.min(callFrames.length, 5); i++) {
+          // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+          const { scopeChain, functionName, this: obj } = callFrames[i]!;
+
+          const localScope = scopeChain.find(scope => scope.type === 'local');
+
+          // obj.className is undefined in ESM modules
+          const fn = obj.className === 'global' || !obj.className ? functionName : `${obj.className}.${functionName}`;
+
+          if (localScope?.object.objectId === undefined) {
+            add(frames => {
+              frames[i] = { function: fn };
+              next(frames);
+            });
+          } else {
+            const id = localScope.object.objectId;
+            add(frames =>
+              session.getLocalVariables(id, vars => {
+                frames[i] = { function: fn, vars };
                 next(frames);
-              });
-            } else {
-              const id = localScope.object.objectId;
-              add(frames =>
-                session.getLocalVariables(id, vars => {
-                  frames[i] = { function: fn, vars };
-                  next(frames);
-                }),
-              );
-            }
+              }),
+            );
           }
+        }
 
-          next([]);
-        };
-
-        const captureAll = options.captureAllExceptions !== false;
-
-        session.configureAndConnect(
-          (ev, complete) =>
-            handlePaused(clientOptions.stackParser, ev as InspectorNotification<PausedExceptionEvent>, complete),
-          captureAll,
+        next([]);
+      };
+
+      const captureAll = options.captureAllExceptions !== false;
+
+      session.configureAndConnect(
+        (ev, complete) =>
+          handlePaused(clientOptions.stackParser, ev as InspectorNotification<PausedExceptionEvent>, complete),
+        captureAll,
+      );
+
+      if (captureAll) {
+        const max = options.maxExceptionsPerSecond || 50;
+
+        rateLimiter = createRateLimiter(
+          max,
+          () => {
+            debug.log('Local variables rate-limit lifted.');
+            session.setPauseOnExceptions(true);
+          },
+          seconds => {
+            debug.log(
+              `Local variables rate-limit exceeded. Disabling capturing of caught exceptions for ${seconds} seconds.`,
+            );
+            session.setPauseOnExceptions(false);
+          },
         );
+      }
 
-        if (captureAll) {
-          const max = options.maxExceptionsPerSecond || 50;
-
-          rateLimiter = createRateLimiter(
-            max,
-            () => {
-              debug.log('Local variables rate-limit lifted.');
-              session.setPauseOnExceptions(true);
-            },
-            seconds => {
-              debug.log(
-                `Local variables rate-limit exceeded. Disabling capturing of caught exceptions for ${seconds} seconds.`,
-              );
-              session.setPauseOnExceptions(false);
-            },
-          );
-        }
+      shouldProcessEvent = true;
+    } catch (error) {
+      debug.log('The `LocalVariables` integration failed to start.', error);
+    }
+  }
 
-        shouldProcessEvent = true;
-      } catch (error) {
-        debug.log('The `LocalVariables` integration failed to start.', error);
-      }
+  return {
+    name: INTEGRATION_NAME,
+    setupOnce() {
+      setupPromise = setup();
     },
-    processEvent(event: Event): Event {
+    async processEvent(event: Event): Promise<Event> {
+      await setupPromise;
+
       if (shouldProcessEvent) {
         return addLocalVariablesToEvent(event);
       }

packages/node-core/test/integrations/local-variables.test.ts

@@ -26,13 +26,13 @@ describe('LocalVariables', () => {
     const eventName = 'test-exclude-LocalVariables-out-of-app-frames';
     const event = getTestEvent(eventName);
     const integration = localVariablesSyncIntegration({}, mockSession);
-    await integration.setupOnce?.();
+    integration.setupOnce?.();
 
     const hash = hashFrames(event.exception!.values![0]!.stacktrace!.frames);
     // @ts-expect-error test helper method
     integration._setCachedFrame(hash!, [{ function: eventName, vars: { foo: 'bar' } } as FrameVariables]);
 
-    const processedEvent = integration.processEvent?.(event, {}, {} as any) as Event;
+    const processedEvent = (await integration.processEvent?.(event, {}, {} as any)) as Event;
 
     expect(processedEvent.exception?.values?.[0]?.stacktrace?.frames?.[0]?.vars).toBeUndefined();
   });
@@ -41,13 +41,13 @@ describe('LocalVariables', () => {
     const eventName = 'test-include-LocalVariables-out-of-app-frames';
     const event = getTestEvent(eventName);
     const integration = localVariablesSyncIntegration({ includeOutOfAppFrames: true }, mockSession);
-    await integration.setupOnce?.();
+    integration.setupOnce?.();
 
     const hash = hashFrames(event.exception!.values![0]!.stacktrace!.frames);
     // @ts-expect-error test helper method
     integration._setCachedFrame(hash!, [{ function: eventName, vars: { foo: 'bar' } } as FrameVariables]);
 
-    const processedEvent = integration.processEvent?.(event, {}, {} as any) as Event;
+    const processedEvent = (await integration.processEvent?.(event, {}, {} as any)) as Event;
 
     expect(processedEvent.exception?.values?.[0]?.stacktrace?.frames?.[0]?.vars).toEqual({ foo: 'bar' });
   });