joule-profiler-cli 2.1.1

CLI tool to measure program energy consumption
Documentation

Joule Profiler ⚡

Rust Linux License Documentation

A modular tool for measuring energy consumption and performance metrics of programs on Linux systems.

Key Features

  • Multiple Metric Sources: RAPL (powercap/perf), perf_event counters, NVIDIA GPU (NVML)
  • Phase-Based Profiling: Measure energy consumption by program phases
  • Extensible Architecture: Easy to add custom metric sources
  • Low Overhead: Minimal impact on measured programs
  • Multiple Output Formats: Terminal, JSON, CSV

Quick Start

Installation

# Quick install with cargo
cargo install joule-profiler-cli

# Quick install with binaries
curl -fsSL https://raw.githubusercontent.com/joule-profiler/joule-profiler/main/install.sh | bash

# Or build from source
git clone https://github.com/joule-profiler/joule-profiler.git
cd joule-profiler
cargo build --release
sudo cp target/release/joule-profiler /usr/local/bin/

Basic Usage

# Phase-based profiling
sudo joule-profiler profile -- python workload.py

# JSON output
sudo joule-profiler --json profile -- ./benchmark

# GPU profiling (NVIDIA)
sudo joule-profiler --gpu profile-- ./gpu-workload

Documentation

Full Documentation

What Makes Joule Profiler Different?

Phase-Based Energy Profiling

Unlike traditional profilers, Joule Profiler can measure energy consumption of specific program phases, helping identify which sections contribute most to energy usage.

# example.py
print("__INIT__")
# initialization code
print("__COMPUTE__")
# heavy computation
print("__CLEANUP__")

sudo joule-profiler profile -- python example.py

Multiple Metric Sources

Source Metrics Requirements
RAPL (powercap) RAPL domains energy Intel CPU, kernel 3.13+
RAPL (perf) RAPL domains energy Intel CPU, perf_event support
perf_event Performance counters Linux perf support
NVML GPU energy NVIDIA GPU

Platform Support

  • OS: Linux (kernel 3.13+)
  • CPU: Intel (RAPL)
  • GPU: NVIDIA (NVML support)
  • Permissions: Root or appropriate capabilities required

Common Use Cases

  • Energy optimization: Identify energy-intensive code sections
  • Performance analysis: Correlate energy with performance counters
  • Green computing: Measure and reduce carbon footprint
  • Benchmarking: Compare energy efficiency across implementations

Contributing

Contributions are welcome! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Contact

Read the Full Documentation | * ⭐ Star on GitHub*