Concepts · Alert rules

Alert rules

An alert rule decides which Issues open Incidents — and therefore which events page the on-call engineer. Rules attach to an app and evaluate every event Nightlamp ingests for that app.

How a rule fires

Each ingested event is normalized and fingerprinted into an Issue. Every active alert rule for the event's app is evaluated against the new event; if any rule matches, an Incident opens (or an existing one is updated) and the notification fan-out runs.

Rules respect a cooldown — once a rule fires for an Issue, it won't fire again for that same Issue within the cooldown window (default 5 minutes). This is the difference between "alert me once when this starts" and "alert me on every single event".


Condition types

  • new_issue — fires the first time a fingerprint is seen. Good default for "I want to know about every new failure mode".
  • threshold — fires when an Issue's event count crosses a configurable threshold within a rolling window. Tune to your traffic; a payments service might want 5 events / 60 s, a low-volume admin tool 1 event / 60 s.
  • regression — fires the first time a previously resolved Issue produces events again. Resolving is durable, so the Issue stays resolved and out of your queue: this alert, fired once per resolve, is how you hear that it came back. Catches "we shipped a fix and it broke again" without spamming you on the initial outage.

Filtering

Rules can scope to a specific environment (e.g. production) and a minimum level (e.g. error and above). This keeps dev-environment noise out of the on-call queue without a separate rule per env.


Where alerts go

An alert rule decides whether to alert. It may also select webhook destinations and an escalation policy. Organization email always fires, and recipients resolve at the organization level, in this order:

  1. your org's notification_emails list, if it has any entries;
  2. otherwise your org's contact_email;
  3. otherwise the sign-in email of the organization's owner;
  4. otherwise nobody — the notification is dropped.

That third case is silent by design: nothing errors, and the event still becomes an Issue. Nightlamp now says so out loud instead — an app with enabled rules and no recipients shows a warning on its detail page, and the Alert delivery panel there reports the recipient count and lets you send a test alert before you need one.

Email remains the default path, and it always fires. In addition, a monitor or an alert rule can select one or more webhook destinations and one reusable escalation policy. An escalation step fires only while the incident or issue is still open, so acknowledging, resolving, or ignoring it stops the ladder.

Destinations and policies are managed once per organization under Settings → Alert routing.

Bursts are collapsed rather than repeated: several alerts for one app in a short window arrive as a digest, and Issues correlated into a single incident cluster produce one notification instead of one per Issue.


Defaults we ship

Every new app is seeded with three rules: a new_issue rule at high severity and above (5-minute cooldown), a threshold rule at 10 events in 5 minutes (10-minute cooldown), and a regression rule (5-minute cooldown). That is enough for a smoke-test integration; tune from there in the alert rules editor on the app's detail page.

Deleted them all and want them back? The empty state offers a one-click restore, or POST /apps/{app_id}/alert-rules/defaults.

Configuring alerting from a script or an agent? Everything above is published machine-readably at GET /apps/{app_id}/capabilities under alerting — endpoints, the full rule vocabulary, the delivery model, and whether recipients are currently configured. See Programmatic setup.
Native uptime monitors come with their own implicit alerting — a confirmed-down probe opens an Incident regardless of alert rules. See Status reference for how monitor states map to incident states.