triaging-error-issues

错误跟踪问题分流

当用户询问“出了什么问题？”或想查看每日错误时，目标是给出简短、按优先级排序的问题列表，指出哪些值得人工关注，而不是罗列所有活跃问题。大多数项目都有数百个活跃问题；真正重要的通常是新问题（首次出现于过去 24–48 小时内）、数量激增的问题，或影响了许多不同用户的问题。

可用工具

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

工作流

第 1 步 — 选择时间窗口和信号

根据用户的措辞确定时间窗口。未指定时使用以下默认值：

• “今天”／“今天上午”／“现在” → dateRange: { date_from: "-24h" }
• “本周”／“从周一以来” → -7d
• 值班交接 → -24h

确定“重要”的含义：

• 新问题 — orderBy: "first_seen"，orderDirection: "DESC"，并使用较短的时间窗口。 可捕捉近期部署引入的回归。
• 影响大 — orderBy: "users"，按受影响的不同用户数排序。比原始发生次数更适合衡量严重程度（一个机器人循环会产生许多次发生，但只涉及一个用户）。
• 趋势 — 在较短时间窗口内按 orderBy: "occurrences" 排序，并与较长的基线对比，以发现激增。

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

先使用较窄的范围，如果返回的问题太少，再扩大范围：

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 个桶，依此类推），这样每行的趋势线才有足够的分辨率来显示激增或平稳状态。只有一个桶时只能看到总量，看不到变化形态。

如果只查询新问题，则并行运行一个使用 orderBy: "first_seen" 的查询：

{
  "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 — 移动端

第 3 步 — 过滤噪声

列表中会包含已知噪声。展示前，应删除或明确指出以下问题：

• 在整个时间窗口内数量保持平稳的问题——它们不是新问题，用户已经习惯了。仅当它们按用户数排名靠前时才列出。
• 仅由机器人触发的问题——如果所有事件都来自无头浏览器或爬虫用户代理，应标记为抑制（suppressing-noisy-errors），而不是进行分流。

如果无法确定问题是新出现还是反复出现，请将 first_seen 与时间窗口的起点进行比较：

• first_seen 在时间窗口内 → 新问题，值得关注
• first_seen 是几周前，但现在数量激增 → 值得关注的回归
• first_seen 是几周前，且数量平稳 → 背景噪声

步骤 4 — 为优先级最高的条目补充上下文

对于排名前 3–5 的候选项，提取一个异常样例，让摘要包含堆栈帧和 URL，而不只是标题。使用 posthog:query-error-tracking-issue-events，不要使用原始 SQL——它会返回标准化字段（$exception_types、$exception_values、$current_url、浏览器／操作系统、$session_id），并默认设置 onlyAppFrames: true，以过滤堆栈中的第三方噪声：

posthog:query-error-tracking-issue-events
{
  "issueId": "<issue_id>",
  "limit": 1,
  "include": ["exception", "stacktrace", "environment", "navigation", "correlation"]
}

如果用户想了解用户当时在做什么，请交由 finding-replay-for-issue 来挑选最合适的关联录制。不要为每个已分诊的问题都获取回放——只获取用户要求深入了解的问题。

步骤 5 — 呈现分诊列表

先用一行标题概述（“过去 24 小时内有 3 个新问题、1 个突增问题、5 个活跃的高影响问题”）。然后提供一个按所选信号排序的简短表格：

问题	首次出现	用户数	会话数	示例消息	建议操作
...	2h ago	142	198	TypeError ... at checkout.js:42	调查
...	spike	67	89	Network request failed	观察 — 可能是暂时性问题
...	3d ago	12	12	chrome-extension:// timeout	抑制（扩展程序噪声）

对于每个问题，建议执行以下操作之一：调查（investigating-error-issue）、分配（error-tracking-issues-partial-update）、抑制（suppressing-noisy-errors）、合并（grouping-noisy-errors），或者如果已知问题已修复，则建议解决。

提示

• 单次部署通常会暴露出多个相关的新问题。如果多个新问题具有相同的 properties.$lib_version（或 SDK 配置为填充该字段时具有相同的 properties.$exception_releases），请将它们分组呈现——回滚决策应基于整个问题群，而不是单个问题。
• 对于面向用户的应用，“用户数”是衡量严重程度的恰当指标。对于没有真实 distinct_id 概念的后端服务，可改用 sessions 或 occurrences。
• 分诊时不要自动分配或自动解决问题。呈现列表并让用户决定。批量操作应通过专用技能执行。
• 如果项目使用 Inbox（posthog:inbox-reports-list），请先检查——PostHog 可能已筛选出最值得处理的问题，这样你就不必重新推导。
• 提供每一行的问题 _posthogUrl（每个问题行都会返回该字段），方便用户直接跳转到问题页面进一步查看。如果自行构建链接，请使用完整的 /project/<project_id>/error-tracking/<id> 路径，绝不要使用裸路径 /error-tracking/<id>。

相关技能

• investigating-error-issue — 对分诊列表中的单个问题进行深入调查
• grouping-noisy-errors — 分诊结果被重复问题或拆分过细的问题淹没时使用
• suppressing-noisy-errors — 静音已知噪声特征，令后续分诊结果更清晰
• authoring-error-tracking-alerts — 将值得采取行动的问题发送到 Slack 或 webhook，而不是手动重复分诊