Triaging Error Issues

1---
2name: triaging-error-issues
3description: >
4  Triage PostHog error tracking issues during a daily or on-call review.
5  Use when the user asks "what's broken?", "what new errors do we have?",
6  "show me top errors today", "what should I look at this morning",
7  or wants a prioritized list of active issues to work on. Surfaces new
8  and high-impact issues, ranks by users affected and recency, points at
9  linked replays, and proposes next actions (investigate, assign, suppress,
10  merge).
11---
12 
13# Triaging error tracking issues
14 
15When a user asks "what's broken?" or wants a daily error review, the goal is a short
16prioritized list of issues worth a human's attention — not a dump of every active
17issue. Most projects have hundreds of active issues; the few that matter are usually
18new (first seen in the last 24-48h), spiking, or affecting many distinct users.
19 
20## Available tools
21 
22| Tool                                        | Purpose                                                                   |
23| ------------------------------------------- | ------------------------------------------------------------------------- |
24| `posthog:query-error-tracking-issues-list`  | List + rank issues with aggregate metrics (occurrences, users, sessions)  |
25| `posthog:query-error-tracking-issue`        | Compact details for a single issue (status, assignee, top frame, release) |
26| `posthog:query-error-tracking-issue-events` | Sampled `$exception` events with stack, URL, browser, and `$session_id`   |
27| `posthog:query-session-recordings-list`     | Find replays of users hitting an issue                                    |
28| `posthog:inbox-reports-list`                | Pre-curated actionable signals if the project uses Inbox                  |
29 
30## Workflow
31 
32### Step 1 — Pick a window and a signal
33 
34Read the time window from the user's wording. Defaults if unspecified:
35 
36- "Today" / "this morning" / "right now" → `dateRange: { date_from: "-24h" }`
37- "This week" / "since Monday" → `-7d`
38- On-call shift handoff → `-24h`
39 
40Pick what "matters" means:
41 
42- **New issues** — `orderBy: "first_seen"`, `orderDirection: "DESC"`, tight window.
43  Catches regressions introduced by recent deploys.
44- **High-impact** — `orderBy: "users"` ranks by distinct users affected. Better than
45  raw occurrences for severity (one bot loop produces many occurrences but one user).
46- **Trending** — `orderBy: "occurrences"` over a short window vs a longer baseline
47  to spot spikes.
48 
49### Step 2 — Pull the candidate list
50 
51Start narrow and widen if too few issues come back:
52 
53```json
54posthog:query-error-tracking-issues-list
55{
56  "status": "active",
57  "orderBy": "users",
58  "orderDirection": "DESC",
59  "dateRange": { "date_from": "-24h" },
60  "limit": 20,
61  "volumeResolution": 24
62}
63```
64 
65Match `volumeResolution` to the window (24 buckets for `-24h`, 14 for `-14d`, etc.)
66so each row's sparkline has enough resolution to show a spike vs flat steady state.
67A single bucket only gives a total, not a shape.
68 
69For new-issues-only, run a parallel query with `orderBy: "first_seen"`:
70 
71```json
72{
73  "status": "active",
74  "orderBy": "first_seen",
75  "orderDirection": "DESC",
76  "dateRange": { "date_from": "-24h" },
77  "limit": 10
78}
79```
80 
81If a project mixes browser and server SDKs, the top-by-users list is usually drowned
82by server-side errors (each invocation often gets a fresh `distinct_id`). Narrow with
83the `library` filter — values match the SDK's `$lib`, not the npm package name, examples:
84 
85- `web` — posthog-js (browser)
86- `posthog-node`, `posthog-python`, `posthog-ruby`, `posthog-go`, `posthog-php`, `posthog-java`, `posthog-elixir` — server SDKs
87- `posthog-edge` — Cloudflare Workers / edge runtime
88- `posthog-ios`, `posthog-android`, `posthog-react-native`, `posthog-flutter` — mobile
89 
90### Step 3 — Filter the noise
91 
92The list will include known noise. Before presenting, drop or call out:
93 
94- Issues whose volume is flat over the window — they're not new, the user already
95  lives with them. Surface them only if they're in the top by users.
96- Bot-only issues — if all events come from headless browsers or crawler user agents,
97  flag for suppression (`suppressing-noisy-errors`) instead of triage.
98 
99If unsure whether an issue is new vs. recurring, compare `first_seen` to the start
100of the window:
101 
102- `first_seen` inside the window → new, worth attention
103- `first_seen` weeks ago but spiking now → regression worth attention
104- `first_seen` weeks ago, flat volume → background noise
105 
106### Step 4 — Add context for the top items
107 
108For the top 3-5 candidates, pull a sample exception so the summary includes a stack
109frame and URL, not just a title. Use `posthog:query-error-tracking-issue-events` rather than
110raw SQL — it returns normalized fields (`$exception_types`, `$exception_values`,
111`$current_url`, browser/OS, `$session_id`) and defaults to `onlyAppFrames: true` to
112strip vendor noise from the stack:
113 
114```json
115posthog:query-error-tracking-issue-events
116{
117  "issueId": "<issue_id>",
118  "limit": 1,
119  "verbosity": "stack"
120}
121```
122 
123If the user wants to see what users were doing, hand off to `finding-replay-for-issue`
124to pick the best linked recording. Don't fetch replays for every triaged issue — only
125the ones the user asks to dig into.
126 
127### Step 5 — Present the triage list
128 
129Lead with a one-line headline ("3 new issues in last 24h, 1 spike, 5 active
130high-impact"). Then a short table sorted by your chosen signal:
131 
132| Issue | First seen | Users | Sessions | Sample message                    | Suggested action           |
133| ----- | ---------- | ----- | -------- | --------------------------------- | -------------------------- |
134| ...   | 2h ago     | 142   | 198      | `TypeError ... at checkout.js:42` | Investigate                |
135| ...   | spike      | 67    | 89       | `Network request failed`          | Watch — likely transient   |
136| ...   | 3d ago     | 12    | 12       | `chrome-extension:// timeout`     | Suppress (extension noise) |
137 
138For each, suggest one of: **investigate** (`investigating-error-issue`), **assign**
139(`error-tracking-issues-partial-update`), **suppress** (`suppressing-noisy-errors`),
140**merge** (`grouping-noisy-errors`), or **resolve** if it's already known fixed.
141 
142## Tips
143 
144- A single deploy often surfaces several related new issues. If multiple new issues
145  share a `properties.$lib_version` (or `properties.$exception_releases` when the
146  SDK is configured to populate it), present them grouped — a rollback decision
147  rests on the cluster, not any one issue.
148- "Users" is the right severity proxy for user-facing apps. For backend services
149  without a real distinct_id concept, fall back to `sessions` or `occurrences`.
150- Don't auto-assign or auto-resolve as part of triage. Present the list and let the
151  user decide. Bulk actions belong in dedicated skills.
152- If the project uses Inbox (`posthog:inbox-reports-list`), check it first — PostHog
153  may have already curated the most actionable issues so you avoid re-deriving them.
154- Provide the issue URL (`/error_tracking/<id>`) for each row so the user can jump
155  straight to the issue page if they want to drill down themselves.
156