Error tracking

Available since v3.5.0

Error tracking captures JavaScript exceptions from your visitors' browsers and groups them into issues. Use it to find out which errors your visitors run into, how often they happen, and which pages, browsers, and releases are affected.

Use Cases#

• Catch errors in production that never showed up during testing.
• See which releases introduced new errors, and confirm that a fix worked.
• Prioritize fixes by the number of occurrences and affected visits.
• Watch the session or replay behind an error to see what the visitor did before it happened.

Usage#

Add the data-errors attribute to your tracking script to enable error tracking.

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-errors="true"
></script>

Once enabled, Umami automatically captures uncaught exceptions and unhandled promise rejections and reports them under the Errors tab for that website. Error tracking doesn't create pageviews or events, and it works when automatic pageview tracking is disabled.

You can also add the data-release and data-environment attributes to label every error with the version of your website and where it is running. Both can be used as filters. The environment defaults to production.

<script
  defer
  src="http://mywebsite.com/script.js"
  data-website-id="94db1cb1-74f4-4a40-ad6c-962362670409"
  data-errors="true"
  data-release="[email protected]"
  data-environment="production"
></script>

Errors are sent to the same collection endpoint as your pageviews and events, so they work with data-host-url, COLLECT_API_ENDPOINT, and proxies without any extra setup.

Reporting caught errors#

Errors that your code catches, such as those handled by a framework error boundary, are not captured automatically. Report them with umami.captureException().

try {
  checkout();
} catch (error) {
  umami.captureException(error);
}

You can pass an optional second argument to add context to the error.

umami.captureException(error, {
  release: '[email protected]',
  environment: 'production',
  tags: { feature: 'checkout' },
  fingerprint: ['checkout-payment'],
});

captureException() requires data-errors="true" and never throws, so it is safe to call from any error handler.

Viewing Errors#

Navigate to a website and click the Errors tab.

The list shows each issue with its status, number of occurrences, number of affected visits, and when it was first and last seen within the selected date range. The chart above the list shows daily error occurrences in UTC.

Use the filters to narrow the list by Status, Release, Environment, Browser, or Page path, or search for text in the error message.

Issues#

Umami groups errors into issues by the error type and its stack trace. If no stack trace is available, errors are grouped by their message. Use the fingerprint option of umami.captureException() to control grouping yourself.

Click on an issue to see its occurrences. Select an occurrence to see its stack trace, page, browser, operating system, device, release, environment, and tags.

From an occurrence you can click View session to open the visitor's session. If a replay was recorded at the time of the error, a View replay link is also shown.

Each issue has one of three statuses:

Changing the status of an issue doesn't stop new occurrences from being collected.

Privacy#

• Page URLs are recorded without query strings or hash values.
• Email addresses, JWTs, and values that look like passwords, secrets, tokens, or API keys are redacted from error messages and stack traces, both in the browser and on the server. This is best-effort, so don't rely on it to remove all sensitive data.
• Console logs, request bodies, cookies, and local variables are never collected.
• The data-before-send handler is called with the type error, so you can remove sensitive data from an error or cancel it before it is sent.

function beforeSendHandler(type, payload) {
  if (type === 'error' && payload.url.startsWith('/admin')) {
    return false;
  }
  return payload;
}

Error tracking also respects data-domains, data-do-not-track, and excluding your own visits.

Limits#

When the per-website limit is reached, the tracker pauses capture for a short time. On self-hosted installs you can change the limit with ERRORS_PER_MINUTE.