joularcore/

lib.rs

/*
 * Copyright (c) 2025-2026, Adel Noureddine.
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the
 * GNU Lesser General Public License v3.0 only (LGPL-3.0-only)
 * which accompanies this distribution, and is available at
 * https://www.gnu.org/licenses/lgpl-3.0.en.html
 *
 * Author : Adel Noureddine
 */

//! 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
//!
//! ```no_run
//! 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.

// Items behind a feature gate (`vm`) are named in prose
// as code spans, not intra-doc links: a link from ungated documentation to an
// item that a reduced-feature build does not compile is a rustdoc warning, and
// `cargo doc` is expected to be clean under every feature combination.
#![cfg_attr(docsrs, feature(doc_cfg))]
#![warn(missing_docs)]
#![warn(unsafe_op_in_unsafe_fn)]
#![warn(clippy::doc_markdown)]
#![warn(clippy::must_use_candidate)]
#![warn(clippy::missing_errors_doc)]
#![warn(clippy::semicolon_if_nothing_returned)]
#![warn(clippy::explicit_iter_loop)]

pub mod config;
pub mod error;
pub mod monitor;
pub mod output;
pub mod platform;
pub mod ringbuffer;
pub mod sensor;

#[cfg(feature = "vm")]
#[cfg_attr(docsrs, doc(cfg(feature = "vm")))]
pub mod vm;

// The everyday surface, re-exported so ordinary use needs one import rather than
// one per module. Anything not here is still reachable through its module.
pub use config::{AppMatch, Component, ElevationPolicy, MonitorConfig, Target};
pub use error::{Error, Result};
pub use monitor::{JoularCoreMonitor, MonitorSample, PowerRecord};
pub use output::{FileWriter, OutputBundle, OutputSink, Schema};
pub use sensor::PowerSensor;

// The README's Rust examples are the first thing a new user runs, so they are
// compiled as doctests rather than left to drift away from the API. They are
// written against the default feature set, which is what a reader following the
// README will have, so they are only compiled when those features are present.
#[cfg(all(doctest, feature = "vm"))]
#[doc = include_str!("../README.md")]
struct ReadmeExamples;