Implement error handling and tracing for Google Cloud functions.

Author: marshall-lee

packages/node/src/handlers.ts

@@ -141,7 +141,7 @@ function extractUserData(
 /**
  * Options deciding what parts of the request to use when enhancing an event
  */
-interface ParseRequestOptions {
+export interface ParseRequestOptions {
   ip?: boolean;
   request?: boolean | string[];
   serverName?: boolean;

packages/serverless/package.json

@@ -23,6 +23,7 @@
     "tslib": "^1.9.3"
   },
   "devDependencies": {
+    "@google-cloud/functions-framework": "^1.7.1",
     "@sentry-internal/eslint-config-sdk": "5.25.0",
     "@types/aws-lambda": "^8.10.62",
     "@types/node": "^14.6.4",

packages/serverless/src/gcpfunction.ts

@@ -0,0 +1,131 @@
+// '@google-cloud/functions-framework/build/src/functions' import is expected to be type-only so it's erased in the final .js file.
+// When TypeScript compiler is upgraded, use `import type` syntax to explicitly assert that we don't want to load a module here.
+import { HttpFunction } from '@google-cloud/functions-framework/build/src/functions';
+import {
+  captureException,
+  flush,
+  getCurrentHub,
+  Handlers,
+  Scope,
+  SDK_VERSION,
+  startTransaction,
+  withScope,
+} from '@sentry/node';
+import { addExceptionMechanism, logger, stripUrlQueryAndFragment } from '@sentry/utils';
+import { Domain } from 'domain';
+
+type Request = Parameters<HttpFunction>[0];
+type Response = Parameters<HttpFunction>[1];
+type ParseRequestOptions = Handlers.ParseRequestOptions;
+
+export { HttpFunction, Request, Response };
+
+export interface HttpWrapperOptions {
+  flushTimeout: number;
+  parseRequestOptions: ParseRequestOptions;
+}
+
+const { parseRequest } = Handlers;
+
+/**
+ * Add event processor that will override SDK details to point to the serverless SDK instead of Node,
+ * as well as set correct mechanism type, which should be set to `handled: false`.
+ * We do it like this, so that we don't introduce any side-effects in this module, which makes it tree-shakeable.
+ * @param scope Scope that processor should be added to
+ */
+function addServerlessEventProcessor(scope: Scope, req: Request, options: ParseRequestOptions): void {
+  scope.addEventProcessor(event => {
+    event.sdk = {
+      ...event.sdk,
+      name: 'sentry.javascript.serverless',
+      integrations: [...((event.sdk && event.sdk.integrations) || []), 'GCPFunction'],
+      packages: [
+        ...((event.sdk && event.sdk.packages) || []),
+        {
+          name: 'npm:@sentry/serverless',
+          version: SDK_VERSION,
+        },
+      ],
+      version: SDK_VERSION,
+    };
+
+    addExceptionMechanism(event, {
+      handled: false,
+    });
+
+    return parseRequest(event, req, options);
+  });
+}
+
+/**
+ * Capture exception.
+ *
+ * @param e exception to be captured
+ */
+function captureRequestError(e: unknown, req: Request, options: ParseRequestOptions): void {
+  withScope(scope => {
+    addServerlessEventProcessor(scope, req, options);
+    captureException(e);
+  });
+}
+
+/**
+ * Wraps an HTTP function handler adding it error capture and tracing capabilities.
+ *
+ * @param handler Handler
+ * @param options Options
+ * @returns Handler
+ */
+export function wrapHttp(fn: HttpFunction, wrapOptions: Partial<HttpWrapperOptions> = {}): HttpFunction {
+  const options: HttpWrapperOptions = {
+    flushTimeout: 2000,
+    parseRequestOptions: {},
+    ...wrapOptions,
+  };
+  const domain = require('domain');
+  return (req, res) => {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    const activeDomain = domain.active as Domain;
+    const reqMethod = (req.method || '').toUpperCase();
+    const reqUrl = req.url && stripUrlQueryAndFragment(req.url);
+
+    const transaction = startTransaction({
+      name: `${reqMethod} ${reqUrl}`,
+      op: 'gcp.function.http',
+    });
+
+    // We put the transaction on the scope so users can attach children to it
+    getCurrentHub().configureScope(scope => {
+      scope.setSpan(transaction);
+    });
+
+    // We also set __sentry_transaction on the response so people can grab the transaction there to add
+    // spans to it later.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-member-access
+    (res as any).__sentry_transaction = transaction;
+
+    // functions-framework creates a domain for each incoming request so we take advantage of this fact and add an error handler.
+    // BTW this is the only way to catch any exception occured during request lifecycle.
+    activeDomain.on('error', err => {
+      captureRequestError(err, req, options.parseRequestOptions);
+    });
+
+    // eslint-disable-next-line @typescript-eslint/unbound-method
+    const _end = res.end;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    res.end = function(chunk?: any | (() => void), encoding?: string | (() => void), cb?: () => void): void {
+      transaction.setHttpStatus(res.statusCode);
+      transaction.finish();
+
+      flush(options.flushTimeout)
+        .then(() => {
+          _end.call(this, chunk, encoding, cb);
+        })
+        .then(null, e => {
+          logger.error(e);
+        });
+    };
+
+    return fn(req, res);
+  };
+}

packages/serverless/src/index.ts

@@ -1,5 +1,6 @@
 // https://medium.com/unsplash/named-namespace-imports-7345212bbffb
 import * as AWSLambda from './awslambda';
-export { AWSLambda };
+import * as GCPFunction from './gcpfunction';
+export { AWSLambda, GCPFunction };
 
 export * from '@sentry/node';

packages/serverless/test/__mocks__/@sentry/node.ts

@@ -1,3 +1,5 @@
+const origSentry = jest.requireActual('@sentry/node');
+export const Handlers = origSentry.Handlers; // eslint-disable-line @typescript-eslint/no-unsafe-member-access
 export const SDK_VERSION = '6.6.6';
 export const Severity = {
   Warning: 'warning',
@@ -16,6 +18,7 @@ export const fakeScope = {
 };
 export const fakeTransaction = {
   finish: jest.fn(),
+  setHttpStatus: jest.fn(),
 };
 export const getCurrentHub = jest.fn(() => fakeHub);
 export const startTransaction = jest.fn(_ => fakeTransaction);
@@ -25,6 +28,7 @@ export const withScope = jest.fn(cb => cb(fakeScope));
 export const flush = jest.fn(() => Promise.resolve());
 
 export const resetMocks = (): void => {
+  fakeTransaction.setHttpStatus.mockClear();
   fakeTransaction.finish.mockClear();
   fakeParentScope.setSpan.mockClear();
   fakeHub.configureScope.mockClear();

packages/serverless/test/gcpfunction.test.ts

@@ -0,0 +1,187 @@
+import { Event } from '@sentry/types';
+import * as domain from 'domain';
+import * as os from 'os';
+
+import * as Sentry from '../src';
+import { HttpFunction, Request, Response, wrapHttp } from '../src/gcpfunction';
+
+/**
+ * Why @ts-ignore some Sentry.X calls
+ *
+ * A hack-ish way to contain everything related to mocks in the same __mocks__ file.
+ * Thanks to this, we don't have to do more magic than necessary. Just add and export desired method and assert on it.
+ */
+
+describe('GCPFunction', () => {
+  afterEach(() => {
+    // @ts-ignore see "Why @ts-ignore" note
+    Sentry.resetMocks();
+  });
+
+  async function invokeHttp(fn: HttpFunction): Promise<void> {
+    return new Promise((resolve, _reject) => {
+      const d = domain.create();
+      const req = {
+        method: 'GET',
+        host: 'hostname',
+        cookies: {},
+        query: {},
+        url: '/path',
+        headers: {},
+      } as Request;
+      const res = { end: resolve } as Response;
+      d.on('error', () => res.end());
+      d.run(() => process.nextTick(fn, req, res));
+    });
+  }
+
+  describe('wrapHttp() options', () => {
+    test('flushTimeout', async () => {
+      expect.assertions(1);
+
+      const handler: HttpFunction = (_, res) => {
+        res.end();
+      };
+      const wrappedHandler = wrapHttp(handler, { flushTimeout: 1337 });
+
+      await invokeHttp(wrappedHandler);
+      expect(Sentry.flush).toBeCalledWith(1337);
+    });
+  });
+
+  describe('wrapHandler()', () => {
+    test('successful execution', async () => {
+      expect.assertions(5);
+
+      const handler: HttpFunction = (_, res) => {
+        res.statusCode = 200;
+        res.end();
+      };
+      const wrappedHandler = wrapHttp(handler);
+      await invokeHttp(wrappedHandler);
+      expect(Sentry.startTransaction).toBeCalledWith({ name: 'GET /path', op: 'gcp.function.http' });
+      // @ts-ignore see "Why @ts-ignore" note
+      expect(Sentry.fakeParentScope.setSpan).toBeCalledWith(Sentry.fakeTransaction);
+      // @ts-ignore see "Why @ts-ignore" note
+      expect(Sentry.fakeTransaction.setHttpStatus).toBeCalledWith(200);
+      // @ts-ignore see "Why @ts-ignore" note
+      expect(Sentry.fakeTransaction.finish).toBeCalled();
+      expect(Sentry.flush).toBeCalledWith(2000);
+    });
+
+    test('capture error', async () => {
+      expect.assertions(5);
+
+      const error = new Error('wat');
+      const handler: HttpFunction = (_req, _res) => {
+        throw error;
+      };
+      const wrappedHandler = wrapHttp(handler);
+      await invokeHttp(wrappedHandler);
+      expect(Sentry.startTransaction).toBeCalledWith({ name: 'GET /path', op: 'gcp.function.http' });
+      // @ts-ignore see "Why @ts-ignore" note
+      expect(Sentry.fakeParentScope.setSpan).toBeCalledWith(Sentry.fakeTransaction);
+      expect(Sentry.captureException).toBeCalledWith(error);
+      // @ts-ignore see "Why @ts-ignore" note
+      expect(Sentry.fakeTransaction.finish).toBeCalled();
+      expect(Sentry.flush).toBeCalled();
+    });
+  });
+
+  test('enhance event with SDK info and correct mechanism value', async () => {
+    expect.assertions(2);
+
+    const error = new Error('wat');
+    const handler: HttpFunction = () => {
+      throw error;
+    };
+    const wrappedHandler = wrapHttp(handler);
+
+    const expectedEventData = {
+      exception: {
+        values: [
+          {
+            mechanism: {
+              handled: false,
+            },
+          },
+        ],
+      },
+      request: {
+        cookies: {},
+        headers: {},
+        method: 'GET',
+        query_string: null,
+        url: 'http://hostname/path',
+      },
+      server_name: os.hostname(),
+      transaction: 'GET /path',
+      user: {},
+      contexts: {
+        runtime: {
+          name: 'node',
+          version: global.process.version,
+        },
+      },
+    };
+
+    const eventWithSomeData = {
+      exception: {
+        values: [{}],
+      },
+      sdk: {
+        integrations: ['SomeIntegration'],
+        packages: [
+          {
+            name: 'some:@random/package',
+            version: '1337',
+          },
+        ],
+      },
+    };
+    // @ts-ignore see "Why @ts-ignore" note
+    Sentry.fakeScope.addEventProcessor.mockImplementationOnce(cb => cb(eventWithSomeData));
+    await invokeHttp(wrappedHandler);
+    expect(eventWithSomeData).toEqual({
+      ...expectedEventData,
+      sdk: {
+        name: 'sentry.javascript.serverless',
+        integrations: ['SomeIntegration', 'GCPFunction'],
+        packages: [
+          {
+            name: 'some:@random/package',
+            version: '1337',
+          },
+          {
+            name: 'npm:@sentry/serverless',
+            version: '6.6.6',
+          },
+        ],
+        version: '6.6.6',
+      },
+    });
+
+    const eventWithoutAnyData: Event = {
+      exception: {
+        values: [{}],
+      },
+    };
+    // @ts-ignore see "Why @ts-ignore" note
+    Sentry.fakeScope.addEventProcessor.mockImplementationOnce(cb => cb(eventWithoutAnyData));
+    await invokeHttp(wrappedHandler);
+    expect(eventWithoutAnyData).toEqual({
+      ...expectedEventData,
+      sdk: {
+        name: 'sentry.javascript.serverless',
+        integrations: ['GCPFunction'],
+        packages: [
+          {
+            name: 'npm:@sentry/serverless',
+            version: '6.6.6',
+          },
+        ],
+        version: '6.6.6',
+      },
+    });
+  });
+});