Searching and monitoring issues

What is an issue?

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.

Exception events are grouped into issues based on event information, such as the exception type, message, and stack trace. The data used for grouping depends on what is available.

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.

You can also manually combine two or more issues by merging them.

Issue list

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.

Issue page

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.

Finding specific issues

You can use the search bar at the top of the issue page to filter issues based on the properties of the exceptions in that issue.

Search results are matched based on properties of exceptions grouped into the issues. For example, if you search for "TypeError", we show you all issues where any exception grouped into the issue has a type of "TypeError".

The search bar provides two modes of filtering:

• Exact property filtering, which operates like property filters elsewhere in PostHog, enabling you to add terms like where 'http_referer' is set or where 'library' equals 'web'.

• Freeform text search, which does text matching for a subset of the error tracking specific properties of the exception event.

You add a property filter by clicking the property name shown here:

Added property filters look like this:

The results of both of these filter types (property filters and freeform search) are ANDed together, such that only exceptions that match all filters are included in the search results.

Freeform text search

The freeform search splits the text you give it into tokens. The search matches an exception if each of the tokens in your search term appear in one of the following:

• The exception type
• The exception message
• The function names in the exception stack trace (if known)
• The file paths in the exception stack trace (if known)

For example, imagine you have an exception that looks like this:

TypeError: Cannot read property 'name' of undefined
    at Object.<anonymous> (/path/to/myfile.js:123:45)
    at Module._compile (module.js:653:30)
    at Object.Module._extensions..js (module.js:664:10)
    at Module.load (module.js:566:32)
    at tryModuleLoad (module.js:506:12)
    at Function.Module._load (module.js:498:3)
    at Function.Module.runMain (module.js:694:10)
    at startup (bootstrap_node.js:204:16)
    at bootstrap_node.js:625:3

If you search for the term TypeError myfile.js, the exception matches this search, as it contains TypeError (as the exception type) and myfile.js (as a file path in the stack trace).

If you search for TypeError myfile.js abc, the exception would not match, as the token abc does not appear anywhere in freeform search properties.

If you want to search for longer exact strings, e.g. a particular exception message, you can group tokens into a single term using quotes, e.g. "Cannot read property 'name' of undefined" myfile.js would match, and "Cannot read property of myfile.js" would not.

Note, perhaps unintuitively, Cannot read property of myfile.js would match, because the tokens are ungrouped, and all of them appear somewhere in the exception search properties.

Searching chained exceptions

Exception events can have more than one exception in them, due to language features like exception chaining. For freeform search, we put the types, messages, functions and file paths of all exceptions into one list, and match if the token appears in any of them.

For example, if you had a chained exception with the messages MyCustomError: Failed to load user and Cannot read property 'age' of undefined, searching for cannot read property would match the exception, because it matches one of the exception messages (property appears in the "root" one).

Filtering exception occurrences within an issue

Once you've found and opened the issue you want to investigate, you can use the same search interface to filter the exception list for a particular instance of the issue. This is particularly useful in cases where some exceptions in the issue have information others don't and you want to use that information for debugging.

Here's an example from our own systems. We select a recent occurrence of this issue to try and get more context on why it's happening, but the details available don't tell me much more than the stack trace:

Here, we've added a property filter on http_referer, which we think will be useful for our debugging and can then easily select an occurrence where that property is set:

Improving search performance

We try to return results to you within a second, but sometimes if you're querying over large amounts of data, it may take longer. The following can improve the search performance:

• Limit the time range you're searching over: 7 days is usually enough to get a sense for the trends of an issue over time.

• Use freeform search rather than property filters: Our freeform searches are generally faster than property filters, as the total amount of data processed is smaller.

If you find your queries timing out or taking more than 30 seconds, please let us know in-app! We're always looking for benchmarks to improve against.