feat(nextjs): Add exception handler for _error.js (#5259)

In order to have Sentry capture certain kinds of errors in nextjs, users need to add a custom `_error.js` file to their projects. We do this automatically when users go through the wizard setup, but [the file we've been adding](https://github.com/getsentry/sentry-wizard/blob/v1.2.17/scripts/NextJs/configs/_error.js) is just a clone of the one in vercel's `with-sentry` nextjs example app, and is simultaneously quite verbose and pretty bare-bones in terms of what it does. (This is not a knock on the folks who wrote it, who don't have the context we do, but the fact remains that it could stand to be improved.)

This does so, by creating a utility function, `captureUnderscoreErrorException`, for users to use in place of the manual edge-case handling and `captureException` calls in the original. In addition to cleaning things up, this allows us to modify behavior, fix bugs, and add features without users having to update their code. (Existing users will have to update to use the function, of course, but after that they should never have to touch it again. And for new users, it'll be a set-it-and-forget-it.)

With this change, the `_error.js` we add with the wizard becomes just

```js
import * as Sentry from '@sentry/nextjs';
import NextErrorComponent from 'next/error';

const CustomErrorComponent = props => {
  Sentry.captureUnderscoreErrorException(props);
  return <NextErrorComponent statusCode={props.statusCode} />;
};

CustomErrorComponent.getInitialProps = async contextData => {
  await Sentry.captureUnderscoreErrorException(contextData);
  return NextErrorComponent.getInitialProps(contextData);
};

export default CustomErrorComponent;
```
(The real copy has helpful comments, but they've been removed here for the sake of brevity.)

And speaking of adding features... why not start now? This new function improves on the existing code by:
- filtering out all 400-type errors, not just 404s,
- annotating errors with a `mechanism` value,
- adding request data to the event when available, and
- capturing a message when falsy errors are thrown.

(See the PR for screenshots of the difference adding this data makes.)

The file injected by the wizard is updated in getsentry/sentry-wizard#170, and the file used in the `with-sentry` example app is updated in vercel/next.js#37866.

Author: lobsterkatie

packages/nextjs/src/index.client.ts

@@ -9,6 +9,7 @@ import { addIntegration, UserIntegrations } from './utils/userIntegrations';
 
 export * from '@sentry/react';
 export { nextRouterInstrumentation } from './performance/client';
+export { captureUnderscoreErrorException } from './utils/_error';
 
 export { Integrations };
 

packages/nextjs/src/index.server.ts

@@ -12,6 +12,7 @@ import { NextjsOptions } from './utils/nextjsOptions';
 import { addIntegration } from './utils/userIntegrations';
 
 export * from '@sentry/node';
+export { captureUnderscoreErrorException } from './utils/_error';
 
 // Here we want to make sure to only include what doesn't have browser specifics
 // because or SSR of next.js we can only use this.
@@ -74,7 +75,7 @@ export function init(options: NextjsOptions): void {
     return event.type === 'transaction' && event.transaction === '/404' ? null : event;
   };
 
-  filterTransactions.id = 'NextServer404Filter';
+  filterTransactions.id = 'NextServer404TransactionFilter';
 
   configureScope(scope => {
     scope.setTag('runtime', 'node');

packages/nextjs/src/utils/_error.ts

@@ -0,0 +1,78 @@
+import { captureException, withScope } from '@sentry/core';
+import { getCurrentHub } from '@sentry/hub';
+import { addExceptionMechanism, addRequestDataToEvent, objectify } from '@sentry/utils';
+import { NextPageContext } from 'next';
+
+type ContextOrProps = {
+  [key: string]: unknown;
+  req?: NextPageContext['req'];
+  res?: NextPageContext['res'];
+  err?: NextPageContext['err'] | string;
+  statusCode?: number;
+};
+
+/** Platform-agnostic version of `flush` */
+function flush(timeout?: number): PromiseLike<boolean> {
+  const client = getCurrentHub().getClient();
+  return client ? client.flush(timeout) : Promise.resolve(false);
+}
+
+/**
+ * Capture the exception passed by nextjs to the `_error` page, adding context data as appropriate.
+ *
+ * @param contextOrProps The data passed to either `getInitialProps` or `render` by nextjs
+ */
+export async function captureUnderscoreErrorException(contextOrProps: ContextOrProps): Promise<void> {
+  const { req, res, err } = contextOrProps;
+
+  // 404s (and other 400-y friends) can trigger `_error`, but we don't want to send them to Sentry
+  const statusCode = (res && res.statusCode) || contextOrProps.statusCode;
+  if (statusCode && statusCode < 500) {
+    return Promise.resolve();
+  }
+
+  // Nextjs only passes the pathname in the context data given to `getInitialProps`, not the main render function, but
+  // unlike `req` and `res`, for which that also applies, it passes it on both server and client.
+  //
+  // TODO: This check is only necessary because of the workaround for https://github.com/vercel/next.js/issues/8592
+  // explained below. Once that's fixed, we'll have to keep the `inGetInitialProps` check, because lots of people will
+  // still call this function in their custom error component's `render` function, but we can get rid of the check for
+  // `err` and just always bail if we're not in `getInitialProps`.
+  const inGetInitialProps = contextOrProps.pathname !== undefined;
+  if (!inGetInitialProps && !err) {
+    return Promise.resolve();
+  }
+
+  withScope(scope => {
+    scope.addEventProcessor(event => {
+      addExceptionMechanism(event, {
+        type: 'instrument',
+        handled: true,
+        data: {
+          // TODO: Get rid of second half of ternary once https://github.com/vercel/next.js/issues/8592 is fixed.
+          function: inGetInitialProps ? '_error.getInitialProps' : '_error.customErrorComponent',
+        },
+      });
+      return event;
+    });
+
+    if (req) {
+      scope.addEventProcessor(event => addRequestDataToEvent(event, req));
+    }
+
+    // If third-party libraries (or users themselves) throw something falsy, we want to capture it as a message (which
+    // is what passing a string to `captureException` will wind up doing)
+    const finalError = err || `_error.js called with falsy error (${err})`;
+
+    // In case we have a primitive, wrap it in the equivalent wrapper class (string -> String, etc.) so that we can
+    // store a seen flag on it. (Because of https://github.com/vercel/next.js/issues/8592, it can happen that the custom
+    // error component's `getInitialProps` won't have run, so we have people call this function in their error
+    // component's main render function in addition to in its `getInitialProps`, just in case. By forcing it to be an
+    // object, we can flag it as seen, so that if we hit this a second time, we can no-op.)
+    captureException(objectify(finalError));
+  });
+
+  // In case this is being run as part of a serverless function (as is the case with the server half of nextjs apps
+  // deployed to vercel), make sure the error gets sent to Sentry before the lambda exits.
+  await flush(2000);
+}