Documentation Grafana Cloud Monitor applications Frontend Observability Instrument Errors instrumentation

Error tracking

Applications can sometimes produce errors, but because they run in a browser, developers are unaware that they’re occurring. In addition, users don’t always report errors, which adds to the complexity of troubleshooting them.

The error instrumentation subscribes to the browser’s window.onerror and onunhandledrejection events to collect them, extract the stack trace if available, and report them to the Grafana Faro Web SDK core API using the faro.api.pushError() function.

Tracking errors helps you to:

• Analyze anomalies that occur in your application (crashes, incorrect behavior)
• Monitor that your application is working as expected
• Detect issues with external systems that your application is using

The error instrumentation should always be enabled as it is the only way to automatically capture errors. You can, however, disable this instrumentation if you are tracking errors by other means.

ts Copy

const buggyFn = () => {
  throw new Error('Buggy function');
};

try {
  buggyFn();
} catch (err) {
  // Re-throw the error so it can be caught by the instrumentation
  throw err;

  // Alternatively, report it manually
  faro.api.pushError(err);
}

How to use the error instrumentation

The following error instrumentation is enabled by default. No additional configuration is required.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
});

To manually include the error instrumentation, use the following getWebInstrumentations helper function.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  instrumentations: [...getWebInstrumentations()],
});

Alternatively, if you want to fine-tune which instruments are enabled, you can use the following ErrorInstrumentation class.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  instrumentations: [new ErrorsInstrumentation()],
});

Exclude errors

Ignore errors from tracking. Ignored errors can either be defined as strings or regular expression patterns.

ts Copy

initializeFaro({
  url: 'https://my-domain.my-tld/collect/{app-key}',
  app: {
    name: 'my-app',
  },
  instrumentations: [...getWebInstrumentations()],
  ignoreErrors: ['My Error', /.*other-error.*/],
});