pulsatrix::SystemMonitor Class Reference

Samples CPU/GPU utilization, memory use and temperatures on a background thread, keeps a bounded in-memory history, and streams every sample to a log file. More...

#include <system_monitor.hpp>

Classes
struct	Options
	Construction options. More...

Public Member Functions
	SystemMonitor ()
	Default options: 1 s interval, no log.
	SystemMonitor (Options options)
	SystemMonitor (Options options, std::unique_ptr< detail::PlatformSources > sources)
	Testing hook: reads from sources instead of the host (see system_monitor_detail.hpp).
	~SystemMonitor ()
	Stops the background thread (if running) and closes the log.
	SystemMonitor (const SystemMonitor &)=delete
SystemMonitor &	operator= (const SystemMonitor &)=delete
void	start ()
	Opens the log (if any) and starts the background sampling thread. No-op if running.
void	stop ()
	Stops and joins the background thread, then closes the log. No-op if not running.
bool	running () const
	True between start() and stop().
SystemSample	sample_now ()
	Takes one synchronous measurement on the calling thread. Works without start().
std::optional< SystemSample >	latest () const
	The most recent background sample, or std::nullopt before the first one.
std::vector< SystemSample >	history () const
	Background samples, oldest first, at most Options::history_capacity of them.
void	on_sample (std::function< void(const SystemSample &)> callback)
	Registers a callback run on the monitor thread after each background sample (after it is logged and stored). Replaces any previous callback; pass {} to clear.
void	mark (std::string label)
	Sets the label carried by subsequent samples (e.g. "epoch 3", "explain:lrp"), and if the log is open writes an immediate "event":"mark" record.
std::vector< MetricCapability >	capabilities () const
	Per-metric availability on this machine, with the source or the reason it is missing.
const Options &	options () const noexcept
	The options this monitor was constructed with.

Detailed Description

Samples CPU/GPU utilization, memory use and temperatures on a background thread, keeps a bounded in-memory history, and streams every sample to a log file.

Usage:

pulsatrix::SystemMonitor::Options opts;
opts.interval = std::chrono::milliseconds(500);
opts.log_path = "run.jsonl";
pulsatrix::SystemMonitor monitor(opts);
monitor.start();
monitor.mark("epoch 1");   // tags this and later samples
...train...
monitor.stop();

Sources (all detected at runtime, no link-time dependency):

• Linux: /proc/stat, /proc/self/stat, /proc/meminfo, /proc/self/status, hwmon CPU sensors (k10temp, zenpower, coretemp, cpu_thermal, then acpitz as a last resort), AMD GPUs via /sys/class/drm/card<N>/device (amdgpu sysfs).
• Windows: GetSystemTimes, GetProcessTimes, GlobalMemoryStatusEx, GetProcessMemoryInfo. CPU temperature is not readable without WMI/admin rights and is always std::nullopt.
• NVIDIA GPUs (Linux and Windows): NVML, loaded with dlopen/LoadLibrary when present.
• Other platforms: compiles, every metric std::nullopt with a reason.

Note

No fabricated values: a metric that cannot be read is std::nullopt in the sample, null in the JSON log and an empty CSV cell – see capabilities() for the reason.

Timing: start() takes a baseline reading and the first background sample is taken one interval later, so every background sample carries CPU rates over a full interval. latest() is empty until then.

Thread safety: every public member may be called from any thread. Do not call stop() or destroy the monitor from inside the on_sample() callback (stop() throws std::logic_error if called from the monitor thread).

Constructor & Destructor Documentation

SystemMonitor() [1/4]

pulsatrix::SystemMonitor::SystemMonitor

(

)

Default options: 1 s interval, no log.

SystemMonitor() [2/4]

pulsatrix::SystemMonitor::SystemMonitor ( Options  options )

explicit

Exceptions

std::invalid_argument

if options.interval is not positive.

SystemMonitor() [3/4]

pulsatrix::SystemMonitor::SystemMonitor	(	Options	options,
		std::unique_ptr< detail::PlatformSources >	sources
	)

Testing hook: reads from sources instead of the host (see system_monitor_detail.hpp).

Exceptions

std::invalid_argument

if options.interval is not positive or sources is null.

~SystemMonitor()

pulsatrix::SystemMonitor::~SystemMonitor

(

)

Stops the background thread (if running) and closes the log.

SystemMonitor() [4/4]

pulsatrix::SystemMonitor::SystemMonitor ( const SystemMonitor &  )

delete

Member Function Documentation

capabilities()

std::vector< MetricCapability > pulsatrix::SystemMonitor::capabilities

(

)

const

Per-metric availability on this machine, with the source or the reason it is missing.

history()

std::vector< SystemSample > pulsatrix::SystemMonitor::history

(

)

const

Background samples, oldest first, at most Options::history_capacity of them.

latest()

std::optional< SystemSample > pulsatrix::SystemMonitor::latest

(

)

const

The most recent background sample, or std::nullopt before the first one.

mark()

void pulsatrix::SystemMonitor::mark

(

std::string

label

)

Sets the label carried by subsequent samples (e.g. "epoch 3", "explain:lrp"), and if the log is open writes an immediate "event":"mark" record.

on_sample()

void pulsatrix::SystemMonitor::on_sample

(

std::function< void(const SystemSample &)>

callback

)

Registers a callback run on the monitor thread after each background sample (after it is logged and stored). Replaces any previous callback; pass {} to clear.

Note

Keep it short: sampling of the next interval waits for it. An exception thrown from it is caught, reported once to stderr, and the thread keeps running.

operator=()

SystemMonitor & pulsatrix::SystemMonitor::operator= ( const SystemMonitor &  )

delete

options()

const Options & pulsatrix::SystemMonitor::options ( ) const

noexcept

The options this monitor was constructed with.

running()

bool pulsatrix::SystemMonitor::running

(

)

const

True between start() and stop().

sample_now()

SystemSample pulsatrix::SystemMonitor::sample_now

(

)

Takes one synchronous measurement on the calling thread. Works without start().

Note

Does not touch latest(), history() or the log. Its CPU rates are measured since the previous sample_now() call (or construction, for the first call).

start()

void pulsatrix::SystemMonitor::start

(

)

Opens the log (if any) and starts the background sampling thread. No-op if running.

Exceptions

std::runtime_error

if Options::log_path is set but cannot be opened for writing.

stop()

void pulsatrix::SystemMonitor::stop

(

)

Stops and joins the background thread, then closes the log. No-op if not running.

Note

Returns within milliseconds regardless of the interval (the thread waits on a condition variable, not a sleep) – unless a sample/callback is mid-flight.

Exceptions

std::logic_error

if called from the on_sample() callback (monitor thread).

---

The documentation for this class was generated from the following file:

• include/pulsatrix/system_monitor.hpp