Alert rules
An alert rule says what counts as a problem. There are six kinds:
threshold, nodata, event, presence, rogue and unknown_device. You normally create
rules by describing what you want to Claude, which writes the rule, shows what
it would flag right now, and saves it only when asked. An organisation can have
up to 200 rules.
How do I create a rule?
Section titled “How do I create a rule?”Ask Claude, for example “alert me when a radio’s airtime stays above 80% for
15 minutes”. Claude uses these alerts.* functions:
| Function | What it does |
|---|---|
create_rule | Dry run by default: validates the rule and previews what it would flag now. apply: true saves it |
update_rule | Merges changes into a rule (a field set to null returns to its default). Dry run unless apply: true. The previous version is kept |
delete_rule | Deletes a rule and its current problems; its versions and history stay |
backtest | Replays a rule over stored history without saving anything (below) |
check_now | Evaluates one rule, or every enabled rule, immediately |
rules / get_rule | Lists rules with their problem counts, last run and last error; versions: true adds a rule’s change history |
context | The context pack for a current problem: where it is, what it hangs off, related problems, recent events and changes, its metrics against a usual week, and how often it happened before |
postmortem | One alert episode written up for a review, with a printable page and a Markdown download |
quality | How well each rule’s alerts work over a period (default 30 days): noisy, ignored, slow to acknowledge, or fine, with suggested changes to backtest |
Saving, changing and deleting need the engineer role or above. Disabling a rule clears its current problems.
Which rule kind do I need?
Section titled “Which rule kind do I need?”| Kind | Raises a problem when | Required fields | One instance per |
|---|---|---|---|
threshold | A PromQL expression crosses warn and/or crit | expr, and crit or warn | Series the expression returns |
nodata | A reporter has sent nothing for longer than maxAge | family, maxAge | Silent reporter |
event | A controller alarm (or event) matches | match | Device and code |
presence | A registered device is not seen on the network | select | Device |
rogue | An access point that isn’t yours advertises a watched SSID | ssids and/or ssidsFrom | Rogue BSSID |
unknown_device | A Wi-Fi or wired client that is neither a registered device nor allowed by the rule is on the network | select, ssids, ssidsFrom or vlans (at least one) | Client MAC |
Threshold
Section titled “Threshold”expr is PromQL over the metrics catalogue (Claude reads it with
metrics.catalog()). op is one of > (default), >=, <, <=, ==,
!=. Give crit, warn or both.
- name: radio-airtime kind: threshold expr: avg_over_time(radio_airtime_percent[15m]) warn: 60 crit: 80Nodata
Section titled “Nodata”Every reporter of family (ap, switch or cluster) that has been silent
for longer than maxAge (for example 20m). within limits it to a zone,
switch group or location. The family stream watches Northbound streaming
itself.
match selects log entries by kinds (alarm, event), codes,
severities (for example Critical, Major) and text. An alarm stays a
problem until SmartZone clears it. An event goes back to OK after
clearAfter (default 30m) without a repeat.
Polling reads the controller’s outstanding alarms every 5 minutes, so alarm rules work without streaming. Controller events (as distinct from alarms) arrive only by Northbound streaming, which the hosted service cannot receive yet.
Presence
Section titled “Presence”select is an inventory selector for devices you have registered as ones that
must be present (for example { tags: { critical: 'yes' } }). A device that is
not seen as a wireless client, a wired client or an LLDP neighbour is a
problem. Ask Claude to register devices and tag them; that is
inventory.add_device and inventory.tag.
ssids lists SSIDs to watch (compared ignoring case), and/or ssidsFrom
selects inventory WLANs whose SSIDs are watched, for example
{ type: 'wlan', tags: { facility: 'yes' } }. A rogue must have been seen
within maxAge (default 30m); within limits it to rogues seen by APs in a
zone or location. The problem sits on the AP that saw it. A rogue marked known,
ignored or allow-listed on the controller is OK.
Polling reads rogues every 5 minutes. The zone must have rogue detection turned on in SmartZone.
Unknown device
Section titled “Unknown device”Where to look is select (a selector for the clients themselves; tags and
within reach them through their AP, switch port or switch), ssids /
ssidsFrom (as for rogue rules) and/or vlans; with both SSIDs and VLANs, a
client on either is in scope. allow lists what else counts as known besides
registered devices: macs (whole MACs or prefixes of at least 3 octets),
vendors (the MAC’s IEEE vendor), hostnames and os (the controller’s
fingerprint), with * and ? globs, ignoring case. The problem recovers when
the device leaves or is registered with inventory.add_device. Approving
devices and the allow list in full: Unknown-device detection.
What fields does every rule take?
Section titled “What fields does every rule take?”| Field | Default | Meaning |
|---|---|---|
name | required | Lower-case letters, digits, _ . -, up to 63 characters |
description | none | Shown on the Alerts page and in notifications |
runbook | none | What the person paged should do: short steps or a link, up to 4,000 characters. Sent with every notification of the rule and shown on the Alerts page |
enabled | true | |
state | CRITICAL | The state an event, presence, nodata, rogue or unknown-device problem raises (WARNING or CRITICAL) |
maxCheckAttempts | 3; 1 for event, rogue and unknown-device rules | Consecutive failing reports before the problem is HARD and notified (1–20) |
every | 1m | How often the rule is evaluated |
renotify | none (notify once) | Repeat an unacknowledged HARD problem this often, e.g. 4h |
flapDetection | true | Pause notifications while an instance flaps |
dependencies | true | Suppress a problem whose upstream (the AP’s switch port or switch) is down |
dependencyWait | 5m | How long a new problem with an upstream waits before notifying |
notify | true | false records problems without notifying |
labels | none | Free-form, e.g. { team: facilities }; carried on notifications and used by escalations |
Durations are written like 30s, 5m, 1h, 7d. See
How alerts work for what SOFT, HARD, flapping and
dependencies mean.
How do I test a rule before saving it?
Section titled “How do I test a rule before saving it?”Backtest it. alerts.backtest replays a rule (a saved one by name, or a
definition) over stored history and reports how many instances would have had
problems, the episodes, the notifications that would have gone out, flapping
starts, and the longest problems. The default window is 24 hours (up to 30
days); past 48 hours it runs on hourly rollups. Threshold rules replay over the
metrics, one check per step (by default 5 minutes, or the window divided into
500 steps when that is longer); event rules replay over the stored log.
Ask: “Backtest a rule that fires when port CRC errors exceed 50 in 15 minutes over the last week, and tell me how noisy it would have been.”
What is in the starter pack?
Section titled “What is in the starter pack?”37 rules for SmartZone, each labelled pack: starter. Install them from
step 5 of the setup checklist, from
Starter checks on the Alerts page’s Rules tab (Preview, then Add N checks),
or by asking Claude (alerts.starter_pack). Installing adds only the rules you
don’t have and never changes one that exists, so rules you have tuned survive a
re-install and new checks arrive when you run it again.
| Area | Rule | Fires on |
|---|---|---|
| Controller | controller-cluster-down | The cluster is not In_Service |
controller-node-down | A controller node is not In_Service | |
controller-cpu-high | Node CPU over 80% (warn) / 95% (crit) | |
controller-memory-high | Node memory over 85% / 95% | |
controller-disk-high | Node disk over 80% / 90% | |
controller-silent | No controller report for 30 minutes | |
stream-silent | Northbound streaming silent for 10 minutes | |
sz-alarm-critical | A Critical SmartZone alarm (CRITICAL until SmartZone clears it) | |
sz-alarm-major | A Major SmartZone alarm (WARNING) | |
certificate-expiring | A certificate the controller uses expires within 30 days / 7 days | |
license-expiring | A licence expires within 60 days / 14 days | |
license-capacity | A licence pool 90% / 100% used | |
license-full-forecast | A growing licence pool is forecast full within 60 / 21 days, at the last 14 days’ trend | |
| Wi-Fi | ap-offline | An AP is not online (repeats every 4 h) |
ap-flapping | An AP went offline and back 4 / 8 times in an hour | |
ap-cpu-high | AP CPU over 80% / 95% for 15 minutes | |
ap-memory-high | AP memory over 85% / 95% for 15 minutes | |
radio-airtime-high | Channel airtime over 70% / 85% for 15 minutes | |
radio-noise-high | Noise floor above −85 / −75 dBm for 15 minutes | |
clients-below-usual | A zone’s clients below 50% / 25% of the same time last week | |
wifi-connection-failures | 30% / 60% of a radio’s client connection attempts fail over 15 minutes (radios with at least 10 attempts) | |
rogue-facility-ssid | A rogue advertising a facility SSID (CRITICAL) | |
rogue-own-ssid | A rogue advertising any of your SSIDs (WARNING) | |
| Security | unknown-device-facility-ssid | An unregistered device on a WLAN tagged facility: yes (WARNING) |
unknown-device-facility-port | An unregistered device on a switch port, switch or switch group tagged facility: yes (WARNING) | |
| Reachability | probe-loss | An AP loses 2 or more of its 5 pings to a synthetic check target (WARNING) |
probe-target-down | No AP reaches a synthetic check target (CRITICAL) | |
| Switching | switch-offline | A switch is not online (repeats every 4 h) |
switch-cpu-high | Switch CPU over 80% / 95% for 15 minutes | |
switch-memory-high | Switch memory over 85% / 95% for 15 minutes | |
switch-poe-budget | PoE drawn over 80% / 95% of the budget | |
switch-poe-full-forecast | A switch’s daily peak PoE draw is forecast to reach 95% of its budget within 30 / 7 days | |
switch-psu-failed | A power supply on any stack unit is not OK (CRITICAL, repeats every 4 h) | |
switch-fan-failed | A fan on any stack unit is not OK (CRITICAL, repeats every 4 h) | |
switch-temperature-high | The switch’s hottest sensor over 75 / 85 °C for 15 minutes | |
port-crc-errors | 10 / 100 CRC errors on a port in 15 minutes | |
port-flapping | A port went down and up 4 / 10 times in an hour |
Some of these stay quiet on the hosted service by design:
ap-cpu-high,ap-memory-high,switch-cpu-high,switch-memory-highandwifi-connection-failuresuse metrics only Northbound streaming delivers, so they have nothing to evaluate while polling is the data source. (switch-psu-failed,switch-fan-failedandswitch-temperature-highdo work: polling reads switch power supplies, fans and temperatures every 15 minutes.)stream-silentwatches the stream, which is not in use.rogue-facility-ssidwatches WLANs taggedfacility: yes, so it is quiet until you tag one. Ask Claude: “Tag the BMS-Sensors WLAN as a facility SSID.” The twounknown-device-facility-*rules are quiet in the same way until a WLAN, or a port, switch or switch group, is tagged.probe-lossandprobe-target-downare quiet until there is a synthetic check target: ask Claude to set one up (metrics.set_probe).license-full-forecastandswitch-poe-full-forecastfit a line through the last 14 days of daily peaks, and fire only while usage is rising and there is room left.clients-below-usualskips zones that usually have under 20 clients, and a zone has no baseline until it has a week of data. A holiday reads as a drop: acknowledge it or schedule downtime.
Can I keep rules in git?
Section titled “Can I keep rules in git?”Yes: export them as YAML, edit, and import the file back. The export writes each rule in its shortest form (fields at their default are left out) with a fixed field order and rules sorted by name, so a diff shows only what someone changed.
- Export: Export rules (YAML) at the top of the Alerts page, or
Download YAML on its Rules as code card (any member),
or ask Claude (
alerts.export_rules). - Import: paste the document into Rules as code on the Alerts page’s Rules tab and
click Preview changes, then Apply (engineer or above). Claude’s
alerts.import_rulesworks the same way, as a dry run untilapply: true.
The document looks like this (a bare list of rules also works):
version: 1rules: - name: ap-offline kind: threshold expr: ap_up op: "<" crit: 1Import creates rules that are new and updates ones that differ. Tick Delete
rules the document doesn’t list (Claude: prune: true) to also delete rules
missing from the file. Every rule is validated before anything changes: one
invalid rule rejects the whole import, with the rule’s position, name and the
problem. The document may give version (only 1 is accepted), must be at
most 1 MB, and may only have the top-level keys version and rules.