Skip to content
SZ-MCP
Get Support

Metrics and the scrape endpoint

SZ-MCP keeps time series per AP, radio, switch, port and controller node for your organisation. Claude queries them with PromQL (metrics.* in code mode), alert rules and boards are built on them, and your own tools can scrape the current values from GET https://sz-mcp.lanpulse.com/metrics in the Prometheus text format.

API polling. An admin turns it on with the API polling switch on the Metrics card under Configure › Data collection, or in step 3 of the setup checklist. SZ-MCP then reads the controller every 5 minutes; ports, controller statistics and switch health (power supplies, fans and temperatures) are read every 15 minutes. The same poll reads the controller’s outstanding alarms and rogue access points for alert rules. Once an hour it also reads licences, licence pools and the certificates the controller uses, for the expiry and capacity metrics.

If the controller is slow, polling backs off (the card shows slowed to every N min). If the controller refuses the saved login, polling pauses until the credentials are updated rather than retrying against SmartZone’s lockout. Engineers can click Poll now.

A few metrics — AP and switch CPU and memory, AP temperature, per-port byte counters, and some radio counters (including the client connection attempts and failures by stage, and AP-to-controller latency) — are only sent by SmartZone’s Northbound streaming, which the hosted service cannot receive yet. They have no data under polling. Switch temperature is polled.

TierResolutionKept
RawEvery report48 hours
Hourly rollups1 hour8 days
Daily rollups1 day (UTC)400 days

A query that reaches past a tier runs entirely on the next one. For longer or finer history, scrape the endpoint below into your own store.

With the metrics functions in code mode:

FunctionWhat it does
metrics.catalog()The 73 metrics, their units, sources and labels, and which keep a weekly baseline
metrics.query()A PromQL query, instant or over a range
metrics.baseline()An entity’s metrics now against their usual value for this hour of the week
metrics.availability()An availability (SLA) report from the up gauges, downtime counted as planned
metrics.forecast()When licences, PoE budgets, ports, AP clients or airtime fill up at the current trend
metrics.status()What has been collected and how fresh it is
metrics.poll()Poll now
metrics.set_polling()Turn polling on or off (admin)
metrics.probes(), set_probe(), remove_probe(), run_probes()Synthetic checks: chosen APs ping a target IP on a schedule, giving the probe_up, probe_loss_ratio and probe_rtt_ms metrics. Setting and removing targets needs engineer or above; running one now, operator or above

Series are labelled with the inventory’s names and containers, so you can ask for things like “clients per zone over the last day” or filter with {within="zone:…"}.

PromQL also has weekly baselines for the metrics the catalogue marks baseline (such as clients, traffic, airtime, PoE draw and controller CPU): baseline(x) is the usual value at this hour of the week (the median of the same UTC hour over up to 8 past weeks), baseline_mad(x) its spread, and baseline_weeks(x) how many weeks are behind it. They return nothing until 3 weeks of data exist, and work in alert rules too. For example, sum by (zone) (ap_clients) / sum by (zone) (baseline(ap_clients)) < 0.6.

On the Metrics card (Configure › Data collection), under Prometheus scrape endpoint, an admin clicks Create token. The token starts szms_ and is shown once, together with a ready-made Prometheus job; copy it then. Rotate token replaces it (the old one stops working at once) and Revoke deletes it. The card shows the token’s prefix, when it was created and when it was last used.

The token reads metrics, the organisation’s /health/org report, and GET /check (below), and nothing else. A scrape never calls your controller.

Send the token as a bearer token:

scrape_configs:
- job_name: smartzone
scheme: https
metrics_path: /metrics
scrape_interval: 60s
authorization:
credentials: szms_...
static_configs:
- targets: ['sz-mcp.lanpulse.com']

For tools that only do HTTP Basic auth, send the token as the password (the username is ignored).

SmartZone reports every 3 to 5.5 minutes, so scraping more often than once a minute gains nothing. By default no sample timestamps are written, so your scraper stamps each value at scrape time and series stay continuous between reports.

Each can repeat or take a comma-separated list.

ParameterEffectDefault
familyOnly ap, switch, cluster or probe metricsAll
metricOnly these metrics, by catalogue name (with or without the sz_ prefix)All
withinOnly entities under a zone, switch group, location…, e.g. within=zone:<id>Everything
max_ageLeave out series not reported for this many seconds (60–7200)1200
timestamps1 writes the controller’s own sample timesOff

Metrics that are reported late or seldom (controller CPU bins, licence and certificate expiry, synthetic check results) stay in the output for 2 to 3 hours regardless of max_age.

Every metric name is prefixed sz_ and has # HELP and # TYPE lines. Value series carry only identifying and grouping labels; one sz_<type>_info series per entity (value 1) carries the display names and the rest. Join them in PromQL:

sz_port_rx_kbps * on (port) group_left (name, switch_name) sz_port_info

Can my monitoring system poll the alert state?

Section titled “Can my monitoring system poll the alert state?”

Yes: GET https://sz-mcp.lanpulse.com/check returns the organisation’s alert problems as one Nagios-plugin-style result, with the same scrape token. It answers 200, or 503 when the result is CRITICAL, with the state (0 to 3) in the X-Nagios-Code header.

ParameterEffect
entityOnly problems on this entity or anything under it (an id or a bare MAC). An unknown one is UNKNOWN, never OK
ruleOnly these rules (comma-separated). An unknown one is UNKNOWN
include_handled=1Count acknowledged, in-downtime and unreachable problems too
format=json{ code, state, label, text, perfdata, counts, long } instead of plugin text
Terminal window
curl -s -H "Authorization: Bearer $SZMS_TOKEN" \
"https://sz-mcp.lanpulse.com/check?entity=switch:<MAC>"

It allows 300 checks a minute per organisation.

To have SZ-MCP push the alert state instead, as passive check results, see Send alert state to Nagios or Icinga.

LimitWhat happens
60 scrapes per minute per organisation429 with Retry-After
20 failed token checks per minute per client IP429
Missing or wrong token401
Unknown family or metric, or max_age out of range400, naming the problem
Output over 24 MB (roughly 140,000 series)413. The scrape is refused rather than cut short, since a partial scrape looks like series disappearing. Scrape per family (?family=ap, ?family=switch, ?family=cluster) or per container (?within=switchgroup:…)

A network of more than about 200 48-port switches needs to be split this way.