suppressing-noisy-errors

What this skill does

# Suppressing noisy errors

Suppression is destructive in spirit: matching events are dropped at ingestion and
never become issues. The wrong rule silently throws away real bugs. This skill
exists to make sure suppression is applied only to patterns that are genuinely
unactionable, with filters narrow enough to avoid swallowing unrelated errors.

## When suppression is the right tool

Suppression is the right tool when an error is:

- **Unactionable from your code** — browser extensions, third-party scripts, ad
  blockers, network beacons firing after navigation. You can't fix it because you
  didn't write it.
- **Browser engine quirks** — `ResizeObserver loop limit exceeded`,
  `Script error.`, `Non-Error promise rejection captured` with empty payloads.
- **Bot or crawler traffic** — errors firing only from headless browsers or known
  crawler user agents.
- **Sampling already enough** — for high-volume but real errors, dampen with
  `sampling_rate` instead of full suppression so you keep visibility without
  paying full cost.

Suppression is **not** the right tool when:

- The error is unactionable _today_ but might become actionable after a fix —
  use issue status `archived` or `resolved` instead so it surfaces if it returns.
- You only want to mute notifications — assign the issue to a user, change its
  status, or use notification rules.
- The error is a duplicate of another — merge or create a grouping rule
  (`grouping-noisy-errors`).

## Available tools

| Tool                                              | Purpose                                                                                              |
| ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `posthog:query-error-tracking-issues-list`        | Find suppression candidates by volume and impact; dry-run a candidate filter via `filterGroup`       |
| `posthog:query-error-tracking-issue-events`       | Inspect sampled `$exception` events to confirm the pattern                                           |
| `posthog:execute-sql`                             | Fallback dry-run for filters that need OR groups or operators outside the `filterGroup` allowed list |
| `posthog:error-tracking-suppression-rules-list`   | Check existing suppression rules                                                                     |
| `posthog:error-tracking-suppression-rules-create` | Create the suppression rule                                                                          |
| `posthog:error-tracking-issues-partial-update`    | Hide past data via issue status without dropping events at ingestion                                 |

## Workflow

### Step 1 — Identify candidates

High occurrences with low distinct users is the strongest noise signal — one
user (or one bot) producing many events.

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

Look for:

- High `occurrences`, low `users` ratio (e.g., 50,000 occurrences, 3 users → likely
  bot or extension loop)
- Exception messages matching known noise patterns: `ResizeObserver loop`,
  `Script error.`, extension namespaces (`chrome-extension://`,
  `moz-extension://`, `safari-extension://`)
- Stack traces dominated by third-party domains the user doesn't control

### Step 2 — Confirm the pattern

For each candidate, pull a sample of `$exception` events and check that the
pattern matches what you intend to suppress:

```json
posthog:query-error-tracking-issue-events
{
  "issueId": "<candidate_issue_id>",
  "limit": 10,
  "verbosity": "stack"
}
```

`onlyAppFrames` defaults to `true`, but for noise investigation you usually
want the third-party frames visible — pass `onlyAppFrames: false` so extension
URLs and vendor domains show up in the stack.

Confirm:

- The exception type or message text is consistent across the sample
- The URLs / user agents / browsers don't include real user traffic mixed in with
  the noise
- Suppressing this pattern won't hide a future real bug that happens to share
  the type

If any sample doesn't match, narrow the filter or skip the candidate.

### Step 3 — Scope the filter tightly

Suppression rules are configured with the same filter shape as grouping rules.
The `error-tracking-suppression-rules-create` tool description warns explicitly:
do **not** create match-all rules and do **not** create overly broad rules.
Match on the most specific property combination you can:

| Noise pattern                       | Recommended filter                                                                                                                          |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| Chrome extension errors             | `$exception_sources icontains "chrome-extension://"`                                                                                        |
| Firefox extension errors            | `$exception_sources icontains "moz-extension://"`                                                                                           |
| Safari extension errors             | `$exception_sources icontains "safari-extension://"`                                                                                        |
| ResizeObserver loop                 | `$exception_values icontains "ResizeObserver loop"` (the message is specific; a type filter is optional)                                    |
| Cross-origin "Script error."        | `$exception_values icontains "Script error."` AND `$exception_types exact "Error"`                                                          |
| Bot user agents                     | `$raw_user_agent regex "(?i)bot"` for a single term; see the alternation pattern below for matching several bot/crawler markers in one rule |
| Third-party network beacon failures | `$exception_sources icontains "<vendor-domain>"` AND a type filter (e.g. `$exception_types exact "TypeError"`)                              |

The canonical exception properties (`$exception_types`, `$exception_values`,
`$exception_sources`, `$exception_functions`) are arrays at capture time. The
property filter compiler [special-cases them](https://github.com/PostHog/posthog/blob/master/posthog/hogql/property.py#L904) — it parses the
JSON-materialized column and wraps the filter in
`arrayExists(v -> ..., JSONExtract(...))`, so all the standard operators
(`exact`, `is_not`, `icontains`, `not_icontains`, `regex`, `not_regex`) work
against individual elements with the bare value: `exact "TypeError"`, not
`exact '["TypeError"]'` or `regex '"TypeError"'`.

The singular forms (`$exception_type`, `$exception_message`) and
`$exception_stack_trace_raw` are emitted on a fraction of a percent of events;
filtering on them produces a rule that silently never matches.

Note that the `regex` operator on suppression and grouping rules compiles to
the HogVM `Operation::Regex`, which is **case-sensitive**. Use the `(?i)`
inline flag for case-insensitive matching (e.g. `(?i)headlesschrome`).

For matching multiple bot or crawler terms, use bare pipes for alternation.
Pass this as the `value` field of the regex filter when calling the API
(`$raw_user_agent` is more reliable than the parsed `$user_agent`, which some
parsers normalize away from crawler markers):

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

Whenever possible, AND together two or more conditions — type plus message, or
message plus URL pattern — so the rule is specific to the real noise.

### Step 4 — Decide: suppress or sample

If you want to keep some visibility, use `sampling_rate` between 0 and 1:

- `sampling_rate: 1` — drop everything matching (full s