joule-profiler-cli 3.0.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
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

# 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
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](examples/example_config.toml). 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:

```bash
# 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:
```bash
sudo sysctl kernel.perf_event_paranoid=0
```

See the [perf_event_paranoid](https://joule-profiler.github.io/sources/perf_event/perf_event_paranoid.html) 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](examples) directory. Also a library usage example is provided.

## 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
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 |
| **cgroup** | CPU/memory/IO usage | cgroup v2, root if cgroup creation or attach pid |
| **procfs** | Memory/IO usage | Linux, `/proc` access |
| **NVML** | NVIDIA GPU energy | NVIDIA GPU |
| **AMD SMI** | AMD GPU energy | AMD GPU, `amd-smi-lib` |

## 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](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/)**