Joule Profiler ⚡

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
joule-profiler profile -- <COMMAND>

# JSON output
joule-profiler --output-format json profile -- <COMMAND>

# GPU profiling (NVIDIA)
joule-profiler --sources rapl,nvml profile -- <COMMAND>

A configuration file can be used to configure the tool using the CLI flag --config, see configuration file. The CLI arguments will ALWAYS override the configuration arguments.

Any key of the configuration file can be set from the command line with -D KEY=VALUE, where KEY is the toml key. This works with or without a --config file, and can be repeated:

# Switch the RAPL backend and restrict it to the first socket
joule-profiler -D profiler.rapl_backend=powercap -D "sources.rapl.sockets_spec=[0]" profile -- <COMMAND>

[!IMPORTANT] If a config option is not in string format, then you must add brackets.

For the RAPL source with the perf_event backend, you might be asked to run Joule Profiler with the root privileges, you can configure the perf_event_paranoid level to allow using the source without them:

sudo sysctl kernel.perf_event_paranoid=0

See the perf_event_paranoid documentation for further information. Some sources like Cgroup or RAPL with the powercap backend can also require root privileges.

Some examples programs and outputs are provided in the examples directory. Also a library usage example is provided.

Documentation

Full Documentation

• Quickstart
• Metric Sources
• Examples

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__")

joule-profiler profile -- python example.py

Multiple Metric Sources

Platform Support

• OS: Linux (kernel 3.13+)
• CPU: Intel (RAPL)
• GPU: NVIDIA (NVML) and AMD (AMD SMI)
• 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

• JouleIt by @powerapi-ng for inspiration

Contact

• Issues: GitHub Issues
• Author: @jwoirhaye, @FrancoisGib

Read the Full Documentation | * ⭐ Star on GitHub*