Rotom integration
The scanner's own view of each box, as a health signal Magnemite cannot produce on its own.
A box can be online, heartbeating, with the scanner process alive, and handing Rotom nothing. The agent has no way to see that; Rotom is the only thing that does. With the integration on, the hub asks it what it thinks of the whole fleet, every ten seconds.
Configuration
ROTOM_ENABLED=true
# /api is appended, so either form works.
ROTOM_URL=http://rotom:7072
# Matches `secret` under http_listener in the Rotom config.
ROTOM_SECRET=your_secret_hereA Rotom published through a proxy is often gated by BasicAuth before Rotom sees
the request. That is a second credential, the proxy checks Authorization, Rotom checks X-Rotom-Secret:
ROTOM_BASIC_USERNAME=your_reverse_proxy_user
ROTOM_BASIC_PASSWORD=your_reverse_proxy_passwordCheck the Health/Status page for the integration's own health.
If Rotom runs in another compose project, the hub still has to reach it: share an external
network, or point ROTOM_URL at its published host and port.
Integration benefits
A Scanner column
On the fleet table, once at least one box is matched: scanning, idle, stalled, disabled or not scanning, with the workers in use and the request rate behind it.
Three monitoring signals
Rotom lost the box, has the box but no workers, and scanner allocated and doing nothing — the only box-health signals that work on every box today, since the hub reads them rather than the agent.
Actions that survive a dead agent
Restart, disconnect and reboot travel Rotom's socket, so they still work on a box Magnemite cannot reach. Enable and disable take a box out of the pool by hand.
What the Scanner column says
| Badge | What it means |
|---|---|
scanning | Connected, a worker allocated, requests going through it |
stalled | A worker is allocated and no requests are going through it |
idle | Connected, and Rotom has nothing allocated on the box |
disabled | Someone took the box out of Rotom's pool on purpose |
not scanning | Rotom has no connection to the box |
— | No matching device in Rotom |
The counts read 2/4w, in use over attached. The rate is only shown where
Rotom measures one; see Request rates below.
The scanner page
The Agent card on a device page carries one line, scanning, not scanning,
not matched, and a additional page with more extensive details.
Acting on a box
Five actions, on the rotom device page and, for three of them, as remediation rungs a rule can take.
| Action | What it does |
|---|---|
| Restart scanner | Restarts the scanner app |
| Drop connection | Rotom drops its socket to the box and all its workers; the box reconnects on its own |
| Reboot | Reboots the box |
| Disable / Enable | Takes the box out of, or back into, Rotom's selection pool |
All five actions travel Rotom's own connection, never the agent's, and that is the point of them: a box whose Magnemite agent has died can still be restarted or rebooted this way if Rotom is still able to communicate with it.
Matching
Devices are matched by Rotom's id: the handle the box registered under,
against the device name, then the serial. origin is not a name: the API gives
it as the address Rotom sees the box connect from, so it is only ever matched
against the box's LAN address, and the public IP likewise. Both addresses only
decide it when exactly one box is a candidate, since a NAT and a DHCP lease each
hand the same address to more than one box. A box that never matches keeps
working normally, it simply has no Scanner column and no Rotom rule.
Freshness
Settings → Tuning → Ask Rotom every (10s) is one request for the whole
fleet, and the resolution of everything Rotom-shaped: the column and the
ROTOM_DISCONNECTED signal are only ever as fresh as the last sync. Rotom
stale after sits directly below it and must be at least two sync intervals,
or a rule alerts on the sync's own lag; the form refuses the combination rather
than letting a fleet discover it through the alerts.
How much of it is kept is a different number. History rides Metric history → Scanner (Rotom) → Sample every (60s), not this: the sync is fast so the column and the rules are current, and keeping six rows a minute per box to draw a chart that buckets them back down again would be six times the table for the same picture. That field is floored at this one — sampling faster than Rotom is asked keeps every sync and no more.
Rotom has no single "healthy" field, so the rule uses the composite its API
implies, enabled && is_connected && can_be_used + how long ago it last
saw the box. One state is deliberately not a fault: a box somebody disabled
in Rotom on purpose. Alerting on that would mean alerting on a decision
already made.
A box has to be missing from Rotom's list twice in a row before it is called disconnected, and a Rotom that answers with no devices at all is treated as silence rather than as an empty fleet. One poll is one opinion: a Rotom mid-restart or a proxy that dropped a request would otherwise mark every box offline at once, and a rule two rungs up would start acting on it before the next sync could disagree.
Built against the
RotomNG API:
GET /api/device?include_workers=true and
PUT /api/device/{id}/action/{action}.