Sentry for Angular

Angular library to setup and configure Sentry projects easily on your applications.

Install

npm i @okode/ngx-sentry

Usage

Configure the Sentry Provider

All-in-one configuration:

• provideSentry: Initializes on bootstrap an configures Sentry with the following default features => withDefaultHttpInterceptor y withDefaultErrorHandler

import { provideSentry } from '@okode/ngx-sentry';

export const appConfig: ApplicationConfig = {
  providers: [
    ...
    provideSentry({
      dsn: 'YOUR_APP_DSN',
      enabled: true,
      release: '0.0.0',
      env: 'YOUR_APP_ENV', // <- dev, pre, pro
    }),
  ],
  ...
};

Fine-grained configuration by features:

• provideSentryWithFeatures: allow to configure Sentry with modular features and your own custom features. ( API REFERENCE -> SentryFeatures)

import { provideSentryWithFeatures, withConfig, withDefaultErrorHandler } from '@okode/ngx-sentry';

export const appConfig: ApplicationConfig = {
  providers: [
    ...
    provideSentryWithFeatures(
        withConfig({
        dsn: 'YOUR_APP_DSN',
        enabled: true,
        release: '0.0.0',
        env: 'YOUR_APP_ENV', // <- dev, pre, pro
      }),
      withDefaultErrorHandler(),
      // Add any other custom feature here
    ),
  ],
  ...
};

Manual initialization

The default provideSentry() function automatically initializes Sentry on bootstrap. If you want to init Sentry on some other point, you'll have to use provideSentryWithFeatures() function and avoid using withConfig().

import { provideSentryWithFeatures, withDefaultHttpErrorInterceptor, withDefaultErrorHandler } from '@okode/ngx-sentry';

export const appConfig: ApplicationConfig = {
  providers: [
    ...
    provideSentryWithFeatures(
      withDefaultHttpErrorInterceptor(),
      withDefaultErrorHandler()
    ),
    ...
  ],
...
};

Now, in some other point on your app, you can init() the SentryErrorReporterService.

// some other place

import { SentryErrorReporterService } from '@okode/ngx-sentry';
import { version } from './package.json';

export class OtherPlaceService {

constructor(private sentryService: SentryErrorReporterService) {
      this.sentryService.init({
      dsn: 'YOUR_APP_DSN',
      enabled: true,
      release: '0.0.0',
      env: 'YOUR_APP_ENV', // <- dev, pre, pro
      release: version,
    });
  }
...
}

Send a custom error

Send a custom error whenever you need.

import { SentryErrorReporterService } from '@okode/ngx-sentry';

export class OtherPlaceService {
  constructor(private sentryService: SentryErrorReporterService) {}

  sendCustomErrorWithError(): void {
    this.sentryService.sendCustomError('MY_ERROR', new Error('PoC Error'));
  }
}

Integration with microfrontends - Monitoring microfrontend errors

Supported since version 0.18.0+.

If a Javascript error happens in a microfrontend feature, this is registered as an application error because this error cannot be identified as external error by default. In addition, Sentry doesn't show any kind of useful information about this error because it doesn't belong to the application project, the trace is minified because there are no source maps, etc.

This library is able to identify and redirect errors that reference its own Sentry project without an extra effort. So, what we have to do is to customize the microfrontend build and to add some metadata that allows application/library to identify this errors as microfrontend errors and redirect them to its own Sentry project.

Remember uploading microfrontend source maps to its Sentry project after it is built, otherwise you will still see the trace minified.

Official docs

API

• API
  • Sentry Provider Functions
    • provideSentry(...)
    • provideSentryWithFeatures(...)
  • Sentry Features
    • withConfig(...)
    • withDefaultHttpErrorInterceptor()
    • withDefaultErrorHandler()
    • makeSentryFeature(...)
  • SentryErrorReporterService
    • init(...)
    • sendError(...)
    • sendServerError(...)
    • sendCustomError(...)
    • setUserScope(...)
  • SentryReportErrorHttpInterceptor
    • intercept(...)
  • SentryErrorHandler
    • handleError(...)
  • Models
    • Sentry Config
    • User
    • SentryFeature
    • SentryFeatureKind
  • FAQ
    • How to customize any error tracked in Sentry?

Sentry Provider Functions

provideSentry(...)

provideSentry(config: SentryConfigResolver) => EnvironmentProviders

Sets a Sentry default setup provider.

| Param | Type | | :----: | :------------------: | | config | SentryConfigResolver |

provideSentryWithFeatures(...)

 provideSentryWithFeatures(...features: SentryFeature<SentryFeatureKind>[]) => EnvironmentProviders

Sets a Sentry setup provider with additional features.

| Param | Type | | :------: | :--------------------------------: | | features | SentryFeature[] |

Sentry Features

withConfig(...)

withConfig(config: SentryConfigResolver) => SentryFeature<SentryFeatureKind.CONFIG>

Sets a custom SentryConfigRevolver and initializes Sentry.

| Param | Type | | :----: | :------------------: | | config | SentryConfigResolver |

