Bundle Settings configuration

Bundle Settings control how Unit Oncall groups related alerts into a single Bundle within a Schedule. Each Bundle Settings entry applies to one tag set: incoming alerts that match the tag set are merged into the same Bundle while the bundling window is open, instead of producing separate notifications.

A Bundle Settings entry belongs to a Schedule, so create the Team and Schedule first. Multiple entries can coexist within a Schedule as long as each one targets a different tag set.

Alerts that match no entry are not left unbundled. Every Schedule has a default bundle — the last-resort receiver for alerts whose tags match none of the entries below, including alerts with no tags at all. It is not a Bundle Settings entry and is not created or deleted here: its parameters live in the Schedule's own configuration, under default_bundle. See Schedule.

Fields

Validation rules

• name is required and is rejected when empty or longer than 100 characters.
• tags must contain at least one tag and at most ten. Duplicate tags within the same entry are rejected.
• Each tag must consist only of letters (A-Z, a-z), digits, and the symbols - _ . : /, and be at most 200 characters. Non-ASCII text, spaces, and other symbols are rejected — see Tags and labels for why. Because tags here is a matching value, this also means an alert carrying an unsupported tag can never be matched by a Bundle Settings entry: it is not grouped into a configured Bundle.
• A Schedule cannot contain two Bundle Settings entries that share the same tag set. Trying to save a duplicate tag set returns an error. This holds regardless of enabled: a disabled entry still occupies its tag set, so you cannot add a second entry for the same tags by disabling the first one. Edit the existing entry instead, or delete it.
• All numeric fields are rejected when they fall outside the ranges in the table above.
• description is limited to 500 characters.

How bundling works

Bundling groups alerts whose tag sets are exactly equal. An entry applies to an alert only when the alert's tag set and the entry's tags are the same set — not when one merely contains the other. Order does not matter, but an extra tag does: an alert tagged db + host:web-03 is not grouped by an entry whose tags are ["db"].

An alert that matches no entry does not get a Bundle of its own. It goes into the Schedule's Default Bundle, together with every other alert on that Schedule that matched no entry — including alerts carrying no tags at all. See The Default Bundle below for why that matters. Keep varying values (host:, instance:, pod:, request IDs, timestamps) out of your tags, or your alerts stop matching their entries and end up there. See Tags and labels for what belongs in a tag, and Transformation Rule for how to control which tags an alert carries.

1. An alert arrives at the Schedule (via a Webhook and any routing rules).
2. Unit Oncall looks for an active Bundle whose tag set matches the alert and whose bundling window is still open.
3. If a match is found, the alert is added to that Bundle and no new notification is sent — with two exceptions: the first alert that raises the Bundle to critical pages you even if the Bundle was already open at a lower severity, and every max_alerts_per_bundle alerts the Bundle notifies you again (see Re-notification below).
4. If no Bundle is open, a new one is created and it notifies. The bundling window is rolling: it stays open for window_seconds after the most recent alert, so a steady stream of alerts keeps extending it (up to a hard cap of 24 hours from creation).
5. When an info alert arrives for a Bundle and auto_resolve_on_info is on, the Bundle is closed.
6. When a Bundle has been open longer than auto_expire_hours without being closed, it is auto-expired.
7. After a Bundle closes, the cooldown fields determine how soon a new Bundle for the same tag set can open.

Re-notification

Bundling exists to stop a storm of calls, but silence has a limit. max_alerts_per_bundle sets how many alerts pile up before an open Bundle notifies you again. Once that many have arrived since the Bundle last notified you, the same Bundle notifies once more: a call when the Bundle's highest severity so far is critical, a push otherwise. The counter then restarts, so the next re-notification comes after that many again.

Three things to know about the count:

