Synthetic reachability checks
A synthetic check has chosen APs ping an IP address you name (a gateway, a badge server, a building-management head end) every few minutes, and stores each result as metrics. That turns “can Hall B still reach the BMS?” into something you can alert on, chart on a board and report availability for.
Synthetic checks are set up only through Claude: there is no dashboard form for them. They run on their own schedule, whether or not API polling is on.
How do I set one up?
Section titled “How do I set one up?”Ask Claude, for example “Ping the core gateway 10.0.0.1 from two APs in each hall every 5 minutes.” Claude uses these functions:
| Function | What it does | Role |
|---|---|---|
metrics.probes() | Every target with its settings, next and last run, last error and the last result per AP | Any |
metrics.set_probe() | Add a target, or change one with the same name | Engineer or above |
metrics.remove_probe() | Remove a target. Its probe entities leave the inventory; their metrics stay until retention drops them | Engineer or above |
metrics.run_probes() | Run one target now, from at most 4 of its APs, and return the results | Operator or above |
A role that is too low gets write_blocked. The first scheduled run is at the
next 5-minute tick.
What does a target take?
Section titled “What does a target take?”| Field | Default | Meaning |
|---|---|---|
name | required | Lower-case letters, digits, ., _ or -, starting with a letter or digit, up to 40 characters, e.g. core-gw |
targetIp | required | An IPv4 or IPv6 address |
aps | none | AP MACs to ping from |
within / tags | none | Or: choose APs under a zone, AP group or location, and/or with these tags |
maxAps | 2, or the number of aps given | How many APs ping it, 1 to 5 |
intervalMinutes | 5 | 5, 10, 15, 30 or 60 |
description | none | Up to 200 characters |
enabled | true |
The target must be an IP address: SmartZone’s AP ping takes nothing else,
so a host name is refused with “targetIp must be an IP address: SmartZone pings
nothing else (a hostname is a 500).” Give aps, within or tags, or the
target is refused with “Say which APs ping it: aps (MACs), within (a zone, AP
group or location id) or tags.”
With within or tags, the target uses the first maxAps matching APs by
name. Pick APs on the paths you care about, such as one per closet or hall.
What limits apply?
Section titled “What limits apply?”| Limit | Value | At the limit |
|---|---|---|
| Targets per organisation | 10 | ”At most 10 targets per organisation; remove one first.” |
| Pings per round per organisation | 20, the enabled targets’ maxAps added up | ”At most 20 pings per round per organisation (the targets’ maxAps add up to N); each takes the AP 7–15 s.” |
| APs per target | 5 | Refused by the call’s argument check: maxAps is a whole number from 1 to 5 |
Each AP sends 5 pings to the target itself (SmartZone’s GET /tool/ping),
which takes about 7 seconds, or about 15 when nothing answers.
What happens when an AP is offline?
Section titled “What happens when an AP is offline?”It is skipped, not counted as a failure. An AP that isn’t Online, or that
gives no answer at all, records skipped and writes no sample, so an offline AP
never makes the target look down. The AP set stays the same: a skipped AP is not
swapped for another, so each series keeps meaning one path. In alerts, an
AP that is down makes its probes unreachable rather than failing, because the
AP is their upstream.
Each AP’s result is one of up (at least one reply), down (no reply),
skipped or error (the controller refused). A target whose selector matches no
AP reports “no_aps: the selector matched no AP (inventory.sync() first?)”. If
the controller refuses the saved login, the target pauses until the controller
credentials are updated.
What metrics does a check produce?
Section titled “What metrics does a check produce?”Three metrics per target and AP, on a probe entity
probe:<target>@<AP MAC> that sits under its AP and carries the labels target
and target_ip:
| Metric | Meaning |
|---|---|
probe_up | 1 when the target answered at least one of the 5 pings from the AP |
probe_loss_ratio | Share of the 5 pings lost, 0 to 1 |
probe_rtt_ms | Average round trip of the pings that came back (absent when none did) |
They are in the probe family, so /metrics?family=probe scrapes only them,
and they work in PromQL like any other metric:
probe_rtt_ms{target="core-gw"}Which starter rules watch them?
Section titled “Which starter rules watch them?”Two starter rules watch every target, and are quiet until there is one.
| Rule | Fires on |
|---|---|
probe-loss | An AP loses 2 or more of its 5 pings (40% or more) to a target: WARNING, after 2 checks |
probe-target-down | Every ping from every AP that ran was lost: the target, or the network in front of it, is down. CRITICAL, after 2 checks |
probe-loss is per AP; probe-target-down says it once per target.
Can I report on availability?
Section titled “Can I report on availability?”Yes. On the Reports page, choose Synthetic checks (AP → target)
under Devices in the Availability report: it shows how much of the
period each AP-to-target path was up, from probe_up. Periods when an AP was
skipped count as not reported, not as down. Claude gives the same report with
metrics.availability({ type: 'probe' }).