feat(node): Add shouldHandleError option to fastifyIntegration

Author: onurtemizkan

dev-packages/e2e-tests/test-applications/node-fastify-5/src/app.ts

@@ -17,7 +17,18 @@ console.warn = new Proxy(console.warn, {
 Sentry.init({
   environment: 'qa', // dynamic sampling bias to keep transactions
   dsn: process.env.E2E_TEST_DSN,
-  integrations: [],
+  integrations: [
+    Sentry.fastifyIntegration({
+      shouldHandleError: (error, _request, _reply) => {
+        if (_request.routeOptions?.url?.includes('/test-error-not-captured')) {
+          // Errors from this path will not be captured by Sentry
+          return false;
+        }
+
+        return true;
+      },
+    }),
+  ],
   tracesSampleRate: 1,
   tunnel: 'http://localhost:3031/', // proxy server
   tracePropagationTargets: ['http://localhost:3030', '/external-allowed'],
@@ -79,6 +90,11 @@ app.get('/test-error', async function (req, res) {
   res.send({ exceptionId });
 });
 
+app.get('/test-error-not-captured', async function () {
+  // This error will not be captured by Sentry
+  throw new Error('This is an error that will not be captured');
+});
+
 app.get<{ Params: { id: string } }>('/test-exception/:id', async function (req, res) {
   throw new Error(`This is an exception with id ${req.params.id}`);
 });

dev-packages/e2e-tests/test-applications/node-fastify-5/tests/errors.test.ts

@@ -28,3 +28,16 @@ test('Sends correct error event', async ({ baseURL }) => {
     parent_span_id: expect.stringMatching(/[a-f0-9]{16}/),
   });
 });
+
+test('Does not send error when shouldHandleError returns false', async ({ baseURL }) => {
+  const errorEventPromise = waitForError('node-fastify-5', event => {
+    return !event.type && event.exception?.values?.[0]?.value === 'This is an error that will not be captured';
+  });
+
+  await fetch(`${baseURL}/test-error-not-captured`);
+
+  // Wait for a short time to ensure no error is sent
+  await new Promise(resolve => setTimeout(resolve, 1000));
+
+  expect(errorEventPromise).rejects.toBeDefined();
+});

packages/node/src/integrations/tracing/fastify/index.ts

@@ -27,6 +27,7 @@ interface FastifyHandlerOptions {
    *
    * @example
    *
+   *
    * ```javascript
    * setupFastifyErrorHandler(app, {
    *   shouldHandleError(_error, _request, reply) {
@@ -35,6 +36,20 @@ interface FastifyHandlerOptions {
    * });
    * ```
    *
+   * or if you use Fastify v5 you can set options in the Sentry.init call:
+   *
+   * ```javascript
+   * Sentry.init({
+   *   integrations: [
+   *     Sentry.fastifyIntegration({
+   *       shouldHandleError(_error, _request, reply) {
+   *         return reply.statusCode >= 500;
+   *       },
+   *     });
+   *   },
+   * });
+   * ```
+   *
    * If using TypeScript, you can cast the request and reply to get full type safety.
    *
    * ```typescript
@@ -88,51 +103,65 @@ function handleFastifyError(
   }
 }
 
-export const instrumentFastify = generateInstrumentOnce(INTEGRATION_NAME, () => {
-  const fastifyOtelInstrumentationInstance = new FastifyOtelInstrumentation();
-  const plugin = fastifyOtelInstrumentationInstance.plugin();
-  const options = fastifyOtelInstrumentationInstance.getConfig();
-  const shouldHandleError = (options as FastifyHandlerOptions)?.shouldHandleError || defaultShouldHandleError;
-
-  // This message handler works for Fastify versions 3, 4 and 5
-  diagnosticsChannel.subscribe('fastify.initialization', message => {
-    const fastifyInstance = (message as { fastify?: FastifyInstance }).fastify;
-
-    fastifyInstance?.register(plugin).after(err => {
-      if (err) {
-        DEBUG_BUILD && debug.error('Failed to setup Fastify instrumentation', err);
-      } else {
-        instrumentClient();
-
-        if (fastifyInstance) {
-          instrumentOnRequest(fastifyInstance);
+export const instrumentFastify = generateInstrumentOnce(
+  INTEGRATION_NAME,
+  (
+    options: Partial<FastifyHandlerOptions> = {
+      shouldHandleError: defaultShouldHandleError,
+    },
+  ) => {
+    const fastifyOtelInstrumentationInstance = new FastifyOtelInstrumentation();
+    const plugin = fastifyOtelInstrumentationInstance.plugin();
+
+    // This message handler works for Fastify versions 3, 4 and 5
+    diagnosticsChannel.subscribe('fastify.initialization', message => {
+      const fastifyInstance = (message as { fastify?: FastifyInstance }).fastify;
+
+      fastifyInstance?.register(plugin).after(err => {
+        if (err) {
+          DEBUG_BUILD && debug.error('Failed to setup Fastify instrumentation', err);
+        } else {
+          instrumentClient();
+
+          if (fastifyInstance) {
+            instrumentOnRequest(fastifyInstance);
+          }
         }
-      }
+      });
     });
-  });
-
-  // This diagnostics channel only works on Fastify version 5
-  // For versions 3 and 4, we use `setupFastifyErrorHandler` instead
-  diagnosticsChannel.subscribe('tracing:fastify.request.handler:error', message => {
-    const { error, request, reply } = message as {
-      error: Error;
-      request: FastifyRequest & { opentelemetry?: () => { span?: Span } };
-      reply: FastifyReply;
-    };
 
-    handleFastifyError.call(handleFastifyError, error, request, reply, shouldHandleError, 'diagnostics-channel');
-  });
+    // This diagnostics channel only works on Fastify version 5
+    // For versions 3 and 4, we use `setupFastifyErrorHandler` instead
+    diagnosticsChannel.subscribe('tracing:fastify.request.handler:error', message => {
+      const { error, request, reply } = message as {
+        error: Error;
+        request: FastifyRequest & { opentelemetry?: () => { span?: Span } };
+        reply: FastifyReply;
+      };
+
+      handleFastifyError.call(
+        handleFastifyError,
+        error,
+        request,
+        reply,
+        options.shouldHandleError,
+        'diagnostics-channel',
+      );
+    });
 
-  // Returning this as unknown not to deal with the internal types of the FastifyOtelInstrumentation
-  return fastifyOtelInstrumentationInstance as Instrumentation<InstrumentationConfig & FastifyHandlerOptions>;
-});
+    // Returning this as unknown not to deal with the internal types of the FastifyOtelInstrumentation
+    return fastifyOtelInstrumentationInstance as Instrumentation<InstrumentationConfig & FastifyHandlerOptions>;
+  },
+);
 
-const _fastifyIntegration = (() => {
+const _fastifyIntegration = (({ shouldHandleError }) => {
   return {
     name: INTEGRATION_NAME,
     setupOnce() {
       instrumentFastifyV3();
-      instrumentFastify();
+      instrumentFastify({
+        shouldHandleError,
+      });
     },
   };
 }) satisfies IntegrationFn;
@@ -153,7 +182,9 @@ const _fastifyIntegration = (() => {
  * })
  * ```
  */
-export const fastifyIntegration = defineIntegration(_fastifyIntegration);
+export const fastifyIntegration = defineIntegration((options: Partial<FastifyHandlerOptions> = {}) =>
+  _fastifyIntegration(options),
+);
 
 /**
  * Default function to determine if an error should be sent to Sentry