suppressing-noisy-errors

抑制噪声错误

从本质上说，抑制具有破坏性：匹配的事件会在写入时被丢弃，永远不会成为问题。错误的规则会悄无声息地丢弃真实的缺陷。这项技能旨在确保只对确实无法处理的模式应用抑制，并将筛选条件设得足够严格，以免误吞无关错误。

何时适合使用抑制

当错误符合以下情况时，适合使用抑制：

• 无法通过你的代码处理 — 浏览器扩展、第三方脚本、广告拦截器、导航后触发的网络信标。你无法修复它，因为这不是你编写的代码。
• 浏览器引擎的特性问题 — ResizeObserver loop limit exceeded、Script error.、Non-Error promise rejection captured 且负载为空。
• 机器人或爬虫流量 — 错误仅在无头浏览器或使用已知爬虫 user agent 的情况下触发。
• 采样已足够 — 对于量大但真实的错误，使用 sampling_rate 降低采样率，而不是完全抑制，这样既能保留可见性，又不必承担全部成本。

以下情况不适合使用抑制：

• 错误 目前 无法处理，但修复后可能可以处理 — 使用问题状态 archived 或 resolved，这样如果错误再次出现，就会重新显现。
• 你只是想静音通知 — 将问题分配给用户、更改其状态，或使用通知规则。
• 错误是另一个错误的重复项 — 合并，或创建分组规则（grouping-noisy-errors）。

可用工具

工具	用途
posthog:query-error-tracking-issues-list	按数量和影响查找抑制候选项；通过 filterGroup 对候选筛选条件进行试运行
posthog:query-error-tracking-issue-events	检查采样后的 $exception 事件，确认模式
posthog:execute-sql	对需要 OR 分组或 filterGroup 允许列表之外运算符的筛选条件进行试运行的备用工具
posthog:error-tracking-suppression-rules-list	检查现有的抑制规则
posthog:error-tracking-suppression-rules-create	创建抑制规则
posthog:error-tracking-issues-partial-update	通过问题状态隐藏过去的数据，而不在写入时丢弃事件

工作流

第 1 步 — 确定候选项

出现次数多、不同用户数少，是最明显的噪声信号——即一个用户（或一个机器人）产生了大量事件。

posthog:query-error-tracking-issues-list
{
  "status": "active",
  "orderBy": "occurrences",
  "orderDirection": "DESC",
  "dateRange": { "date_from": "-7d" },
  "limit": 30,
  "volumeResolution": 0
}

请留意：

• occurrences 高、users 比率低（例如，50,000 次出现、3 个用户 → 可能是机器人或扩展程序循环）
• 异常消息匹配已知噪声模式：ResizeObserver loop、Script error.、扩展程序命名空间（chrome-extension://、moz-extension://、safari-extension://）
• 堆栈跟踪主要来自用户无法控制的第三方域名

步骤 2 — 确认模式

对于每个候选项，提取一组 $exception 事件样本，并检查模式是否符合你要抑制的内容：

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

onlyAppFrames 默认为 true，但在调查噪声时，你通常会希望显示第三方堆栈帧——传入 onlyAppFrames: false，这样扩展程序 URL 和供应商域名就会出现在堆栈中。

请确认：

• 样本中的异常类型或消息文本一致
• URL / 用户代理 / 浏览器中没有混入真实用户流量
• 抑制此模式不会导致将来恰好具有相同类型的真实错误被隐藏

如果任何样本不符合预期，请缩小筛选条件，或跳过该候选项。

步骤 3 — 严格限定筛选范围

抑制规则的配置方式与分组规则使用相同的筛选器结构。error-tracking-suppression-rules-create 工具说明明确警告：不要创建匹配所有内容的规则，也不要创建过于宽泛的规则。请使用尽可能具体的属性组合进行匹配：

噪声模式	建议的筛选条件
Chrome 扩展程序错误	$exception_sources icontains "chrome-extension://"
Firefox 扩展程序错误	$exception_sources icontains "moz-extension://"
Safari 扩展程序错误	$exception_sources icontains "safari-extension://"
ResizeObserver 循环	$exception_values icontains "ResizeObserver loop"（消息足够具体；类型筛选条件可选）
跨源 "Script error."	$exception_values icontains "Script error." AND $exception_types exact "Error"
机器人用户代理	单个词项使用 $raw_user_agent regex "(?i)bot"；如需在一条规则中匹配多个机器人 / 爬虫标记，请参阅下方的交替匹配模式
第三方网络信标失败	$exception_sources icontains "<vendor-domain>" AND 类型筛选条件（例如 $exception_types exact "TypeError"）

