> AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt

# Querying exceptions – Error Tracking pocket guide

Canonical URL: https://posthog.com/learn/error-tracking/pocket-guide/querying-exceptions

## On this page

- [Join exceptions to the rest of Twig's data](#join-exceptions-to-the-rest-of-twigs-data)
- [Rank issues by bookings at risk](#rank-issues-by-bookings-at-risk)
- [Check whether an error makes guests leave](#check-whether-an-error-makes-guests-leave)
- [Watch what guests saw](#watch-what-guests-saw)
- [Start from one host's errors](#start-from-one-hosts-errors)
- [Find the errors behind support tickets](#find-the-errors-behind-support-tickets)
- [Reach the guests an error hit](#reach-the-guests-an-error-hit)
- [Catch new errors in experiments](#catch-new-errors-in-experiments)
- [Track crash-free sessions](#track-crash-free-sessions)

Chapter 05

# Querying exceptions – Error Tracking pocket guide

Now that Twig's engineers capture high quality exceptions, they can query them for analysis.

Here are ways Twig's engineers use other PostHog events to understand the impact of issues in error tracking.

Each check below has a prompt to give an agent on [Learn Error Tracking with your agent](https://posthog.com/learn/error-tracking/agent-prompts-and-mcp.md).

## Join exceptions to the rest of Twig's data

PostHog keeps Twig's events in one [context warehouse](https://posthog.com/docs/self-driving/context.md) with persons, groups, sessions, and the tables an app can [sync](https://posthog.com/docs/data-pipelines/sources.md) from other tools, like [Zendesk](https://posthog.com/docs/data-pipelines/sources/zendesk.md). [HogQL](https://posthog.com/docs/data-warehouse/sql.md) queries all of it together, so anything sent to PostHog can be joined to Twig's exceptions.

The engineers want to know which issue to fix first. The exception alone can't tell them, but each one carries the same context as Twig's other events:

-   Which guest hit it, in `distinct_id` and their person properties.
-   Which host's stay it was, in `$groups`.
-   Which session it happened in, in `$session_id`, which links to the replay.
-   Which page it happened on, in `$current_url`.
-   Which flag variant the guest saw, in `$feature/<flag-key>`.

Using these clues, Twig's engineers can piece together a more complete story.

[Issues and exceptions](https://posthog.com/docs/error-tracking/issues-and-exceptions.md) lists every property PostHog sets.

## Rank issues by bookings at risk

**Prerequisites**

-   Group analytics with hosts as a group, so each exception carries the host of the stay. [Configure group analytics](https://posthog.com/docs/product-analytics/group-analytics.md#set-up-group-analytics)
-   An `mrr` property on each host from a warehouse connection with [Stripe](https://posthog.com/docs/data-pipelines/sources/stripe.md). [Connect your payment data](https://posthog.com/docs/data-warehouse/warehouse-properties.md#set-up-a-warehouse-property)

Hosts pay Twig a monthly fee, which the engineers sync from Stripe as each host's `mrr`. They rank issues by the MRR of the hosts they hit. An issue that hits high-MRR hosts can matter more, even with fewer occurrences Fig. 1.

Book stay fails · 620 exceptions

$48,000

Payout statement fails · 180 exceptions

$16,000

Stay search times out · 9,000 exceptions

$4,000

mrr

Fig. 1 – Example: issues ranked by the MRR of the hosts they hit. Stay search throws the most exceptions, but Book stay fails for hosts who pay twelve times as much.

This joins exceptions to hosts on `$groups`:

| Source | What it adds |
| --- | --- |
| `$exception` | The hosts each issue hit |
| `groups` | What each host pays, from its `mrr` property |

The [Errors in paying hosts](https://posthog.com/learn/error-tracking/pocket-guide/errors-in-paying-hosts.md) scout runs a related check every day. It reports issues concentrated in paying hosts.

## Check whether an error makes guests leave

**Prerequisites**

-   Session tracking to see what people did after an error. The web and mobile SDKs do this automatically. [Track sessions on your server](https://posthog.com/docs/data/sessions.md#server-sdks-and-sessions)

To see whether an error makes guests leave, the engineers check three things:

-   **Funnels.** The engineers build a [funnel](https://posthog.com/docs/product-analytics/funnels.md) of booking a stay on Twig, with its graph type set to [historical trends](https://posthog.com/docs/product-analytics/funnels.md#graph-type), to see whether conversion fell when the error appeared Fig. 2. They [break it down](https://posthog.com/docs/product-analytics/funnels.md#breakdowns) by the issue's cohort, created from the issue page, to compare people who hit the error with people who didn't.
-   **Retention.** They filter a [retention insight](https://posthog.com/docs/product-analytics/retention.md) to the issue's cohort and compare it with all users. If people who hit the error come back less, the error is driving churn.
-   **Session drop-off.** They check whether people did anything within a minute of each error. Some sessions end anyway, so they compare each issue with the overall drop-off.

Error first seen

300 fewer confirmed bookings per day

Clicked Book stay: 1,000/dayConfirmed: 800/day to 500/day

Fig. 2 – Example: Twig guests click Book stay as often as before, but the share that confirms a booking falls from 80% to 50% when the error appears.

The session drop-off check joins exceptions to the events that followed on `$session_id`:

| Source | What it adds |
| --- | --- |
| `$exception` | When the error fired |
| `$pageview` and Twig's named events, like `twig_stay_viewed` | Whether the guest kept going |

## Watch what guests saw

**Prerequisites**

-   Session replay to watch what people saw when the error happened. [Set up session replay](https://posthog.com/docs/session-replay/installation.md)
-   Recordings of every session with an error, so the right one exists. [Record sessions with errors](https://posthog.com/docs/session-replay/how-to-control-which-sessions-you-record.md#event-triggers)

When an error makes guests leave, the engineers watch their sessions to see what happened.

This joins exceptions to recordings on `$session_id`:

| Source | What it adds |
| --- | --- |
| `$exception` | The error and when it fired |
| `session_replay_events` | What the person saw and did |

## Start from one host's errors

**Prerequisites**

-   Group analytics with hosts as a group. [Configure group analytics](https://posthog.com/docs/product-analytics/group-analytics.md#set-up-group-analytics)

Triage can also start from a host. When a host reports a problem, the engineers rank every issue on that host's stays by how many guests it impacts Fig. 3. In the issue list, that's the host as a filter, sorted by **Users**.

Book stay fails · 314 exceptions

186

Payout statement fails · 41 exceptions

27

Stay search times out · 2,840 exceptions

2

users

Fig. 3 – Example: one host's issues, ranked by how many of the host's guests each one hit. Stay search fired 2,840 times for only 2 guests, which looks like a retry loop.

This joins exceptions to hosts on `$groups`:

| Source | What it adds |
| --- | --- |
| `$exception` | Each issue and how many guests it impacts |
| `groups` | Which host's stays those guests were on |

## Find the errors behind support tickets

**Prerequisites**

-   A support tool connected to PostHog, like [Zendesk](https://posthog.com/docs/data-pipelines/sources/zendesk.md) or [Intercom](https://posthog.com/docs/data-pipelines/sources/intercom.md). [Connect your support data](https://posthog.com/docs/data-pipelines/sources.md)
-   Replay links in tickets, so each ticket points to a session. [Add replay links to tickets](https://posthog.com/docs/session-replay/sharing.md#method-two-automatically-share-replays-to-intercom-or-crisp)

Guests and hosts reach Twig's support in Zendesk, which the engineers sync to PostHog. A ticket with an error behind it points at a bug they can fix.

This joins tickets to exceptions on the session ID in each ticket's replay link:

| Source | What it adds |
| --- | --- |
| A tickets table, like `zendesk.tickets` | What the customer reported |
| `$exception` | The error behind it |

## Reach the guests an error hit

**Prerequisites**

-   Identified users, so it's clear who to contact. [Identify your users](https://posthog.com/docs/getting-started/identify-users.md)

Once the engineers fix an issue, they tell the guests it hit, or survey them. They create a [cohort](https://posthog.com/docs/data/cohorts.md) from the issue page, then [duplicate it as a static cohort](https://posthog.com/docs/data/cohorts.md#can-you-use-a-dynamic-cohort-as-a-feature-flag-target) to target them with a survey or flag.

This joins exceptions to people on `distinct_id`:

| Source | What it adds |
| --- | --- |
| `$exception` | The issue each person hit |
| `persons` | Who they are, so the team can reach them |

## Catch new errors in experiments

**Prerequisites**

-   Feature flags sent with events, so it's clear which variant each person saw. [Send flags with your events](https://posthog.com/docs/feature-flags/adding-feature-flag-code.md)

When Twig ships a change as an [experiment](https://posthog.com/docs/experiments.md), the engineers add `$exception` as a [secondary metric](https://posthog.com/docs/experiments/metrics.md#primary-and-secondary-metrics) to compare errors across variants.

To see when errors started, they chart each variant's error rate Fig. 4. With an uneven split, they compare a ratio, like exceptions per pageview, so a variant on 5% of traffic compares fairly with one on 95%. The Feature Flags pocket guide covers [running the experiment](https://posthog.com/learn/feature-flags/pocket-guide/flag-to-experiment.md).

Booking form deploy

Control

2% of sessions hit an error

New booking form

2% to 8% of sessions hit an error

Fig. 4 – Example: after a deploy, Twig's new booking form's affected-session rate rises to 8% while control stays at 2%. Both lines use the same scale.

This joins exceptions to variants on `$feature/<flag-key>`:

| Source | What it adds |
| --- | --- |
| `$exception` | Errors in each variant |
| `$pageview` | Traffic in each variant, for the rate |

## Track crash-free sessions

**Prerequisites**

-   Exception autocapture, so unhandled exceptions are captured. On mobile, crash reporting in an ![](https://res.cloudinary.com/dmukukwp6/image/upload/Android_robot_bec2fb7318.svg) [Android](https://posthog.com/docs/error-tracking/installation/android.md), ![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/ios.svg) [iOS](https://posthog.com/docs/error-tracking/installation/ios.md), or ![](https://res.cloudinary.com/dmukukwp6/image/upload/posthog.com/contents/images/docs/integrate/react.svg) [React Native](https://posthog.com/docs/error-tracking/installation/react-native.md) app.

Twig is a web app, so the engineers track stability as the share of sessions without an unhandled exception.

This joins sessions to unhandled exceptions on `$session_id`:

| Source | What it adds |
| --- | --- |
| `sessions` | Every session |
| `$exception` with `$exception_handled` set to `false` | Which sessions hit an unhandled exception |

To rank your issues by the revenue they put at risk, give an agent the revenue skill Fig. 5.

error-tracking-errors-by-revenue/SKILL.md

```markdown
---
name: error-tracking-errors-by-revenue
description: >
  Build a PostHog insight that joins exceptions to your accounts and revenue, such as the new
  errors ranked by the MRR of the accounts they hit. Find the events, find the key that joins it,
  pick a chart, then adapt the example query to this project.
---

# Rank errors by what they put at risk

Read the current docs first. Every PostHog docs URL returns Markdown if you append `.md`:

- https://posthog.com/docs/data-warehouse/sql.md
- https://posthog.com/docs/product-analytics/group-analytics.md
- https://posthog.com/docs/data-warehouse/warehouse-properties.md

If the user hasn't said what to rank by, ask: MRR, ARR, plan, or seats. Then work through these
steps in order.

## 1. Find the events and properties

You need three things. Check that each one exists in this project before you write a query.

- **Exceptions.** `$exception` events. Each one has an `issue_id`, and
  `properties.$exception_list[1]` holds the error's type and message.
- **The account each exception came from.** Group types are defined by each project, so list this
  project's group types and find the one that represents an account, such as `company`. Note its
  index. If the project has no groups, look for an account property on persons, such as a company
  ID or email domain.
- **What each account is worth.** A property on that group, such as `mrr`, `arr`, or `plan`. Check
  that most accounts have a value.

If no account has a value, stop. Tell the user that warehouse properties can sync one from Stripe
or their database. Don't guess one.

## 2. Find the key that joins them

Each event's `$groups` property maps the project's group types to keys, such as
`{"company": "acme"}`. In HogQL, the same keys are the columns `$group_0` to `$group_4`, and the
index from step 1 picks the column.

- Check that most `$exception` events from the last 7 days have that key. If they don't, the SDK
  doesn't set the group when it captures exceptions. Tell the user, and point them to group
  analytics for their SDK.
- Join exceptions to the `groups` table on `groups.key` and `groups.index`.
- Count each account once per error. An account that hits an error 500 times is still one account.

## 3. Pick the shape

- One value per error reads best as a bar chart. In the SQL editor, open **Visualization**, pick
  **Horizontal bar chart**, and put the error label on the X-axis and the value on the Y-axis.
- Label each bar with the exception type and the start of its message. Issue IDs are unreadable on
  an axis.
- Show the top 10.
- Match the time window to the question. "New errors" means issues created in the last 7 days, from
  `system.error_tracking_issues`. To rank every error, drop that filter.
- Group by the issue ID as well as the label. Two issues can share a label.

## 4. Adapt the example

This query ranks the errors first seen in the last 7 days by the MRR of the accounts they hit. It
assumes the account group type has index 0 and an `mrr` property. Change the group index, the
property, and the time windows to match what you found in steps 1 and 2. Don't run it unchanged.

```sql
WITH issues AS (
    SELECT
        id AS issue_id,
        concat(name, ': ', substring(description, 1, 45)) AS error
    FROM system.error_tracking_issues
    WHERE created_at >= now() - INTERVAL 7 DAY
),
affected AS (
    SELECT DISTINCT issue_id, $group_0 AS account
    FROM events
    WHERE event = '$exception'
        AND timestamp >= now() - INTERVAL 7 DAY
        AND notEmpty($group_0)
        AND issue_id IN (SELECT issue_id FROM issues)
)
SELECT
    i.error AS error,
    round(sum(toFloat(g.properties.mrr))) AS mrr_at_risk
FROM affected a
JOIN issues i ON i.issue_id = a.issue_id
LEFT JOIN groups g ON g.key = a.account AND g.index = 0
GROUP BY i.issue_id, i.error
ORDER BY mrr_at_risk DESC
LIMIT 10
```

Run it and check the result. The values shouldn't all be zero, and the labels should be readable.
Then save it as an insight.

## Finally

Report the top three errors and what they put at risk. Say that the value is what those accounts
pay, not revenue the error lost.
```

Show full example

Fig. 5 – The skill that ranks errors by the revenue they put at risk. Copy it and give it to your agent.

[Triage and alerts →](https://posthog.com/learn/error-tracking/pocket-guide/triage-and-alerts.md)

**Explore further**

[Issues and exceptions](https://posthog.com/docs/error-tracking/issues-and-exceptions.md) · [Data warehouse joins](https://posthog.com/docs/data-warehouse/join.md) · [Features that drive revenue](https://posthog.com/learn/warehouse/pocket-guide/features-drive-revenue.md) · [Warehouse properties](https://posthog.com/docs/data-warehouse/warehouse-properties.md) · [Funnels](https://posthog.com/docs/product-analytics/funnels.md) · [Session Replay pocket guide](https://posthog.com/learn/session-replay/pocket-guide/configure-replays.md)