This page introduces the concept of issues and exceptions, how they fit into the error tracking workflow, and how you can work with them.
What is an exception?
Errors are initially captured as individual $exception events. Like other events in PostHog, they contain properties that you can use to filter and group them. You can also use them to create insights, filter recordings, trigger surveys, and more.
You can expect the following properties to be present in the exception events (in addition to the standard event properties):
| Name | Key | Example value |
|---|---|---|
$exception_list | List | A list of exceptions that occurred. In languages that support chained exceptions, the list will contain multiple items. Contains the following properties: |
└─ type | String | The type of exception that occurred |
└─ value | String | The message of the exception that occurred |
└─ stacktrace | Object | Contains a list of stack frames that occurred |
└─ mechanism | Object | If the stacktrace is handled and if it's synthetic |
$exception_fingerprint | String | A fingerprint of the exception |
$exception_level | String | The level of the severity of the error |
These captured properties are used to build a fingerprint of the exception, which is used to group similar exceptions into issues.
What is an issue?
Issues are groups of similar $exception events that share common event information, such as the exception type, message, and stack trace. They're the primary way you interact with captured exceptions in error tracking.
When working in the context of error tracking, PostHog groups similar exception events into issues to help you triage them and take action. You can do the following with issues:
- Mark the issue as active, suppressed, or resolved
- Assign the issue to a team member or role
- Connect the issue to an external tracking system like GitHub issues or Linear
- View session replays to help root cause the issue
How exceptions are grouped into issues
PostHog attempts to group similar exceptions into an issue automatically by their exception type, exception message, and stack traces. The quality of automatic grouping can vary depending on the data available.
You can customize issue grouping logic by using custom grouping rules, merging issues, or labeling exceptions with a custom fingerprint.
When multiple issue grouping methods apply, PostHog applies them in the following order:
- Client-side defined custom fingerprint using
$exception_fingerprint - Match custom grouping rules defined in PostHog
- If no user defined logic, fall back to automatic fingerprinting
We're working on improving our grouping algorithm. If you spot two issues that you think should have been one, or one issue that you think should have been split into two, please let us know in-app.