Error tracking

⚠️ Error tracking is currently released as a beta in feature preview. You can enable it from within your PostHog account. If you have any feedback during the beta, please share it with us.

Error tracking enables you to track, investigate, and resolve exceptions your customers face.

Errors are captured as $exception events which means that you can create insights, filter recordings, trigger surveys, and more in the same way you can for any other type of event.

Installation

Python

Note: A minimum SDK version of v3.7.0 is required, but we recommend keeping up to date with the latest version to ensure you have all of error tracking's features.

Exception autocapture can be enabled during initialization of the PostHog client to automatically capture any exception thrown by your Python application.

from posthog import Posthog

posthog = Posthog("<ph_project_api_key>", enable_exception_autocapture=True, ...)

If you're using Django 4.2+, you can enable the exception autocapture integration which will also automatically capture Django errors.

from posthog.exception_capture import Integrations

Posthog("<ph_project_api_key>", enable_exception_autocapture=True, exception_autocapture_integrations = [Integrations.Django])

For exceptions handled by your application that you would still like sent to PostHog, you can manually call the capture method:

posthog.capture_exception(e, 'user_distinct_id', properties=additional_properties)

Javascript

Note: A minimum SDK version of v1.160.0 is required, but we recommend keeping up to date with the latest version to ensure you have all of error tracking's features.

Exception autocapture within the JavaScript Web SDK is remotely controlled via the PostHog app.

It is also possible to manually capture exceptions:

posthog.captureException(error, additionalProperties)

Functionality

In addition to using events in insights, replays, and surveys as mentioned above customers can also visit the error tracking page.

Exceptions are grouped by type, each with aggregated counts and sparklines providing an indication of the severity of each group. You can also search for exceptions containing specific text and filter to see which exceptions affect certain users.

Clicking through to an individual group shows you all the associated exceptions, including the associated stack trace, active feature flags when the exception was captured, and a link to the relevant session replay.

Custom issue grouping

PostHog attempts to group the same exceptions as a single issue. An $exception_fingerprint property is generated during ingestion by PostHog and used to perform this grouping. Setting the $exception_fingerprint property on the frontend will override the default flow to allow for custom grouping of certain exceptions.

When using the captureException method you can provide $exception_fingerprint as an additional property in the functions second argument.

posthog.captureException(error, { $exception_fingerprint: "MyCustomGroup" })

Should an exception be autocaptured, you will need to modify the properties before the event is sent. The PostHog config offers a before_send hook that fires for each event. You can alter the event as part of this callback to add the property:

posthog.init("<ph_project_api_key>", {
  before_send: (event) => {
    if (event.event === "$exception") {
      const exceptionList = event.properties["$exception_list"] || []
      const exception = exceptionList.length > 0 ? exceptionList[0] : null;

      if (exception && exception["$exception_type"] == "SyntaxError") {
        event.properties["$exception_fingerprint"] = "MyCustomGroup"
      }    
    }
    return event
  }
})

Upcoming features

There is a long list of features on our roadmap but we're primarily working towards:

• Actioning exceptions (merging, assigning, resolving, etc)
• Alerting

FAQs

Are web workers supported?

Yes. Error tracking will work as long as you initialize PostHog in the web worker. You will need to disable any features that rely on the window object:

posthog.init(token, {
    ...
    autocapture: false,
    capture_pageview: false,
    capture_pageleave: false,
    disable_session_recording: true,
    disable_surveys: true,
});

To identify users in web workers you will need to pass the distinct ID. This can be done via an env variable or sending it via postMessage from your main application.

Can exceptions be sampled / ignored

Returning null for a given event in the before_send hook will cause it not to be captured. You may want to:

• Drop certain types of exceptions
• Randomly sample a subset of all exceptions
• Sample based on the events properties (e.g. URL or user)