Error tracking

⚠️ Error tracking is currently released as a feature preview. You can enable it from within your PostHog account.

Error tracking allows 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 and trigger surveys based on them exactly the same way you can for any other type of event.

Installation

Python

A minimum SDK version of v3.7.0 is required

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("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("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 it is possible to manually call the capture method.

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

Javascript

A minimum SDK version of v1.160.0 is required

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

It is also possible to manually capture exceptions using the JS SDK.

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. Aggregated counts and sparklines provide an indication of the severity of each group. Search makes it easy to find exceptions containing specific text, and filters allow you 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("<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

If you have any feedback during the alpha please share it with us.

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)