feat(node): Capture SystemError context and remove paths from message (#17331)

resolves #17332

Node.js has a
[`SystemError`](https://nodejs.org/api/errors.html#class-systemerror)
error class.

This error type contains numerous properties which can be useful for
debugging but it also includes many of them in the error message which
stops fingerprinting from grouping these errors.

This PR adds a default enabled integration that copies the error
properties to a new context and strips paths from the error message.

If the top-level `sendDefaultPii` is not enabled, the `path` and `dest`
properties will not be included.

Author: timfish

.size-limit.js

@@ -233,7 +233,7 @@ module.exports = [
     import: createImport('init'),
     ignore: [...builtinModules, ...nodePrefixedBuiltinModules],
     gzip: true,
-    limit: '147 KB',
+    limit: '148 KB',
   },
   {
     name: '@sentry/node - without tracing',

dev-packages/e2e-tests/test-applications/node-exports-test-app/scripts/consistentExports.ts

@@ -52,6 +52,7 @@ const DEPENDENTS: Dependent[] = [
       'NodeClient',
       'NODE_VERSION',
       'childProcessIntegration',
+      'systemErrorIntegration',
     ],
   },
   {

dev-packages/node-core-integration-tests/suites/system-error/basic-pii.mjs

@@ -0,0 +1,11 @@
+import * as Sentry from '@sentry/node-core';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+import { readFileSync } from 'fs';
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  transport: loggingTransport,
+  sendDefaultPii: true,
+});
+
+readFileSync('non-existent-file.txt');

dev-packages/node-core-integration-tests/suites/system-error/basic.mjs

@@ -0,0 +1,10 @@
+import * as Sentry from '@sentry/node-core';
+import { loggingTransport } from '@sentry-internal/node-integration-tests';
+import { readFileSync } from 'fs';
+
+Sentry.init({
+  dsn: 'https://[email protected]/1337',
+  transport: loggingTransport,
+});
+
+readFileSync('non-existent-file.txt');

dev-packages/node-core-integration-tests/suites/system-error/test.ts

@@ -0,0 +1,59 @@
+import { afterAll, describe, test } from 'vitest';
+import { cleanupChildProcesses, createRunner } from '../../utils/runner';
+
+afterAll(() => {
+  cleanupChildProcesses();
+});
+
+describe('SystemError integration', () => {
+  test('sendDefaultPii: false', async () => {
+    await createRunner(__dirname, 'basic.mjs')
+      .expect({
+        event: {
+          contexts: {
+            node_system_error: {
+              errno: -2,
+              code: 'ENOENT',
+              syscall: 'open',
+            },
+          },
+          exception: {
+            values: [
+              {
+                type: 'Error',
+                value: 'ENOENT: no such file or directory, open',
+              },
+            ],
+          },
+        },
+      })
+      .start()
+      .completed();
+  });
+
+  test('sendDefaultPii: true', async () => {
+    await createRunner(__dirname, 'basic-pii.mjs')
+      .expect({
+        event: {
+          contexts: {
+            node_system_error: {
+              errno: -2,
+              code: 'ENOENT',
+              syscall: 'open',
+              path: 'non-existent-file.txt',
+            },
+          },
+          exception: {
+            values: [
+              {
+                type: 'Error',
+                value: 'ENOENT: no such file or directory, open',
+              },
+            ],
+          },
+        },
+      })
+      .start()
+      .completed();
+  });
+});

packages/astro/src/index.server.ts

@@ -124,6 +124,7 @@ export {
   startSession,
   startSpan,
   startSpanManual,
+  systemErrorIntegration,
   tediousIntegration,
   trpcMiddleware,
   updateSpanName,

packages/aws-serverless/src/index.ts

@@ -114,6 +114,7 @@ export {
   spanToJSON,
   spanToTraceHeader,
   spanToBaggageHeader,
+  systemErrorIntegration,
   trpcMiddleware,
   updateSpanName,
   supabaseIntegration,

packages/google-cloud-serverless/src/index.ts

@@ -115,6 +115,7 @@ export {
   trpcMiddleware,
   updateSpanName,
   supabaseIntegration,
+  systemErrorIntegration,
   instrumentSupabaseClient,
   zodErrorsIntegration,
   profiler,

packages/node-core/src/index.ts

@@ -21,6 +21,7 @@ export { onUnhandledRejectionIntegration } from './integrations/onunhandledrejec
 export { anrIntegration, disableAnrDetectionForCallback } from './integrations/anr';
 
 export { spotlightIntegration } from './integrations/spotlight';
+export { systemErrorIntegration } from './integrations/systemError';
 export { childProcessIntegration } from './integrations/childProcess';
 export { createSentryWinstonTransport } from './integrations/winston';
 

packages/node-core/src/integrations/systemError.ts

@@ -0,0 +1,76 @@
+import * as util from 'node:util';
+import { defineIntegration } from '@sentry/core';
+
+const INTEGRATION_NAME = 'NodeSystemError';
+
+type SystemErrorContext = {
+  dest?: string; // If present, the file path destination when reporting a file system error
+  errno: number; // The system-provided error number
+  path?: string; // If present, the file path when reporting a file system error
+};
+
+type SystemError = Error & SystemErrorContext;
+
+function isSystemError(error: unknown): error is SystemError {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+
+  if (!('errno' in error) || typeof error.errno !== 'number') {
+    return false;
+  }
+
+  // Appears this is the recommended way to check for Node.js SystemError
+  // https://github.com/nodejs/node/issues/46869
+  return util.getSystemErrorMap().has(error.errno);
+}
+
+type Options = {
+  /**
+   * If true, includes the `path` and `dest` properties in the error context.
+   */
+  includePaths?: boolean;
+};
+
+/**
+ * Captures context for Node.js SystemError errors.
+ */
+export const systemErrorIntegration = defineIntegration((options: Options = {}) => {
+  return {
+    name: INTEGRATION_NAME,
+    processEvent: (event, hint, client) => {
+      if (!isSystemError(hint.originalException)) {
+        return event;
+      }
+
+      const error = hint.originalException;
+
+      const errorContext: SystemErrorContext = {
+        ...error,
+      };
+
+      if (!client.getOptions().sendDefaultPii && options.includePaths !== true) {
+        delete errorContext.path;
+        delete errorContext.dest;
+      }
+
+      event.contexts = {
+        ...event.contexts,
+        node_system_error: errorContext,
+      };
+
+      for (const exception of event.exception?.values || []) {
+        if (exception.value) {
+          if (error.path && exception.value.includes(error.path)) {
+            exception.value = exception.value.replace(`'${error.path}'`, '').trim();
+          }
+          if (error.dest && exception.value.includes(error.dest)) {
+            exception.value = exception.value.replace(`'${error.dest}'`, '').trim();
+          }
+        }
+      }
+
+      return event;
+    },
+  };
+});