Managing Noise

DebugBundle should surface actionable incidents, not turn every known operational pattern into permanent triage work. Noise management is the process of turning repeated, low-value incidents into scoped rules after you have confirmed the evidence.

Use this guide when you see paths, browser events, bots, third-party resources, or expected client errors repeatedly opening incidents.

Noise Management Loop

1. Inspect the incident bundle before suppressing anything.
2. Decide whether the signal is a real product issue, expected application behavior, or operational noise.
3. Use the narrowest control that matches the evidence.
4. Re-check the incident list after new traffic to make sure useful incidents still open.
5. Keep the rule auditable: name it clearly, scope it by service and environment, and add an expiry when the pattern may be temporary.

To remove a capture rule's expiry through the CLI, run debugbundle capture-rule update <rule-id> --project-id <project-id> --expires-at null. This sends an explicit JSON null. Omit --expires-at to preserve the existing expiry, or pass an ISO8601 timestamp to replace it.

Do not start by broadly dropping event types or all 4xx responses. A broad rule can hide real regressions that happen to share the same status code or generic browser message.

Which Control to Use

Start From an Incident

Use the incident as evidence for the rule.

debugbundle inspect <incident-id> --source cloud --json
debugbundle explain <incident-id> --source cloud --json
debugbundle bundle <incident-id> --source cloud --json
debugbundle capture-rule suggest <incident-id> --json

If a suggestion is safe, apply it from the suggestion instead of hand-writing a matcher:

debugbundle capture-rule create-from-suggestion <incident-id> \
  --suggestion-id <suggestion-id> \
  --name "Demote known analytics resource noise" \
  --expires-at 2026-07-20T00:00:00Z

Use demote when the event is useful context but should not open, reopen, alert, or dispatch automation. Use sample when you still want representative events. Use drop only when future matching events have no retained value.

Browser Resource Failures

Resource incidents identify the failed provider or asset, such as “Google Tag Manager script failed to load”. Concrete resource failures group across pages within the same project, service and environment. Affected routes remain context, with counts labeled as occurrence metadata or retained samples. Different assets and versions remain separate.

Separate hashed assets from one browser session and page can still arrive as a single page-load burst. DebugBundle keeps their incident identities separate for diagnosis, puts eligible email items into the same ten-second project digest, and applies a separate ten-second burst check to Slack, Discord, and alert-webhook delivery. Existing per-resource cooldowns remain in force. Fixed capture-time buckets and page origin, resource host and lifecycle scope keep later or unrelated failures separate.

A resource-load event does not prove why the request failed. “Possibly blocked by privacy tools” leaves room for network failures, CSP and provider outages; it does not diagnose Pi-hole or a particular extension.

Open Reduce noise on a resource incident to review Keep as context or Stop capturing. These controls are available for known providers, unknown dependencies and application resources. They match the exact resource host/path/type, service, environment and observed opacity. When the retained evidence cannot establish that scope, the control matches the incident's exact fingerprint together with the available service and environment restrictions. Review the displayed scope and confirm before creating a rule. Capture remains enabled by default.

Recognized services include Google tag / Google Analytics, Google Tag Manager, Microsoft Clarity, Hotjar, Cloudflare Web Analytics, Yandex Metrica, WordPress.com / Jetpack Stats, Meta Pixel, Microsoft Advertising UET, LinkedIn Insight, TikTok Pixel, Pinterest Tag, X Pixel, Segment, Mixpanel, Amplitude, PostHog and Plausible. Recognition covers their known script addresses, not every hosted or proxied variant. An unrecognized address still has the same explicit controls. A recognized dependency can affect application behavior; confirm its impact before changing capture. Google sign-in retains its authentication warning.

A first-party link preload can also offer context-only demotion when the captured page was hidden and incomplete; that rule requires exact visibility, ready state, target tag, and rel, so ordinary visible asset failures do not match it. Confirm that the preload interruption is understood before creating a rule. Existing matching rules are shown, including paused rules; creating from a suggestion does not replace or re-enable them. Sampling and rule editing remain available in project settings.

