#pulse — the realtime monitor
aegis-pulse is the realtime monitor behind the panel. It samples the platform area by area and publishes every snapshot through Bird, the WebSocket transport; a browser never talks to a sampler and a sampler never talks to a browser.
The command group is small on purpose. Pulse has no catalogue to edit and no queue to drain: it has one foreground loop and one report that reads the counters the loop already wrote.
aegis pulse --helpaegis pulse statusThe group has no banner of its own: a bare aegis pulse is an argparse error (exit 2), and --help lists the two commands.
#What an area is
MONITORS is the single list of everything the platform watches:
| Area | Sampler | What it carries |
|---|---|---|
core | yes | host facts, every supervised service, scheduled jobs, network summary, problems |
web | no | nginx counters (collector-backed, not implemented yet) |
mail | no | deliveries, queue depth, Postfix events |
network | no | interfaces, traffic and peers |
connections | no | established sockets grouped by address |
nginx | no | new requests and stub-status counters |
An area with no sampler is not silently dropped: the daemon logs it once as waiting for a sampler: …, the status file records the list, and aegis check reports it. That is how a configured area can be seen to be waiting instead of looking broken.
Each area has its own interval. The loop is a dispatcher: every half second it looks at the areas whose interval has elapsed and hands each one to a worker thread, so a slow sampler never delays the others. If a worker is still busy at its next turn, that tick is skipped and counted, not queued — a monitoring snapshot is only useful while it is fresh.
#Commands
#aegis pulse daemon
Run the sampler loop in the foreground. The keeper starts exactly this command as the service aegis-pulse; run it by hand to watch a cycle, and stop it with Ctrl-C.
aegis pulse daemon| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis pulse daemonaegis pulse daemon &2026-11-17 06:40:00 aegis-pulse started, core every 5s2026-11-17 06:40:00 waiting for a sampler: web, mail, network, connections, nginxA successful cycle publishes on the private channel under the area's name and writes nothing to stdout; the counters land in the status file. A failing sampler is logged and recorded instead of breaking the loop:
2026-11-17 06:41:05 core: bird is not listeningThe daemon owns run/pulse.pid and refuses a second copy. The first process logs its start; the second logs already running (pid 802341) and exits 0.
SIGTERM and SIGINT end the loop after the current tick; the pid file is removed and the status file is marked stopped.
#What it writes
run/pulse.status.json pid, start time, per-area counters, intervals, missing areasrun/pulse.pid the process idlogs/pulse.log one line per start, skip, error and stopThe status file is rewritten atomically after every sample, so aegis pulse status never sees a half-written document.
#aegis pulse status
Print the daemon's own counters: who is running, since when, and one row per area with its interval, cycles, skipped ticks, errors and the time of the last snapshot. The command only reads run/pulse.status.json, so it is safe to run against a live monitor at any time.
aegis pulse status| Argument / option | Default | Meaning |
|---|---|---|
| — | — | none; the command takes no arguments or options |
aegis pulse statusaegis pulse status | head -8Pulse pid 802341 started 2026-11-17 06:10:02 updated 2026-11-17 06:42:04 state running area every cycles skipped errors last connections 10s 0 0 0 - core 5s 384 0 0 2026-11-17 06:42:04 mail 60s 32 0 0 - network 10s 0 0 0 - nginx 10s 0 0 0 - web 10s 0 0 0 -Errors are cumulative, and the most recent message is repeated under its area:
area every cycles skipped errors last core 5s 384 2 7 2026-11-17 06:42:04 ↳ bird is not listeningskipped counts ticks where the previous sample of that area was still running. A slowly growing errors with a fresh last means one sampler is unhealthy while the rest are fine; a last that stops moving means the daemon is gone.
Before the first run, or after the status file was removed, the command prints one line and exits 0:
pulse has not run yet (/aegis/run/pulse.status.json)#Configuration
All keys live under [pulse] in config/aegis.toml.
[pulse]enabled = trueinterval = 10 # fallback for every area without its own value[pulse.core]interval = 5| Key | Default | Meaning |
|---|---|---|
pulse.enabled | true | register the keeper service |
pulse.interval | 10 | fallback interval for an area, seconds |
pulse.<area>.interval | pulse.interval | interval for one area, seconds (minimum 1) |
An interval that is missing or unparsable falls back to the default rather than disabling the area silently; a value below one is clamped to one second.
#Where the data goes
Pulse publishes to Bird, on the private channel, with the area name as the topic:
| Topic | Producer | Content |
|---|---|---|
core | pulse | host facts, services, jobs, network summary, problems |
A message is published with app.modules.bird.publish.send; a stopped Bird returns False, which the sampler turns into its error counter. Nothing queues: the next snapshot corrects the view. The panel follows the feed through /api/live, and the tasker uses the same transport for its log, so the topic table above grows as other areas get a sampler.
#Checking it is alive
aegis pulse status # did every area publish, and whenaegis check # the pulse row of the health reportaegis keeper services # is aegis-pulse running?| Symptom | Likely cause |
|---|---|
pulse has not run yet | the service was never started, or [pulse] enabled = false |
state stopped | the daemon exited; the pid and log say why |
errors growing, last fresh | Bird is down, or one sampler raises |
every last frozen | the daemon is hung or the keeper is not supervising it |
waiting for a sampler in aegis check | an area without a sampler; expected for web, mail, network, connections and nginx in this build |
Nothing here is destructive: daemon runs a foreground process, status reads a file. Stopping the service is a keeper operation.