triaging-error-issues

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

当用户询问“哪里出问题了”或需要每日错误审核时，目标是生成一份简短的、按优先级排序的值得人工关注的问题列表——而非所有活跃问题的堆砌。大多数项目都有数百个活跃问题，真正重要的通常是新出现的（过去24-48小时首次发现）、激增的，或影响大量独立用户的问题。

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

工具	用途
`posthog:query-error-tracking-issues-list`	列出并按聚合指标（发生次数、用户数、会话数）排序问题
`posthog:query-error-tracking-issue`	单个问题的精简详情（状态、经办人、顶级调用栈、版本）
`posthog:query-error-tracking-issue-events`	包含调用栈、URL、浏览器和 `$session_id` 的抽样 `$exception` 事件
`posthog:query-session-recordings-list`	查找遇到该问题的用户的会话回放
`posthog:inbox-reports-list`	如果项目使用Inbox，可获取预先整理的可操作信号

Workflow

工作流程

Step 1 — Pick a window and a signal

步骤1 — 选择时间范围和排序依据

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.

从用户的表述中读取时间范围。若未指定，默认规则如下：

“今日”/“今早”/“现在” →
```
dateRange: { date_from: "-24h" }
```
“本周”/“自周一以来” →
```
-7d
```
值班交接 →
```
-24h
```

定义“重要”的标准：

新问题 —
```
orderBy: "first_seen"
```
，
```
orderDirection: "DESC"
```
，时间范围较窄。用于捕获最近部署引入的回归问题。
高影响 —
```
orderBy: "users"
```
按受影响独立用户数排序。相比原始发生次数，更能体现严重程度（一个机器人循环会产生很多次发生，但仅影响一个用户）。
趋势性 — 对比短时间范围和较长基线的
```
orderBy: "occurrences"
```
，以发现激增情况。

Step 2 — Pull the candidate list

步骤2 — 获取候选问题列表

Start narrow and widen if too few issues come back:

json

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"

json

{
  "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

先从窄范围开始，若返回的问题太少再扩大范围：

json

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

将

volumeResolution

与时间范围匹配（

-24h

对应24个桶，

-14d

对应14个桶等），这样每行的迷你图有足够分辨率来显示激增状态与平稳状态的区别。单个桶只能提供总数，无法体现变化趋势。

若仅关注新问题，可并行运行以下查询：

json

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

如果项目同时使用浏览器和服务器SDK，按用户数排序的列表通常会被服务器端错误淹没（每次调用通常会生成新的

distinct_id

）。可使用

library

过滤器缩小范围——其值与SDK的

$lib

匹配，而非npm包名称，示例：

```
web
```
— posthog-js（浏览器端）

posthog-node

posthog-python

posthog-ruby

posthog-go

posthog-php

posthog-java

posthog-elixir

— 服务器端SDK

```
posthog-edge
```
— Cloudflare Workers / 边缘运行时

posthog-ios

posthog-android

posthog-react-native

posthog-flutter

— 移动端

Step 3 — Filter the noise

步骤3 — 过滤无效信息

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

列表中会包含已知的无效信息。在呈现之前，需剔除或标注：

时间范围内数量平稳的问题——它们不是新问题，用户已经知晓。仅当它们属于用户数排名靠前的问题时才呈现。
仅机器人触发的问题——如果所有事件都来自无头浏览器或爬虫用户代理，应标记为需要屏蔽（
```
suppressing-noisy-errors
```
）而非分类处理。

若不确定问题是新出现还是重复发生，可将

first_seen

与时间范围的起始时间对比：

```
first_seen
```
在时间范围内 → 新问题，值得关注
```
first_seen
```
在数周前但现在激增 → 回归问题，值得关注
```
first_seen
```
在数周前，数量平稳 → 背景无效信息

Step 4 — Add context for the top items

步骤4 — 为顶级问题添加上下文信息

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:

json

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.

对于排名前3-5的候选问题，获取一个抽样异常事件，以便摘要中包含调用栈和URL，而不仅仅是标题。使用

posthog:query-error-tracking-issue-events

而非原始SQL——它会返回标准化字段（

$exception_types

$exception_values

$current_url

, 浏览器/操作系统,

$session_id

），并且默认

onlyAppFrames: true

以剔除调用栈中的第三方无效信息：

json

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

如果用户想了解用户的操作行为，可转至

finding-replay-for-issue

来选择最佳关联会话回放。无需为每个分类处理的问题都获取回放——仅在用户要求深入挖掘时才进行。

Step 5 — Present the triage list

步骤5 — 呈现分类处理列表

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.

以一行标题开头（“过去24小时内有3个新问题，1个激增问题，5个高影响活跃问题”）。然后是按所选排序依据排序的简短表格：

问题	首次发现时间	用户数	会话数	抽样信息	建议行动
...	2小时前	142	198	`TypeError ... at checkout.js:42`	展开调查
...	数量激增	67	89	`Network request failed`	持续观察——可能为临时问题
...	3天前	12	12	`chrome-extension:// timeout`	屏蔽（扩展程序无效信息）

对于每个问题，建议以下行动之一：调查（

investigating-error-issue

）、分配（

error-tracking-issues-partial-update

）、屏蔽（

suppressing-noisy-errors

）、合并（

grouping-noisy-errors

），若已知问题已修复则建议解决。

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.

单次部署通常会暴露多个相关的新问题。如果多个新问题共享
```
properties.$lib_version
```
（或当SDK配置为填充该字段时的
```
properties.$exception_releases
```
），可将它们分组呈现——回滚决策取决于这类问题的整体情况，而非单个问题。
对于面向用户的应用，“用户数”是合适的严重程度指标。对于没有真实
```
distinct_id
```
概念的后端服务，可改用
```
sessions
```
或
```
occurrences
```
。
不要在分类处理过程中自动分配或自动解决问题。呈现列表后让用户自行决定。批量操作属于专门的功能模块。
如果项目使用Inbox（
```
posthog:inbox-reports-list
```
），应先查看它——PostHog可能已经整理出最具可操作性的问题，避免重复推导。
为每行提供问题URL（
```
/error_tracking/<id>
```
），以便用户在需要深入研究时直接跳转到问题页面。