Resource bundles can also call out a failed recovery request, such as a signed-URL refresh returning 404 within 30 seconds in the same session or trace. DebugBundle presents that request as the most actionable captured signal while keeping the wording clear that it does not prove why the original resource load stopped.

Keeping events as context prevents new incidents, reopenings, alerts and automation from those matching events; context may still count toward paid usage. Dropping discards future matching events. Existing incidents and artifacts stay available, and owners/admins can pause or remove rules in project settings.

Manage Route Noise

Generic 404 traffic is common on public applications. Avoid promoting every 404 unless you really want all missing paths to open incidents.

Prefer a path-scoped client-error rule for routes where a 4xx is meaningful:

debugbundle capture-policy set \
  --project <project-id> \
  --client-error-path-rule '404=/checkout/*@GET,POST'

This promotes 404 responses under /checkout/* without opening incidents for scanner paths, old assets, or unrelated missing routes.

Teach Agents the Same Workflow

The generated .agents/skills/debugbundle/SKILL.md includes a Noise Management section. When an AI agent is investigating recurring low-value incidents, it should:

• Inspect bundle evidence first.
• Run debugbundle capture-rule suggest <incident-id> --json.
• Prefer project capture rules for operational noise.
• Keep browser suppression narrow with structured browser, bot, service, and environment evidence.
• Use client-error path rules for known route-scoped 4xx incidents.

Keep the generated skill current with:

debugbundle validate --fix --json

For MCP-based agents, the same workflow is available through suggest_capture_rules_from_incident, create_capture_rule_from_incident_suggestion, get_capture_policy, and update_capture_policy.

What Already Stays Non-Incident

Unpromoted 4xx responses, including generic 404 traffic, remain request telemetry or context when captured. They do not open normal request incidents solely because they repeat.

Common low-value external-probe GET/404 paths are also excluded from hosted improvement lists unless you explicitly promote them through project policy.

Related Docs

• Capture Policy — Presets, client-error incidents, and capture rules
• Agent Skill File — How generated skills teach agents to use DebugBundle
• MCP Tools — Agent-facing capture policy and capture-rule tools
• Browser SDK — Browser-specific noise and beforeSend guidance

Adjust delivery noise through API, CLI, or MCP

Set an email alert's config.aggregation_window_seconds to 1–300 seconds (default 10) to collect eligible incidents for the same project and recipient. The first pending digest sets the deadline; later items do not postpone delivery. If a digest contains more than 25 alert matches, the email shows up to 25 distinct incidents with critical incidents first, their matched alert conditions, and the full incident count. It links to the project's incident list when the application URL is configured. The remaining matched incidents stay available in DebugBundle.

For Slack, Discord, or an alert webhook, set config.cooldown_scope to "project" and choose cooldown_seconds to apply that rule's cooldown across distinct incidents. Environments and severity levels remain separate, so a higher-severity failure can still alert. The default "incident" scope preserves existing behavior. Signed lifecycle webhooks and GitHub automation keep their full event stream.

Pass the config object through CLI alert create/alert update --config-json, or MCP create_alert/update_alert. For example, an email config is {"to":"ops@example.com","aggregation_window_seconds":30}. A webhook config is {"target_url":"https://example.com/alerts","cooldown_scope":"project"}. The dashboard exposes these options in the shared create/edit form and preserves them during destination edits.

When a retained refresh, retry, or signed-URL request fails within 30 seconds of a resource error and shares its session or trace, the bundle highlights that more actionable failure. Later context-only 404s can refresh an existing bundle. This is correlated evidence, not proof that the later request caused the original resource interruption.

Capture-rule editing reuses the existing creation controls for action, sampling, enabled state and expiry. The matcher JSON editor exposes the complete definition, including multiple event types and browser lifecycle predicates. Unchanged expiry retains its exact timestamp; clear the expiry field to remove it.