Crate joularcore 

Joular Core is a Rust library for measuring power and energy across systems and devices.

It measures CPU and GPU power consumption in real time, and can break that down to individual processes or applications. Joular Core runs on Linux, Windows, macOS, Raspberry Pi, and inside virtual machines.

It allows applications, telemetry services, benchmarks, and custom developer tools to monitor CPU, GPU, and total system power, as well as attribute energy usage to specific process IDs (PIDs) or multi-process applications. It can export data to CSV files and to a shared-memory ring buffer.

Getting started example

use joularcore::JoularCoreMonitor;

let mut monitor = JoularCoreMonitor::for_app("firefox");

std::thread::sleep(std::time::Duration::from_secs(1));

let sample = monitor.poll();
println!("total {:.2} W, firefox {:.2} W", sample.total_power(), sample.target_power_or_zero());

Putting a session together

There are three independent choices, and nothing hides them from you:

• What to measure — MonitorConfig, passed to JoularCoreMonitor::from_config.
• Where to read it from — the platform’s own sensors by default. Replace any of them through JoularCoreMonitor::builder, which is how vm::VmSensor (the vm feature) is used inside a virtual machine.
• Where samples go — push destinations onto an OutputBundle.

Unavailable sensors

Power interfaces are privileged on most systems. When one cannot be read, MonitorSample::cpu_power and MonitorSample::gpu_power are None rather than 0.0, so an unreadable sensor is never mistaken for an idle machine. See the README for what each platform requires.

Output

Every destination is an output::OutputSink, and OutputBundle fans one sample out to all of them: CSV or bare-wattage files, and a shared-memory ringbuffer for other processes to read. To send samples anywhere else — over HTTP, into a database — implement OutputSink.

Adding a sensor of your own

The sensor module holds the traits every backend implements. Implement sensor::PowerSensor for a single source of power — that is all vm::VmSensor is — or sensor::Platform for a whole machine, and hand it to monitor::MonitorBuilder.

Logging

The library never writes to stdout or stderr on its own. It emits log records — warnings such as “RAPL is not readable” arrive there. Install whichever logger your program already uses (env_logger, simplelog, …); with no logger installed the records are discarded and nothing is printed.

Feature flags

• vm (default): allow reading power from files written by a hypervisor or an external meter, for use inside virtual machines.
• sbc: allow monitoring single-board computers using regression models, replacing the RAPL-based Linux one.

Re-exports

pub use config::AppMatch;

pub use config::Component;

pub use config::ElevationPolicy;

pub use config::MonitorConfig;

pub use config::Target;

pub use error::Error;

pub use error::Result;

pub use monitor::JoularCoreMonitor;

pub use monitor::MonitorSample;

pub use monitor::PowerRecord;

pub use output::FileWriter;

pub use output::OutputBundle;

pub use output::OutputSink;

pub use output::Schema;

pub use sensor::PowerSensor;

Modules

config

Configuration for a monitoring session.

error

The error type returned across the whole crate.

monitor

The sampling engine: turns sensor readings into MonitorSamples.

output

Where monitoring samples go: files and the shared-memory ring buffer.

platform

Per-platform sensor backends.

ringbuffer

Shared-memory ring buffer for low-latency IPC with other processes.

sensor

The traits a sensor backend implements, and the formula that splits CPU power between workloads.

vmvm

Reading power from a file instead of a hardware sensor.