withDefaultHttpErrorInterceptor()

withDefaultHttpErrorInterceptor() => SentryFeature<SentryFeatureKind.DEFAULT_HTTP_ERROR_INTERCEPTOR>

Provides the default HTTPErrorInterceptor service.

withDefaultErrorHandler()

withDefaultErrorHandler() => SentryFeature<SentryFeatureKind.DEFAULT_ERROR_HANDLER>

Provides the default ErrorHandler service.

makeSentryFeature(...)

makeSentryFeature<KindT extends SentryFeatureKind>(  kind: KindT,  providers: Provider[]) =>SentryFeature<KindT>

Creates a custom SentryFeature.

| Param | Type | | :-------: | :--------: | | kind | KindT | | providers | Provider[] |

SentryErrorReporterService

Sentry service that communication with Sentry.

init(...)

init(config: SentryConfig) => void

Initializes Sentry Service.

| Param | Type | | :----: | :----------: | | config | SentryConfig |

sendError(...)

sendError(error: unknown) => void

Sends Error.

| Param | Type | | :---: | :-----: | | error | unknown |

sendServerError(...)

sendServerError(error: HttpErrorResponse, req: HttpRequest<unknown>) => void

Sends Server Error.

| Param | Type | | :---: | :------------------: | | error | HttpErrorResponse | | req | HttpRequest |

sendCustomError(...)

sendCustomError(errorCode: string, error?: unknown, level: 'debug' | 'warning' = 'debug') => void

Sends Custom Error.

| Param | Type | | :-------: | :------------------: | | errorCode | string | | error | unknown | | level | 'debug' or 'warning' |

setUserScope(...)

setUserScope(sentryUserScope: User) => void

Sets a User scope.

| Param | Type | | :-------------: | :--: | | sentryUserScope | User |

SentryReportErrorHttpInterceptor

intercept(...)

intercept(request: HttpRequest<unknown>, next: HttpHandler) => Observable<HttpEvent<unknown>>

Intercepts HTTP Errors.

| Param | Type | | :-----: | :------------------: | | request | HttpRequest | | next | HttpHandler |

SentryErrorHandler

handleError(...)

handleError(error: unknow) => void

Handle thrown errors.

| Param | Type | | :---: | :-----: | | error | unknown |

Models

Sentry Config

| Param | Type | | :----------------: | :-------------------------------------------------------------------------------: | | dsn | string | | enabled | boolean | | env | string | | release | string | | dist | string | | denyUrls | (RegExp | string)[] | | debug | boolean | | logErrors | boolean | | tracesSampleRate | number | | ignoreErrors | (RegExp | string)[] | | beforeSend | (event:ErrorEvent, hint:EventHint) => PromiseLike<Event | null> | Event | null | | integrationsConfig | { browserTracing: { tracePropagationTargets?:string[];} } |

Default denyUrls

  /extensions\//i,
  /^chrome:\/\//i,
  /safari-extension:/i,
  /ruxitagentjs/i,
  /googletagmanager/i,
  /pagead\/js/i,
  /\/(gtm|ga|analytics)\.js/i,
  /facebook\.com/i,
  /connect\.facebook\.net/i,
  /ubembed\.com/i,
  /cdn\.cookielaw\.org/i,
  /onetrust\.org/i,
  /googleapis\.com/i,
  /chatasistencia\/auraFW\//i,
  /embeddedService\/liveAgentStateChat\//i,
  /force\.com/i,
  /salesforceliveagent\.com/i,

User

| Param | Type | | :-----------: | :--------------: | | [key: string] | any | | id | string | number | | ip_address | string | | email | string | | username | string | | segment | string |

SentryFeature

| Param | Type | | :--------: | :--------: | | ekind | KindT | | eproviders | Provider[] |

SentryFeatureKind

| ENUM | | :----------------------------: | | CONFIG | | DEFAULT_HTTP_ERROR_INTERCEPTOR | | DEFAULT_ERROR_HANDLER |

FAQ

How to customize any error tracked in Sentry?

In the Sentry library, most use cases for error monitoring are covered, but it's always possible that additional aspects need to be implemented for specific project needs. For this reason, the Sentry library is extensible and can be customized.

To achieve this, you need to create a new service in your application, for example, sentry-reporter-service-ext.service.ts. This service should extend the class you want to modify.

In the providers of your application, you need to indicate that the new service created will replace the Sentry service from the library as follows:

{ provide: SentryErrorReporterService, useExisting: SentryErrorReporterServiceExt }

To customize error monitoring according to your specific requirements or to add new features, you'll need to use the @override annotation to replace or extend the functionality of the existing functions.

export class SentryErrorReporterServiceExt extends SentryErrorReporterService {

  constructor(
    @Inject(INJECTOR) injector: Injector,
    @Inject(PLATFORM_ID) platformId: string,
    @Inject(DOCUMENT) document: Document,
  ) {
    super(injector, platformId, document);
  }

  override sendError(error: unknown) {
    // [Your custom implementation]
  }
}