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,
  "include": ["exception", "stacktrace", "environment", "navigation", "correlation"]
}

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 each row's _posthogUrl (returned on every issue row) so the user can jump

straight to the issue page if they want to drill down themselves. If you build the

link yourself, use the full /project/<project_id>/error_tracking/<id> path, never

a bare /error_tracking/<id>.