• It counts distinct alert fingerprints, not raw alerts. The fingerprint is the identity your monitoring tool gives an alert (see Generic Webhook). Repeats of a fingerprint already in the Bundle do not move the count, so one flapping alert never re-notifies you on its own.
• The Bundle is never split. The count is a re-notification threshold, not a capacity limit: the Bundle keeps growing, and one incident stays one Bundle.
• Suppression still wins. A maintenance window, a cooldown, or a _notify:none tag suppresses the re-notification exactly as it suppresses the first one.

The default of 1000 means an open Bundle effectively never notifies twice for volume alone — only severity escalation does. Lower it when a growing Bundle should page you again: 50 calls you back every 50 distinct alerts. 1 means every new fingerprint notifies, which turns bundling into per-alert notification without splitting the Bundle.

The Default Bundle

Every Schedule has one Default Bundle. An alert lands in it whenever it matches no Bundle Settings entry — because it carries no tags, or because its tag set is not exactly equal to any entry's tags. There is no per-alert Bundle: unmatched alerts are not kept apart, they are merged with each other.

That merge is what makes stray tags dangerous, and the risk runs opposite to what you might expect. The problem is not that you get too many Bundles and too much noise. It is that unrelated incidents end up in the same Bundle and stop notifying you. Once the Default Bundle is open, the rules in step 3 above apply to it as well: further alerts joining it raise no new notification unless one of them escalates the Bundle to critical, or the Bundle crosses its max_alerts_per_bundle threshold. A warning from a completely different service, arriving while the Default Bundle is open, is recorded but does not page anyone until one of those two happens. And because the window is rolling, a Schedule with steady traffic can keep its Default Bundle open more or less continuously.

So a tag whose value changes per alert — host:web-03, instance:i-0ab12, a request ID — does not merely fail to group your alerts. It pushes them out of the entry you wrote for them and into the shared Default Bundle, where they can be silently absorbed. Use tags for the stable dimensions you group on, and let the per-alert detail stay in the payload.

Disabling an entry

Set enabled to false to switch an entry off without deleting it — useful while you are trying out a grouping, or to stop it temporarily.

A disabled entry is treated as if it did not exist. Alerts that match its tag set are bundled using the Schedule's default bundle, and every field of the disabled entry is ignored — including auto_expire_hours, so the fallback also decides when an unclosed Bundle is auto-expired. The entry keeps its tag set reserved within the Schedule, so re-enabling it restores the previous behaviour and no second entry can claim those tags meanwhile.

Examples

The configuration document is the bundle settings: the fields below sit at the top level, with no spec wrapper around them. This is what you author in Edit mode and what History mode stores and diffs.

(On the wire, the config endpoint carries that document inside a spec envelope — {"spec": { …the fields below… }, "change_summary": "…"} — and the console adds and removes the envelope for you. The envelope is not part of the document you edit.)

A simple grouping for database alerts:

{
  "name": "Database alerts",
  "description": "Group DB alerts that share the db tag",
  "tags": ["db"],
  "enabled": true,
  "window_seconds": 30,
  "max_alerts_per_bundle": 1000,
  "auto_resolve_on_info": true,
  "auto_expire_hours": 24,
  "cooldown_after_resolve_minutes": 0,
  "cooldown_after_dismiss_minutes": 5
}

A wider window that calls back every 200 alerts, with a longer cooldown:

{
  "name": "Region us-east bundle",
  "description": "Bundle all us-east alerts; keep the window open for 2 minutes",
  "tags": ["region:us-east", "env:prod"],
  "enabled": true,
  "window_seconds": 120,
  "max_alerts_per_bundle": 200,
  "auto_resolve_on_info": false,
  "auto_expire_hours": 6,
  "cooldown_after_resolve_minutes": 10,
  "cooldown_after_dismiss_minutes": 15
}

Related

• Schedule — Bundle Settings belong to a Schedule and inherit its rotation and escalation.
• Tags and labels — the values you put in tags are managed in the tag master.
• Maintenance window — use this to suppress notifications during planned work, instead of widening the bundling window.