posthog/triaging-error-issues

Triaging error tracking issues

When a user asks "what's broken?" or wants a daily error review, the goal is a short prioritized list of issues worth a human's attention — not a dump of every active issue. Most projects have hundreds of active issues; the few that matter are usually new (first seen in the last 24-48h), spiking, or affecting many distinct users.

Available tools

| Tool | Purpose | | ------------------------------------------- | ------------------------------------------------------------------------- | | posthog:query-error-tracking-issues-list | List + rank issues with aggregate metrics (occurrences, users, sessions) | | posthog:query-error-tracking-issue | Compact details for a single issue (status, assignee, top frame, release) | | posthog:query-error-tracking-issue-events | Sampled $exception events with stack, URL, browser, and $session_id | | posthog:query-session-recordings-list | Find replays of users hitting an issue | | posthog:inbox-reports-list | Pre-curated actionable signals if the project uses Inbox |

Workflow

Step 1 — Pick a window and a signal

Read the time window from the user's wording. Defaults if unspecified:

• "Today" / "this morning" / "right now" → dateRange: { date_from: "-24h" }
• "This week" / "since Monday" → -7d
• On-call shift handoff → -24h

Pick what "matters" means:

• New issues — orderBy: "first_seen", orderDirection: "DESC", tight window. Catches regressions introduced by recent deploys.
• High-impact — orderBy: "users" ranks by distinct users affected. Better than raw occurrences for severity (one bot loop produces many occurrences but one user).
• Trending — orderBy: "occurrences" over a short window vs a longer baseline to spot spikes.

Step 2 — Pull the candidate list

Start narrow and widen if too few issues come back:

posthog:query-error-tracking-issues-list
{
  "status": "active",
  "orderBy": "users",
  "orderDirection": "DESC",
  "dateRange": { "date_from": "-24h" },
  "limit": 20,
  "volumeResolution": 24
}

Match volumeResolution to the window (24 buckets for -24h, 14 for -14d, etc.) so each row's sparkline has enough resolution to show a spike vs flat steady state. A single bucket only gives a total, not a shape.

For new-issues-only, run a parallel query with orderBy: "first_seen":

{
  "status": "active",
  "orderBy": "first_seen",
  "orderDirection": "DESC",
  "dateRange": { "date_from": "-24h" },
  "limit": 10
}

If a project mixes browser and server SDKs, the top-by-users list is usually drowned by server-side errors (each invocation often gets a fresh distinct_id). Narrow with the library filter — values match the SDK's $lib, not the npm package name, examples:

• web — posthog-js (browser)
• posthog-node, posthog-python, posthog-ruby, posthog-go, posthog-php, posthog-java, posthog-elixir — server SDKs
• posthog-edge — Cloudflare Workers / edge runtime
• posthog-ios, posthog-android, posthog-react-native, posthog-flutter — mobile

Step 3 — Filter the noise

The list will include known noise. Before presenting, drop or call out:

• Issues whose volume is flat over the window — they're not new, the user already lives with them. Surface them only if they're in the top by users.
• Bot-only issues — if all events come from headless browsers or crawler user agents, flag for suppression (suppressing-noisy-errors) instead of triage.

If unsure whether an issue is new vs. recurring, compare first_seen to the start of the window:

• first_seen inside the window → new, worth attention
• first_seen weeks ago but spiking now → regression worth attention
• first_seen weeks ago, flat volume → background noise

Step 4 — Add context for the top items

For the top 3-5 candidates, pull a sample exception so the summary includes a stack frame and URL, not just a title. Use posthog:query-error-tracking-issue-events rather than raw SQL — it returns normalized fields ($exception_types, $exception_values, $current_url, browser/OS, $session_id) and defaults to onlyAppFrames: true to strip vendor noise from the stack:

posthog:query-error-tracking-issue-events
{
  "issueId": "<issue_id>",
  "limit": 1,
  "verbosity": "stack"
}

If the user wants to see what users were doing, hand off to finding-replay-for-issue to pick the best linked recording. Don't fetch replays for every triaged issue — only the ones the user asks to dig into.

Step 5 — Present the triage list

Lead with a one-line headline ("3 new issues in last 24h, 1 spike, 5 active high-impact"). Then a short table sorted by your chosen signal:

| Issue | First seen | Users | Sessions | Sample message | Suggested action | | ----- | ---------- | ----- | -------- | --------------------------------- | -------------------------- | | ... | 2h ago | 142 | 198 | TypeError ... at checkout.js:42 | Investigate | | ... | spike | 67 | 89 | Network request failed | Watch — likely transient | | ... | 3d ago | 12 | 12 | chrome-extension:// timeout | Suppress (extension noise) |

For each, suggest one of: investigate (investigating-error-issue), assign (error-tracking-issues-partial-update), suppress (suppressing-noisy-errors), merge (grouping-noisy-errors), or resolve if it's already known fixed.

Tips

• A single deploy often surfaces several related new issues. If multiple new issues share a properties.$lib_version (or properties.$exception_releases when the SDK is configured to populate it), present them grouped — a rollback decision rests on the cluster, not any one issue.
• "Users" is the right severity proxy for user-facing apps. For backend services without a real distinct_id concept, fall back to sessions or occurrences.
• Don't auto-assign or auto-resolve as part of triage. Present the list and let the user decide. Bulk actions belong in dedicated skills.
• If the project uses Inbox (posthog:inbox-reports-list), check it first — PostHog may have already curated the most actionable issues so you avoid re-deriving them.
• Provide the issue URL (/error_tracking/<id>) for each row so the user can jump straight to the issue page if they want to drill down themselves.