规范的异常属性（$exception_types、$exception_values、 $exception_sources、$exception_functions）在捕获时都是数组。 PostHog 的属性筛选器会对这些属性进行特殊处理——每个筛选器都会针对数组中的单个元素进行匹配，因此所有标准运算符（exact、 is_not、icontains、not_icontains、regex、not_regex）都可以直接使用值：exact "TypeError"，而不是 exact '["TypeError"]' 或 regex '"TypeError"'。

单数形式（$exception_type、$exception_message）和 $exception_stack_trace_raw 只会在不到百分之一的事件中出现；使用它们进行筛选会产生一条悄无声息地永不匹配的规则。

请注意，抑制规则和分组规则中的 regex 运算符会编译为 HogVM 的 Operation::Regex，它区分大小写。要进行不区分大小写的匹配，请使用内联标志 (?i)（例如 (?i)headlesschrome）。

要匹配多个机器人或爬虫词项，请使用竖线直接进行交替匹配。 调用 API 时，将其作为正则筛选器的 value 字段传入 （$raw_user_agent 比解析后的 $user_agent 更可靠，后者有些解析器会将其规范化，从而去除爬虫标记）：

(?i)(HeadlessChrome|bot|crawler|spider)

只要可能，就应使用 AND 将两个或更多条件组合起来——例如类型加消息，或消息加 URL 模式——使规则能够准确匹配真实噪声。

Step 4 — 决定：抑制还是采样

如果想保留部分可见性，请使用介于 0 和 1 之间的 sampling_rate：

• sampling_rate: 1 — 丢弃所有匹配项（完全抑制）
• sampling_rate: 0.95 — 丢弃 95% 的匹配事件，保留 5% 作为哨兵数据
• sampling_rate: 0.5 — 采样率减半，适用于高频但确实存在的错误

只要有任何疑虑，认为该模式不完全是噪声，就默认使用非 1.0 的采样率。等数据表明此规则没有捕获真实问题后，再将其收紧到 1.0。

Step 5 — 对实时数据试运行过滤器

请求确认前，先对问题列表运行候选过滤器，以便你和用户准确查看该规则在过去 7 天内会捕获哪些问题。query-error-tracking-issues-list 的 filterGroup 参数接受与抑制规则相同的属性过滤器结构，因此对于典型的仅包含 AND 的规则，可以直接传入规则的叶级过滤器，无需转换为 HogQL：

posthog:query-error-tracking-issues-list
{
  "filterGroup": [
    { "type": "event", "key": "$exception_types", "operator": "exact", "value": "Error" },
    { "type": "event", "key": "$exception_values", "operator": "icontains", "value": "ResizeObserver loop" }
  ],
  "dateRange": { "date_from": "-7d" },
  "status": "all",
  "filterTestAccounts": false,
  "orderBy": "occurrences",
  "limit": 25
}

抑制预览中需要覆盖的重要默认值：

• status: "all" — 抑制会应用于所有问题状态，因此不要让默认的 active 过滤器隐藏已归档的噪声。
• filterTestAccounts: false — 规则在数据摄取时不会遵循测试账户开关。预览应与生产环境的实际情况一致。

每行代表规则会捕获的一个问题：name（异常类型）、description（示例消息）、source、library，以及 aggregations.occurrences 和 aggregations.users。问题列表就是按问题细分的结果——请逐行查看。

最重要的安全检查：扫描结果，查看是否有任何问题的 name / description / source 看起来像是团队会想要修复的真实错误，而非噪声。基于消息文本看似严格的过滤器，常常会匹配到碰巧包含相同短语的无关问题；规则启用后，这种失误会悄无声息地摧毁真实数据。如果发现任何可疑内容，请收紧过滤器（第 3 步），然后重新运行此步骤，直到列表中只剩下真正的噪声模式。

将各行的 aggregations.occurrences 和 aggregations.users 相加，得到第 6 步要告知用户的影响范围总量。如果需要获取超过 limit 个问题的精确总量，请使用 offset 分页，或使用本步骤末尾的 HogQL 聚合查询。

如需查看一两个带完整堆栈跟踪的具体事件示例，请对最可疑的问题调用 query-error-tracking-issue-events：

posthog:query-error-tracking-issue-events
{
  "issueId": "<id from the list>",
  "limit": 3,
  "include": ["exception", "stacktrace", "environment", "navigation"],
  "onlyAppFrames": false
}

