Type: explanation · Last reviewed: 2026-07-17
Pulse Historian is not a single process. The main clarity binary supervises a set of child processes — the Python micro-services (reporting, EMS, tag mapping, and more) and the live connectors (the PI driver, backfill jobs). Something has to start them, keep them alive, restart them when they die, and make sure none are left orphaned when the app closes. That something is the ProcessManager. This page explains how that supervision works from an operator's point of view. For the exact API, restart accounting, and platform specifics, follow the links down to Process Manager (reference).
The ProcessManager keeps a registry (in its own SQLite database) of every process it should be running, each described by a process config: the command to run, whether to auto-start it, an optional health-check URL, and a restart policy with limits (how many restarts, within what window). It supervises two families:
pi-driver (started when you onboard a PI unit) and pi-backfill jobs.A background watchdog periodically checks every auto-start process. If one that should be running isn't, the watchdog restarts it — so a service that crashes comes back on its own, without an operator intervening. Restart attempts are counted within a time window, so a process that flaps (crash-restart-crash) doesn't loop forever; once it exceeds its limit in the window it's left down rather than hammered.
Health-checked services are polled at their health_check_url; a service that stops answering is treated as dead and recovered the same way.
Under the hood → Process Manager § Watchdog.
Two failure modes get explicit handling:
clarity exits any way — clean shutdown, Task-Manager kill, or crash — the OS terminates all its children with it. No stranded Python processes holding ports.Because the Python services are owned by a dedicated setup path, the reboot-restore step deliberately skips them (they're re-created by their own owner), avoiding a double-owner race that used to cause "random service failure after reboot."
Under the hood → Process Manager § Startup reconciliation · § Windows Job Object.
Every supervised process has its logs routed to its own file (e.g. mqtt.log, tag_mappings.log, licensing.log), rotated when they grow large, so you can read one service's output without wading through everything. A live view is served at /process-logs — a browser page backed by a WebSocket that pushes the process list, the last 1 000 log lines, and then live entries as they happen.
There are no HTTP start/stop endpoints — process control is internal to the app. The
/process-logsstream is read-only observability.
Under the hood → Process Manager § HTTP API · § Log routing.
When you onboard a PI unit for the canonical boiler-2 (see PI connector setup), the historian registers a managed pi-driver-<connection> process that polls PI and writes into the collection:
auto_start = true, so it starts immediately and again on every app launch.pi-driver PID from before the reboot is killed and a fresh one spawned; the driver resumes polling./process-logs, find pi-driver-<connection> in the list, and watch its live output.