Aegis documentation

#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.

bash
aegis pulse --helpaegis pulse status

The 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:

AreaSamplerWhat it carries
coreyeshost facts, every supervised service, scheduled jobs, network summary, problems
webnonginx counters (collector-backed, not implemented yet)
mailnodeliveries, queue depth, Postfix events
networknointerfaces, traffic and peers
connectionsnoestablished sockets grouped by address
nginxnonew 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.

bash
aegis pulse daemon
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis pulse daemonaegis pulse daemon &
text
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, nginx

A 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:

text
2026-11-17 06:41:05 core: bird is not listening

The 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

text
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 stop

The 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.

bash
aegis pulse status
Argument / optionDefaultMeaning
——none; the command takes no arguments or options
bash
aegis pulse statusaegis pulse status | head -8
text
Pulse  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:

text
  area       every   cycles  skipped  errors  last  core       5s      384     2        7       2026-11-17 06:42:04             ↳ bird is not listening

skipped 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:

text
pulse has not run yet (/aegis/run/pulse.status.json)

#Configuration

All keys live under [pulse] in config/aegis.toml.

toml
[pulse]enabled = trueinterval = 10           # fallback for every area without its own value[pulse.core]interval = 5
KeyDefaultMeaning
pulse.enabledtrueregister the keeper service
pulse.interval10fallback interval for an area, seconds
pulse.<area>.intervalpulse.intervalinterval 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:

TopicProducerContent
corepulsehost 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

bash
aegis pulse status        # did every area publish, and whenaegis check               # the pulse row of the health reportaegis keeper services     # is aegis-pulse running?
SymptomLikely cause
pulse has not run yetthe service was never started, or [pulse] enabled = false
state stoppedthe daemon exited; the pid and log say why
errors growing, last freshBird is down, or one sampler raises
every last frozenthe daemon is hung or the keeper is not supervising it
waiting for a sampler in aegis checkan 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.