必须回退到 execute-sql 的情况

filterGroup 仅支持扁平 AND。以下情况请改用 HogQL：

• 规则在外层分组或任何嵌套分组中使用 type: "OR"。
• 规则使用 filterGroup 不支持的运算符（例如 between、in、semver_*）。
• 你需要精确的事件级计数，而非按问题聚合的计数。

HogQL 的结构与抑制规则字节码编译后的结构一致。物化属性列可为空，因此必须使用 coalesce(..., '[]') 包装；否则 ClickHouse 会以“Nested type Array(String) cannot be inside Nullable type”拒绝查询：

SELECT
  count() AS matched,
  count(DISTINCT distinct_id) AS users,
  count(DISTINCT properties.$exception_issue_id) AS issues
FROM events
WHERE event = '$exception'
  AND timestamp > now() - INTERVAL 7 DAY
  AND arrayExists(
    v -> ifNull(ilike(v, '<pattern>'), 0),
    JSONExtract(coalesce(properties.$exception_values, '[]'), 'Array(String)')
  )

icontains 使用 ilike，exact 使用普通相等运算符，regex 使用 match(v, '<pattern>')。规则中的 regex 区分大小写——如有需要，请内联添加 (?i)。

Step 6 — 创建前征求用户确认

尽管 API 将抑制标记为 destructive: false，但它本质上具有破坏性。创建前向用户展示：

1. 计划发送的确切过滤器
2. 第 5 步的问题列表及其 occurrences 和 users，以及汇总总量——指出任何看起来像真实错误的条目
3. 是否与任何现有抑制规则重叠（先调用 posthog:error-tracking-suppression-rules-list）

等待用户明确确认。然后创建：

posthog:error-tracking-suppression-rules-create
{
  "filters": {
    "type": "AND",
    "values": [
      {
        "type": "event",
        "key": "$exception_types",
        "operator": "exact",
        "value": "Error"
      },
      {
        "type": "event",
        "key": "$exception_values",
        "operator": "icontains",
        "value": "ResizeObserver loop"
      }
    ]
  },
  "sampling_rate": 0.95
}

先从 0.95 开始（丢弃 95%，保留 5% 作为哨兵数据），以便在收紧到 1.0 前确认该规则没有捕获真实错误。

步骤 7 — 观察规则 24–48 小时

创建规则后：

• 对一个较短的时间窗口运行相同的筛选条件，确认匹配的事件不再被捕获。该时间窗口必须限定在规则创建之后（例如，过一小时后使用 WHERE timestamp > now() - INTERVAL 1 HOUR）。 不要重新运行步骤 5 中的 7 天估算 — 抑制仅适用于新事件，因此窗口中的历史事件仍会保留，计数不会下降。
• 观察规则创建后时间窗口内相关活跃问题的变化 — 如果它们的数量下降，而无关问题保持稳定，说明规则的范围设置正确。
• 如果某个相关的真实问题数量也下降（误报），请立即让用户通过 Project settings → Error tracking → Suppression rules 停用规则，并在重新创建规则前收紧筛选条件。用于编辑或删除规则的 MCP 工具（error-tracking-suppression-rules-partial-update、-destroy）尚未启用 — Agent 无法通过编程方式恢复。

如果发现误报迹象（某个真实问题恰好在规则创建时不再出现），优先停用规则，而不是删除它 — 这样可以保留规则配置，供后续取证审查。

提示

• Project settings → Error tracking → Suppression rules 会显示相同的数据；用户询问规则在 UI 中的位置时，请告知他们。
• 抑制作用于数据摄取阶段。过去事件产生的现有问题会保留其数据；只有新事件会被丢弃。
• 如果只需更改状态（不丢弃数据，只将其从活跃列表中隐藏），优先使用带有 status: "suppressed" 的 error-tracking-issues-partial-update，而不是创建抑制规则。
• 架构明确警告模型不要创建匹配所有内容的规则。如果用户要求“抑制来自扩展的所有内容”，仍应按堆栈跟踪或 URL 限定范围 — 绝不要将 filters 留空。
• 范围过窄的抑制规则无伤大雅（仍会漏过一些噪声）。范围过宽的规则会悄无声息地销毁真实数据 — 应倾向于设置较窄的范围。

相关技能

• grouping-noisy-errors — 当事件仍包含有效信息时，合并或重新分组，而不是丢弃
• triaging-error-issues — 噪声被屏蔽后，对剩余问题排序