Questions regarding: Rolling your own Angular error handler

[bjornharvold]

Hi Team Sentry 👋🏻

The intention behind rolling my own is because we want to use it in our consumable Web Components and we don't want to catch any parent errors.

I asked this question earlier and your team members gave me a good head start to do this myself.

I started here: https://docs.sentry.io/platforms/javascript/troubleshooting/#using-a-client-directly
Then copied your default Angular error handler from here: https://github.com/getsentry/sentry-javascript/blob/master/packages/angular/src/errorhandler.ts

and made it my own like this:

import { HttpErrorResponse } from '@angular/common/http';
import type { ErrorHandler as AngularErrorHandler } from '@angular/core';
import { Inject, Injectable } from '@angular/core';
import * as Sentry from '@sentry/angular-ivy';
import type { Event } from '@sentry/types';
import { isString } from '@sentry/utils';
import { ENVIRONMENT, GIT } from '@wink/shared/util-tokens';
import { runOutsideAngular } from './zone';

/**
 * Options used to configure the behavior of the Angular ErrorHandler.
 */
export interface ErrorHandlerOptions {
  logErrors?: boolean;
  showDialog?: boolean;
  dialogOptions?: Sentry.ReportDialogOptions;
  /**
   * Custom implementation of error extraction from the raw value captured by the Angular.
   * @param error Value captured by Angular's ErrorHandler provider
   * @param defaultExtractor Default implementation that can be used as the fallback in case of custom implementation
   */
  extractor?(
    error: unknown,
    defaultExtractor: (error: unknown) => unknown,
  ): unknown;
}

// https://github.com/angular/angular/blob/master/packages/core/src/util/errors.ts
function tryToUnwrapZonejsError(error: unknown): unknown | Error {
  // TODO: once Angular14 is the minimum requirement ERROR_ORIGINAL_ERROR and
  //  getOriginalError from error.ts can be used directly.
  return error && (error as { ngOriginalError: Error }).ngOriginalError
    ? (error as { ngOriginalError: Error }).ngOriginalError
    : error;
}

function extractHttpModuleError(error: HttpErrorResponse): string | Error {
  // The `error` property of http exception can be either an `Error` object, which we can use directly...
  if (isErrorOrErrorLikeObject(error.error)) {
    return error.error;
  }

  // ... or an`ErrorEvent`, which can provide us with the message but no stack...
  if (error.error instanceof ErrorEvent && error.error.message) {
    return error.error.message;
  }

  // ...or the request body itself, which we can use as a message instead.
  if (typeof error.error === 'string') {
    return `Server returned code ${error.status} with body "${error.error}"`;
  }

  // If we don't have any detailed information, fallback to the request message itself.
  return error.message;
}

type ErrorCandidate = {
  name?: unknown;
  message?: unknown;
  stack?: unknown;
};

function isErrorOrErrorLikeObject(value: unknown): value is Error {
  if (value instanceof Error) {
    return true;
  }

  if (value === null || typeof value !== 'object') {
    return false;
  }

  const candidate = value as ErrorCandidate;

  return (
    isString(candidate.name) &&
    isString(candidate.message) &&
    (undefined === candidate.stack || isString(candidate.stack))
  );
}

/**
 * Implementation of Angular's ErrorHandler provider that can be used as a drop-in replacement for the stock one.
 */
@Injectable({ providedIn: 'root' })
export class SentryErrorHandler implements AngularErrorHandler {
  protected readonly _options: ErrorHandlerOptions;

  /* indicates if we already registered our the afterSendEvent handler */
  private _registeredAfterSendEventHandler;
  private _client: Sentry.BrowserClient;
  private _hub: Sentry.Hub;

