joule-profiler-cli 2.1.1

CLI tool to measure program energy consumption
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# Joule Profiler ⚡

[![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=for-the-badge&logo=rust&logoColor=white)](https://www.rust-lang.org/)
[![Linux](https://img.shields.io/badge/Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black)](https://www.linux.org/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=for-the-badge)](LICENSE)
[![Documentation](https://img.shields.io/badge/docs-mdbook-blue?style=for-the-badge)](https://joule-profiler.github.io)

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

```bash
# 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

```bash
# 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](https://joule-profiler.github.io/)**

- [Quickstart](https://joule-profiler.github.io/quickstart.html)
- [Metric Sources](https://joule-profiler.github.io/sources/overview.html)
- [Examples](https://joule-profiler.github.io/examples/overview.html)

## 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.

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

```bash
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](https://github.com/joule-profiler/.github/blob/main/CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Acknowledgments

- [JouleIt](https://github.com/powerapi-ng/jouleit) by [@powerapi-ng](https://github.com/powerapi-ng) for inspiration

## Contact

- **Issues**: [GitHub Issues](https://github.com/joule-profiler/joule-profiler/issues)
- **Author**: [@jwoirhaye](https://github.com/jwoirhaye), [@FrancoisGib](https://github.com/FrancoisGib)

---

**[Read the Full Documentation](https://joule-profiler.github.io)** | *
*[⭐ Star on GitHub](https://github.com/joule-profiler/joule-profiler/)**