Separate privileged acquisition from unprivileged clients.
RAPL access can require elevation; the Unix socket becomes a narrow, auditable boundary.Alternative not selected: Letting every Python or CLI process read protected counters directly.
Trace-first energy measurement
Wattch Core
A protocol-first Rust measurement spine that separates privileged energy acquisition from unprivileged CLI, Python and VS Code workflows while preserving replayable raw evidence.
Context and problem
Hardware energy counters can require elevated access, while developers, tests and benchmark tools need a safe workflow that preserves source meaning and does not turn noisy machine-level evidence into false process-level precision.
Ownership and contribution
Chakib designed and implemented the daemon/client boundary, typed protocol and validation model, Linux RAPL and synthetic acquisition paths, replayable CLI artifacts, the pywattch client and the Energy Tests developer workflow.
Responsibilities
- Implemented the Rust domain, protocol, daemon, powerd, deterministic test daemon and CLI crates.
- Defined typed source descriptors, evidence classes, sequence invariants and versioned local frames.
- Built replayable capture/inspect/validate artifacts and a pyJoules-compatible Python client.
- Added Energy Tests discovery and a VS Code results surface with per-domain joule and budget columns.
- Documented privilege, socket permissions, counter semantics, failure behavior and explicit non-goals.
Architecture and data flow
A privileged wattch-powerd daemon reads Linux RAPL counters or a synthetic source and serves strict, versioned frames over a local Unix socket. Unprivileged CLI and Python clients capture source descriptors and raw sample batches into immutable run artifacts; inspection, tests and later interpretation stay outside the acquisition path.
- Linux RAPL powercap or synthetic source
- wattch-powerd acquisition daemon
- Versioned local Unix-socket protocol
- CLI / pywattch / Energy Tests
- Manifest + descriptors + raw trace
- Offline inspect and validation
Engineering decisions
Keep the daemon deliberately interpretation-free.
Raw descriptors and samples remain replayable while aggregation, comparison and claims evolve offline.Alternative not selected: Embedding baselines, joules-per-token, scoring or optimization advice in the acquisition path.
Reliability, security and evaluation
- Descriptor and sample invariants reject unknown sources, invalid units and non-monotonic sequences.
- The deterministic daemon and checked-in scenarios validate the same protocol path without presenting synthetic values as hardware measurements.
- CI runs Rust formatting, Clippy with warnings denied, workspace tests, Python-client tests and extension tests.
Outcome and status
The public foundation supports Linux RAPL and synthetic acquisition, a strict local protocol, deterministic test scenarios, CLI capture/inspect/validate workflows, replayable traces, a pywattch Python API and VS Code Energy Tests. It does not claim per-process energy allocation or absolute meter accuracy.
Technology groups
Systems
Rust, Linux, RAPL, Unix sockets
Clients
CLI, Python, pyJoules API, VS Code
Evidence
Typed descriptors, Deterministic daemon, Replayable traces
Proof and source material