  /**
   * Method called for every value captured through the ErrorHandler
   */
  public handleError(error: unknown): void {
    const extractedError = this._extractError(error) || 'Handled unknown error';

    // TODO how / when to these 2 methods best practices
    // this._hub.configureScope(scope => {

    // });
    // this._hub.withScope(scope => {

    // });

    // this._hub.withScope(scope => {

    // }),

    // Capture handled exception and send it to Sentry.
    const eventId = runOutsideAngular(() =>
      this._hub.captureException(extractedError),
    );

    // When in development mode, log the error to console for immediate feedback.
    if (this._options.logErrors) {
      // eslint-disable-next-line no-console
      console.error(extractedError);
    }

    // Optionally show user dialog to provide details on what happened.
    if (this._options.showDialog) {
      const client = this._hub.getClient();

      if (client && client.on && !this._registeredAfterSendEventHandler) {
        client.on('afterSendEvent', (event: Event) => {
          if (!event.type) {
            Sentry.showReportDialog({
              ...this._options.dialogOptions,
              eventId: event.event_id,
            });
          }
        });

        // We only want to register this hook once in the lifetime of the error handler
        this._registeredAfterSendEventHandler = true;
      } else if (!client || !client.on) {
        Sentry.showReportDialog({ ...this._options.dialogOptions, eventId });
      }
    }
  }

  /**
   * Used to pull a desired value that will be used to capture an event out of the raw value captured by ErrorHandler.
   */
  protected _extractError(error: unknown): unknown {
    // Allow custom overrides of extracting function
    if (this._options.extractor) {
      const defaultExtractor = this._defaultExtractor.bind(this);
      return this._options.extractor(error, defaultExtractor);
    }

    return this._defaultExtractor(error);
  }

  /**
   * Default implementation of error extraction that handles default error wrapping, HTTP responses, ErrorEvent and few other known cases.
   */
  protected _defaultExtractor(errorCandidate: unknown): unknown {
    const error = tryToUnwrapZonejsError(errorCandidate);

    // If it's http module error, extract as much information from it as we can.
    if (error instanceof HttpErrorResponse) {
      return extractHttpModuleError(error);
    }

    // We can handle messages and Error objects directly.
    if (typeof error === 'string' || isErrorOrErrorLikeObject(error)) {
      return error;
    }

    // Nothing was extracted, fallback to default error message.
    return null;
  }

