Systemd Monitor

Systemd Monitor

Linux only. On any other OS, passing --systemd prints a warning and the flag is ignored.

When enabled with --systemd, Knightwatch polls systemd over D-Bus every second and exposes unit state via the /systemd family of endpoints. It also emits unit change events to the Telegram bot and webhook dispatcher.

knightwatch --pid <PID> --systemd

Endpoints

Endpoint	Description
GET /api/systemd	Full snapshot — all units with counts
GET /api/unit/<unit_name>	Single unit by name (e.g. nginx.service), or 404
GET /api/units/<unit_state>	All units matching an active state (active, failed, etc.)
GET /api/failed_units	Shorthand for all units in the failed state

Systemd Commands

When the server is started with --allow-systemd-commands, the following write endpoints become available.

Authentication required. All systemd command endpoints always require authentication, regardless of whether --enable-auth is set.

knightwatch --systemd --allow-systemd-commands

Command Endpoints

Endpoint	Description
POST /api/systemd/poll/pause	Pause the polling loop
POST /api/systemd/poll/resume	Resume the polling loop
POST /api/systemd/poll/interval	Change the polling interval

Controlling the Poll Loop

Pause snapshot collection (the tracker still responds to queries):

POST /api/systemd/poll/pause

Resume at the current interval:

POST /api/systemd/poll/resume

Change the polling interval (takes effect immediately):

POST /api/systemd/poll/interval
Content-Type: application/json
 
{ "interval_ms": 2000 }

---

Webhook Events

Event	Description	Key data fields
systemd.initial_snapshot	First unit snapshot after startup	timestamp, unit_count, failed_count, active_count, inactive_count
systemd.tick	Periodic unit snapshot	timestamp, unit_count, failed_count, active_count, inactive_count
systemd.unit_failed	A unit transitioned to failed	unit_name, previous_state
systemd.unit_recovered	A previously failed unit recovered	unit_name
systemd.unit_appeared	A new unit became visible	unit_name, active_state, sub_state, description
systemd.unit_disappeared	A unit is no longer present	unit_name

Telegram Notifications

When both --systemd and --telegram are enabled, the bot sends alerts for:

• 🔴 Unit failed — a unit transitioned to failed
• 🟢 Unit recovered — a previously failed unit is active again
• 🆕 Unit appeared — a new unit became visible to systemd
• 💨 Unit disappeared — a tracked unit is no longer present