How diffstorm/processwatchdog works
Project type and purpose
• This is a Linux-based, single-binary “daemon” utility (Process Watchdog) written in C.
• Its job is to read a list of applications from an INI file, start them with delays, monitor their health via UDP heartbeats (or simple liveness checks), restart any that hang or crash, and maintain statistics and a file-based command interface.
File structure
• Top-level:
• config.ini – declarative process list and UDP port
• run.sh – wrapper to relaunch the watchdog if it crashes
• Makefile – build script
• src/ – modular C source:
• ini.c/h – parse config.ini
• server.c/h – UDP listener and dispatcher
• apps.c/h – process-start/stop abstractions
• filecmd.c/h – file-based command interface (wdtstop, etc.)
• stats.c/h – statistics gathering & log file writer
• log.c/h – internal logging
• utils.c/h – shared utilities
• main.c – orchestration
• test.c/h – unit-test harness
• test_child.py – a Python script used by the example config to simulate child processes (heartbeat/no-heartbeat modes)
Extract key architectural points from the README
• Reads an INI file with N “apps”, each with start_delay, heartbeat_interval, cmd
• Opens a UDP socket on configured port, listens for “p< PID>” heartbeats
• Tracks last-heartbeat timestamps; if overdue, kills & restarts the process
• Provides file commands for manual control (startN, stopN, wdtstop, etc.)
• Writes per-app statistics to log files
a. Configuration Loader
– parses config.ini on startup
b. Process Manager
– spawns child processes (via apps.c)
– tracks PIDs, start/stop logic
c. Heartbeat Server (UDP Listener)
– binds to UDP port (server.c)
– dispatches heartbeat events to Process Manager
d. Watchdog Controller (main loop)
– enforces start_delay, heartbeat_delay, restart logic
– invokes filecmd module on detecting command files
e. File-Command Interface
– polls a directory or watches files (filecmd.c), translates files to control events
f. Statistics Logger
– collects metrics (start count, heartbeat stats) and writes to disk via log.c/stats.c
g. OS / External Environment
– Linux process API, signals, sockets
– File system (config, control files, log files)
h. Managed Applications
– arbitrary executables or scripts (e.g., test_child.py)
Interactions & data flow
1. On launch, the Watchdog Controller loads config.ini via Configuration Loader.
2. According to start_delay, the Process Manager forks/execs each app’s cmd.
3. Child processes send UDP heartbeats to the UDP port.
4. Heartbeat Server receives packets, extracts PID, notifies Watchdog Controller / Process Manager.
5. Watchdog Controller compares timestamps, decides if a process needs restart.
6. On restart, Process Manager kills old PID (if needed) and respawns via apps module.
7. File-Command Interface scans for “wdtstop”, “start2”, etc., instructs Watchdog Controller.
8. Statistics Logger records events (starts, crashes, heartbeat timing) to log files.
Architectural patterns & principles
• Modular layering: config parsing → core controller → I/O modules (UDP, FS) → process management → logging
• Event-driven: heartbeat arrival and file commands trigger actions
• Single responsibility: each C module handles one domain (INI, UDP, file cmd, logging)
• Config-driven behavior: no hard-coded processes, all managed entities defined in INI
Technologies & libraries
• C standard library, POSIX API (fork/exec, signals)
• BSD sockets for UDP
• Custom lightweight INI parser
• Shell script (run.sh) for resilience
• Python (test_child.py) for demo clients