  public constructor(
    @Inject(ENVIRONMENT) private readonly environment: any,
    @Inject(GIT) private readonly version: any,
    @Inject('errorHandlerOptions') options?: ErrorHandlerOptions,
  ) {
    this._registeredAfterSendEventHandler = false;

    if (environment?.sentry?.dsn == null || environment?.sentry?.dsn === '') {
      throw new Error(
        'Unable to instantiate SentryCustomErrorHandler. Reason: Missing sentry.dsn property in env file.',
      );
    }
    const dsn: string = environment.sentry.dsn;

    if (environment?.environment == null || environment?.environment === '') {
      throw new Error(
        'Unable to instantiate SentryCustomErrorHandler. Reason: Missing environment property in env file.',
      );
    }
    const env: string = environment.environment;

    if (version?.version == null || version?.version === '') {
      throw new Error(
        'Unable to instantiate SentryCustomErrorHandler. Reason: Missing version property in versions file.',
      );
    }
    const release: string = version.version;

    if (
      environment?.sentry?.networkDetailAllowUrls == null ||
      environment?.sentry?.networkDetailAllowUrls.length === 0
    ) {
      throw new Error(
        'Unable to instantiate SentryCustomErrorHandler. Reason: Missing sentry.networkDetailAllowUrls property in env file.',
      );
    }
    const networkDetailAllowUrls: Array<string | RegExp> =
      environment.sentry.networkDetailAllowUrls;
    const tracePropagationTargets: Array<string | RegExp> =
      environment.sentry.networkDetailAllowUrls;

    if (
      environment?.sentry?.networkRequestHeaders == null ||
      environment?.sentry?.networkRequestHeaders.length === 0
    ) {
      throw new Error(
        'Unable to instantiate SentryCustomErrorHandler. Reason: Missing sentry.networkRequestHeaders property in env file.',
      );
    }
    const networkRequestHeaders: Array<string> =
      environment.sentry.networkRequestHeaders;

    if (
      environment?.sentry?.networkResponseHeaders == null ||
      environment?.sentry?.networkResponseHeaders.length === 0
    ) {
      throw new Error(
        'Unable to instantiate SentryCustomErrorHandler. Reason: Missing sentry.networkResponseHeaders property in env file.',
      );
    }
    const networkResponseHeaders: Array<string> =
      environment.sentry.networkResponseHeaders;

    if (
      environment?.sentry?.tracingOrigins == null ||
      environment?.sentry?.tracingOrigins.length === 0
    ) {
      throw new Error(
        'Unable to instantiate SentryCustomErrorHandler. Reason: Missing sentry.tracingOrigins property in env file.',
      );
    }
    const tracingOrigins: Array<string> = environment.sentry.tracingOrigins;

    this._options = {
      logErrors: true,
      ...options,
    };

    const integrations = [
      ...Sentry.defaultIntegrations,
      new Sentry.Replay({
        networkDetailAllowUrls,
        networkRequestHeaders,
        networkResponseHeaders,
      }),
      new Sentry.BrowserProfilingIntegration(),
      new Sentry.BrowserTracing({
        tracingOrigins,
        routingInstrumentation: Sentry.routingInstrumentation,
      }),
    ];

    this._client = new Sentry.BrowserClient({
      dsn,
      release,
      environment: env,
      ignoreErrors: [
        'ResizeObserver loop limit exceeded',
        'Non-Error promise rejection captured with value: undefined',
      ],
      // beforeSend(event, hint) {
      //   const eventConditional = event?.exception?.values != null && event?.exception?.values[0]?.value?.startsWith('Non-Error exception captured');
      //   let messageConditional = false;

      //   if (hint?.originalException != null && hint?.originalException instanceof Error) {
      //     const originalExceptionError: Error = hint.originalException;
      //     messageConditional = originalExceptionError.message.startsWith('Non-Error exception captured');
      //   }
      //   /* eslint-disable */
      //   const isNonErrorException = eventConditional || messageConditional;
      //   /* eslint-enable */

      //   if (isNonErrorException) {
      //     // We want to ignore those kind of errors
      //     console.warn('Received a non-standard error', event);
      //     return null;
      //   }
      //   return event;
      // },
      // This sets the sample rate to be 10%. You may want this to be 100% while
      // in development and sample at a lower rate in production
      replaysSessionSampleRate: 0.1,
      // If the entire session is not sampled, use the below sample rate to sample
      // sessions when an error occurs.
      replaysOnErrorSampleRate: 1.0,
      transport: Sentry.makeFetchTransport,
      stackParser: Sentry.defaultStackParser,
      tracesSampleRate: 0.2,
      // Set `tracePropagationTargets` to control for which URLs distributed tracing should be enabled
      tracePropagationTargets,
      integrations,
    });

    this._hub = new Sentry.Hub(this._client);
  }
}

Now I have 2 questions regarding this implementation (note that all my references to Sentry here is from @sentry/angular-ivy):

1. I had to redo how the capture exception occurred. This was removed from the default error handler as you can see above:

const eventId = runOutsideAngular(() =>
      Sentry.captureException(extractedError, (scope: Scope) => {
        scope.addEventProcessor(event => {
          addExceptionMechanism(event, {
            type: 'angular',
            handled: false,
          });

          return event;
        });

        return scope;
      }),
    );

and replaced with:

const eventId = runOutsideAngular(() =>
      this._hub.captureException(extractedError),
    );

I am not sure how to do the same using the hub.withScope and I am thinking that if I don't do it, I wont get all the defaults scope that is currently available on all my errors through the Sentry UI (See screenshot).

2. Routing instrumentation

new Sentry.BrowserTracing({
        tracingOrigins,
        routingInstrumentation: Sentry.routingInstrumentation,
      }),

Is this going to be an issue in a Sentry "embedded context" such as the Angular error handler I have created? I see that it's reaching out to WINDOW.location and of course this will not be owned by me but by our integrators. Guessing I might not be able to enable tracing within a Web Component embedded in a foreign site. 🤔

Anything else I should be aware of and do you see any improvements that can be made to what we've implemented?

Feel free to use this code in your examples for other Angular folks passing by.

Bjorn 🍺