Configuration

ProcessMonitor

You can configure any number of <Process> to watch OS processes or groups of processes.

<SystemMonitor>

  <ProcessMonitor onUsage="" onIdle="">

    <Process ... />
    <Process ... />

  </ProcessMonitor>

</SystemMonitor>

pollInterval

⏱️ duration:

default:

2s

Sets the interval at which the Process Monitor polls the OS for process changes.

On Windows, process changes are delivered by ETW event notifications and this setting has no effect.

On macOS and Linux, where no event-based alternative is used, this is the detection latency for a process starting. A tick costs a single system call there, so short intervals are affordable.

This is a system setting and changing it requires restarting the daemon.

<?system ProcessManager:pollInterval="5s" ?>

See Performance.

onUsage

⚡️ event:

This event is triggered on every inspection cycle in which at least one configured process group reports activity.

onIdle

⚡️ event:

This event is triggered when every configured process group is idle.

Process

<Process name="Browser" watchChildren="false" minCPU="1%" watch="CPU"
  onUsage="" onIdle="stop" onStart="" onStop="">

  chrome|edge|firefox

</Process>

name

You can provide any logical name here, to describe the process or group of processes. This name will be used to represent these processes in the log.

text

🔍 regex:

The text node of the <Process> will be parsed as a regular expression and matched against the name of the process.

If the expression contains a path separator — a /, or a \\ matching a literal backslash — it is matched against the full path of the executable instead. Nothing else changes the choice: a . is read as the regular-expression wildcard it is, so chrome.* still matches by name.

<Process name="Browser">chrome|firefox</Process>
<Process name="Games">/usr/games/.*</Process>

watchChildren

default:

false

By default, this process group will only include processes with a matching image name. However, if you set watchChildren, their spawned child processes will also be included. However, each individual process will only be included once. Therefore, you can safely set this for processes that spawn child processes of themselves (e.g. most of the web browsers).

minCPU

For each process group, you can set a cumulative CPU threshold so that it counts as usage. The following formats are valid:

10%

When a number is configured with a percentage unit, the absolute processing time will be compared with the total processing time available since the last timeout. The used processing time has to be more than this average for the resource to be considered non-idle. The total processing time takes into account the number of available processing cores, so the value will correspond to what you see in Task Manager.

10min

When a number is configured with a time unit, it is compared to the absolute processing time since the last timeout. If multiple cores are used, the processing time can exceed the elapsed clock time by a factor equal to the number of installed cores. You can use the usual format for durations.

Use the watch expression to combine this result with other configured metrics. With no thresholds, the default catch-all expression counts every matching process as activity.

minGPU

The cumulative graphics-processing threshold for a process group, including watched children. It accepts the same percentage and duration forms as minCPU:

10ms

More than ten milliseconds of GPU processing during the inspection interval.

10%

GPU processing time greater than ten percent of the interval. One graphics engine busy for the full interval is 100%; simultaneous engines can total more than 100%. This is not normalized across CPU cores and need not match a utilization percentage shown by another monitoring application.

Use watch="CPU or GPU" when either CPU or graphics work should count. If several thresholds are supplied without a custom expression, a process uses AND by default.

A threshold of 0 always matches when the counter is readable. It does not disable GPU collection. GPU thresholds are unavailable on Linux, and availability on Windows/macOS depends on the hardware and platform counters. Unsupported configured measurements are reported as configuration errors.

For the macOS accounting setting, see Performance.

minIO

For each process group, you can set a cumulative storage IO threshold, so that only a group actually moving data counts as usage. The following formats are valid:

100kb

A number with a binary unit declares an amount of bytes that have to be read from or written to storage during the configured timeout of the System Monitor, otherwise the process group will be considered idle.

1MB/s

A number with both a binary unit and a time period declares an amount of bytes that have to be read from or written to storage in average during the configured timeout of the System Monitor, otherwise the process group will be considered idle.

A number without a binary unit (e.g. 500 or 100/s) is rejected here: on the network side it would mean raw packets, which processes cannot count.

Storage IO deliberately excludes network traffic — that is what minTraffic is for. What exactly is counted is each platform’s closest honest answer:

• Windows counts file IO as the process performs it: reads served from the cache count in full, traffic through the socket APIs does not, and memory-mapped IO is invisible.

• Linux counts bytes the process moves to and from the storage layer (read_bytes/write_bytes): reads served from the page cache are invisible, buffered writes are credited to the writing process. When a watched process reaps a child, the child’s lifetime totals fold into the parent in one jump, so the cycle after a child exits may report demand once too often.

• macOS counts physical disk reads (reads served from the cache are invisible — the platform keeps no logical read counter) and file writes to internal storage, both buffered and direct; on external volumes only direct and flushed writes are visible, not buffered writes as such.

A platform that keeps no such counter at all refuses minIO when the watch is built, naming the watch and the attribute, rather than carrying a threshold nothing measures. Where the counters exist but a single process will not answer for them — one that exited between two cycles, or one the service may not open — that process contributes nothing and the rest of the group is measured as usual. A cycle in which no matching process can supply the configured counter is an inspection error.

Use the watch expression to combine this result with other configured metrics.

minTraffic

Attention

Windows and macOS only. Linux offers no per-process network counter, and configuring minTraffic where none exists is refused outright: the service reports the watch and the attribute, and does not start. A threshold nothing measures cannot be honoured either, and a machine guarded by an attribute nobody is watching is worse than one that said so.

For each process group, you can set a cumulative network traffic threshold, so that only a group actually transferring data over the network counts as usage.

Metered are actual TCP and UDP payload bytes per process — the same numbers the system’s own tools show in their per-process network columns. Both platforms meter on demand: nothing is measured until a process a minTraffic threshold applies to is first sampled, and the metering stops when the last such process is gone. A configuration without minTraffic therefore pays nothing at all.

Windows reads them from a kernel event tracing (ETW) session. While it runs, the kernel reports every packet-sized network event on the machine — so the cost is continuous for exactly as long as a matching process runs.

macOS reads them from the kernel’s own per-flow counters instead, asking once per monitor cycle rather than being told continuously; between cycles the metering costs nothing. Because there is no public interface for those counters, the daemon speaks the private one the system’s tools use, and checks at startup that it still understands what the running kernel answers. Where it does not — a macOS whose layout this build has never seen — a configured minTraffic is refused like an unsupported platform, with the details in the log. Metering needs no additional privileges beyond those the daemon already runs with.

Note

On macOS, traffic belonging to a socket one process opened on behalf of another is counted for the process it was opened for, not for the one doing the transferring.

The formats match minIO:

100kb

Bytes that have to be received or sent during the configured timeout of the System Monitor, otherwise the process group will be considered idle.

1MB/s

Bytes that have to be received or sent in average during the configured timeout of the System Monitor, otherwise the process group will be considered idle.

A number without a binary unit is rejected, as for minIO.

Use the watch expression to combine this result with other configured metrics.

watch

default:

default AND

Combines the configured process metrics into an activity expression. By default, all supplied metrics must report activity. With no thresholds, a matching running process counts as active.

<Process name="Game" minCPU="20%" minGPU="10ms"
         watch="CPU or GPU">game</Process>

See Watch expressions for syntax, available metrics, defaults, and expression composition.

onIdle

⚡️ event:

This event is triggered when the watch expression evaluates to false for a running process group. With no thresholds, the default catch-all expression keeps a matching process demanded.

onUsage

⚡️ event:

This event is triggered on every inspection cycle in which the watch expression evaluates to true for the process group.

onStart

⚡️ event:

This event is triggered when the first process of this group starts.

onStop

⚡️ event:

This event is triggered when the last process of this group exits.