Error Tracking

Betterlytics captures client-side errors from your site and sends them to your dashboard. Identical errors are automatically grouped so you can track unique issues over time.

Quick start

Using the script tag

Add data-track-errors="true" to your analytics script to start capturing errors and data-track-console-errors="true" to also capture console.error() calls:

<script
  async
  src="https://betterlytics.io/analytics.js"
  data-site-id="your-siteid"
  data-track-errors="true"
  data-track-console-errors="true"
>
</script>

Configuration reference

Using the npm package

Error tracking is disabled by default. Enable it with trackErrors:

import betterlytics from '@betterlytics/tracker';
 
betterlytics.init('your-site-id', {
  trackErrors: true, // true | false (default)
});

To also capture console.error() calls:

betterlytics.init('your-site-id', {
  trackErrors: true,
  trackConsoleErrors: true, // true | false (default)
});

See the package docs for the full API and options: @betterlytics/tracker on npm .

What gets captured

Betterlytics captures three types of errors:

• JavaScript errors: runtime errors like TypeError, ReferenceError, etc. that are not caught by your code.
• Failed promises: promises that reject without being handled.
• Console errors (optional): console.error() calls. Enable with data-track-console-errors="true".

Errors and Session Replay

When error tracking is combined with Session Replay, errors are automatically linked to replay recordings. You can jump from any error in the dashboard directly to the session replay to see what the user experienced.

If a session is already being recorded, errors are linked to it automatically with no extra configuration needed.

Error-triggered replay

For sessions that are not being recorded, you can enable data-replay-on-error to capture a replay anyway. Betterlytics records in the background and only uploads when an error occurs, giving you around 1-2 minutes of context before the error. Sessions without errors are never uploaded.

<script
  async
  src="https://betterlytics.io/analytics.js"
  data-site-id="your-siteid"
  data-track-errors="true"
  data-replay="true"
  data-consent-replay="true"
  data-replay-on-error="true"
>
</script>

Or with the npm package:

betterlytics.init('your-site-id', {
  enableSessionReplay: true,
  trackErrors: true,
  replayOnError: true, // true | false (default)
});

Scripts hosted on a CDN or different domain

If your JavaScript is served from a different domain than your page, browsers block error details from cross-origin scripts. You will only see "Script error." with no stack trace.

To fix this, add crossorigin="anonymous" to your script tags and make sure your CDN is configured to allow it:

<script src="https://cdn.example.com/app.js" crossorigin="anonymous"></script>

Privacy

Error messages may occasionally contain sensitive data, such as URLs with user IDs. Make sure your application does not include personal data in error messages.

Best practices

• Enable alongside Session Replay to get full context for every error.
• Use data-track-console-errors if your dependencies log errors rather than throw them.
• Triage errors regularly using the Resolved and Ignored statuses.
• Check for new error groups after each deploy.

Troubleshooting

• No errors appearing: Verify data-track-errors="true" is set on your analytics script.
• Missing stack traces: If you only see "Script error.", see Scripts hosted on a CDN or different domain.
• Console errors not captured: Set data-track-console-errors="true" alongside data-track-errors="true".

Next steps: Learn how to view and manage errors in the Error Tracking dashboard.