What does Crash Analytics do?

Cloud On-Premise

Crash Analytics is intended for developers, QA teams, DevOps engineers, and technical administrators responsible for maintaining websites or applications. This feature works with any website that uses the Matomo JavaScript tracker, including traditional websites and single-page applications (SPAs).

When an error is detected or reported, Crash Analytics creates a crash report in Matomo, providing diagnostic information to investigate unexpected errors, understand their impact, and resolve issues before they affect more users.

Crash Analytics complements your existing Matomo Analytics reports by recording technical errors separately from your visitor and traffic analytics. Recording crashes does not change your visitor, traffic, Ecommerce, or conversion reports.

What is considered a crash?

A crash is an unexpected error that interrupts the normal operation of a website or application. On websites, Crash Analytics automatically records:

  • unhandled JavaScript exceptions: errors that are not caught by your application’s code. These can interrupt page functionality or prevent parts of your website from working as expected.
  • unhandled Promise rejections: errors that occur during asynchronous operations, such as loading data from an API, when the application does not handle the failure.

Applications can also report exceptions and other errors to Crash Analytics manually. This is useful when your application detects an error that it can recover from, such as a failed API request or an unexpected application state.

Refer to the developer guides on how to track a crash manually and tracking application and server-side crashes.

Platform How crashes are collected
Websites The Matomo JavaScript tracker automatically records unhandled JavaScript exceptions and unhandled Promise rejections.
Websites using Matomo Tag Manager Matomo Tag Manager uses the Matomo JavaScript tracker. When automatic crash tracking is enabled, JavaScript errors are collected without additional Tag Manager configuration.

You can also report crashes manually by calling the Crash Analytics methods provided by the JavaScript tracker from your website code or a Custom HTML tag.
Server-side applications Report exceptions and errors manually using a supported Matomo Tracker SDK, such as PHP, or the HTTP Tracking API.
Mobile applications Native Android and iOS crashes are not detected automatically. Applications must explicitly report exceptions because there is currently no built-in support for automatically detecting application crashes or unresponsive apps.

What information is in a crash report?

A crash report contains the diagnostic information available for the reported error.

crash report

Privacy features can also limit the information available in crash reports. For example, when Enforce CNIL compliance is enabled, browser information is limited to the major version, and device type and screen resolution are not collected. See CNIL compliance and data availability.

Depending on the tracking configuration, crash reports can include:

  • the actions performed before the error occurred
  • the error type and error message
  • the stack trace
  • the category (if defined)
  • the source file, URL, or screen
  • the line and column number (where available)
  • browser, operating system, application version, or other platform information
  • the time the error occurred

Privacy considerations

Crash reports include technical information generated by your application, such as error messages or stack traces. Ensure your application does not include personal or sensitive information in exception messages or manually reported crash data, as Crash Analytics sends these values to Matomo.

Crash Analytics respects your Matomo privacy configuration. If tracking requires visitor consent and consent has not been granted, crash reports are not collected.

Does Crash Analytics affect website performance?

Crash Analytics is designed to have minimal impact on website performance. If an error occurs, Crash Analytics sends a small request to Matomo containing diagnostic information about the error. This request is asynchronous and is designed to have minimal impact on page rendering and user interactions.

The impact on performance depends on how frequently errors occur. Websites experiencing a large number of JavaScript errors will generate more crash reports and additional network requests until those issues are resolved.

Next steps

Next FAQ: Getting started