Telegram Bot

Telegram Bot

Knightwatch includes a Telegram bot for remote monitoring and alerting without opening the web dashboard.

Setup

Store your bot token in persistent config:

knightwatch config set telegram-token <YOUR_BOT_TOKEN>

Clear it if needed:

knightwatch config set telegram-token --clear

Verify it was saved:

knightwatch config get telegram-token

Enabling

Pass the --telegram flag at runtime:

knightwatch --pid <PID> --telegram

Notifications

The bot sends push notifications for all process events when tracking at least one process:

• 🟢 Initial snapshot — root and children when tracking begins
• 🆕 Children appeared — new child processes detected
• 🔴 Children exited — specific child PIDs exited
• ✅ All children gone — all child processes have exited
• 💀 Root process exited — the root process itself has stopped

When --system-resources is enabled:

• ⚠️ CPU threshold exceeded — aggregate CPU usage above 90%
• ⚠️ Memory threshold exceeded — memory usage above 90%
• ⚠️ Disk threshold exceeded — a mount point usage above 90%
• 🔋 Battery low — charge below 15% while discharging
• 🔌 Battery state changed — plugged in, unplugged, or full

When --docker is enabled:

• 🐳 Docker started — initial container list and count on startup
• 🆕 Containers appeared — new containers detected
• 👻 Containers disappeared — containers no longer visible to the tracker
• 🔄 Container status changed — previous and current status for a container
• 🏥 Container health changed — previous and current health state for a container
• 💥 Container OOM killed — a container was terminated by the out-of-memory killer
• ✅ / ❌ Container action result — success or failure of a command (stop, kill, start, restart, pause, unpause)

When --systemd is enabled:

• 🔴 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