PowerTrace

PowerTrace is a comprehensive framework designed for power measurement, attribution, and control of CPU-bound workloads and benchmarks. It provides tools for:

• Benchmarking: Running various benchmarks and collecting performance data.
• Power Measurement & Estimation: Tools to measure and estimate power consumption.
• Power Attribution: Attributing power usage to specific components or processes.
• Power Control: Implementing power capping and management strategies.
• Power Prediction: Predicting power characteristics.

Prerequisites

Before setting up PowerTrace, ensure your system meets the following requirements. Carefully follow each step to avoid common setup issues.

1. Operating System

• Ubuntu 22.04 LTS or newer (or a compatible Debian-based distribution).
• Kernel: Linux kernel with cgroup v2 enabled and cpuset, cpu controllers available.

How to Verify cgroup v2

PowerTrace relies heavily on cgroup v2. To verify if your system is using cgroup v2, run the following command:

mount | grep cgroup

You should see output similar to this, indicating cgroup2 is mounted:

cgroup2 on /sys/fs/cgroup type cgroup2 (rw,nosuid,nodev,noexec,relatime,nsdelegate)

If you see cgroup (without the 2) or no cgroup2 entry, your system might be using cgroup v1 or a hybrid mode. PowerTrace is designed for cgroup v2. Consult your distribution's documentation on how to enable cgroup v2 if it's not active.

2. User Permissions

• sudo access is required for installation and cgroup setup.

3. Hardware

• At least two CPU sockets are highly recommended for optimal cgroup control setup, especially if you plan to use the cgroup_ctl_setup.sh script for workload isolation. While PowerTrace can function on single-socket systems, some advanced features related to CPU core isolation across sockets will not be available.

Installation

Follow these steps precisely to set up PowerTrace on your system.

Step 1: Clone the Repository

First, clone the PowerTrace repository to your local machine:

git clone https://github.com/your-repo/PowerTrace.git # Replace with the actual repository URL
cd PowerTrace

Step 2: Install Dependencies

Execute the dependencies.sh script to install all necessary packages and Python libraries. This script requires sudo privileges.

Important: This step will install system-wide packages and Python libraries. Ensure you have an active internet connection.

sudo ./dependencies.sh

This script will:

• Add a PPA for stress-ng.
• Update package lists.
• Install core system utilities: python3-pip, luarocks, docker.io, memtier-benchmark, bison, flex, redis, libevent-dev, libssl-dev, cgroup-tools.
• Install Linux performance tools: linux-tools-common, linux-tools-generic, linux-tools-$(uname -r).
• Install benchmarking and system utilities: stress-ng, htop, sysbench, ffmpeg, powercap-utils, ipmitool.
• Install Docker Compose.
• Install LuaSocket.
• Install Python libraries listed in requirements.txt (e.g., psutil, numpy, pandas, tensorflow, scikit-learn, etc.).

Troubleshooting dependencies.sh:

• add-apt-repository: command not found: Install software-properties-common: sudo apt install software-properties-common.
• Unable to locate package linux-tools-$(uname -r): Ensure your kernel headers are installed. Try sudo apt install linux-headers-$(uname -r). If the issue persists, your kernel version might not have pre-built tools available. You may need to compile them or use a different kernel.
• E: Unable to locate package ...: Double-check your internet connection and ensure your apt sources are up-to-date (sudo apt update). Some packages might have slightly different names on older Ubuntu versions.

Step 3: Configure Cgroups

PowerTrace heavily relies on cgroups for resource management and isolation. You need to initialize and configure them.

Critical Warning: These steps require sudo and will modify system-level cgroup configurations. It's highly recommended to reboot your system after these steps to ensure cgroup settings are applied correctly and to avoid unexpected behavior.

3.1: Initialize Cgroups

Run the cgroup_init.sh script to create the necessary cgroup hierarchies and enable controllers.

sudo ./scripts/cgroup_init.sh

This script will:

• Ensure cpuset and cpu controllers are enabled at the root cgroup level.
• Create /sys/fs/cgroup/user and /sys/fs/cgroup/critical cgroups.
• Set cpu.max to unlimited for both user and critical cgroups.
• Assign all available CPUs to both user and critical cgroups.

Troubleshooting cgroup_init.sh:

• rmdir: failed to remove '...': Device or resource busy: This is normal if the cgroups already exist and are in use. The script will attempt to recreate them.
• echo: write error: Operation not permitted: This usually means the cgroup controller is not enabled or the cgroup filesystem is not mounted correctly as cgroup v2. Re-verify your cgroup v2 setup (see Prerequisites).

3.2: Set up Cgroup Control (for multi-socket systems)

If your system has multiple CPU sockets (at least two), you can use cgroup_ctl_setup.sh to assign specific CPU cores from different sockets to the user and critical cgroups. This is crucial for isolating workloads and preventing interference.

sudo ./scripts/cgroup_ctl_setup.sh

This script will:

• Auto-detect CPU sockets and assign CPUs from the first socket to the critical cgroup and CPUs from the second socket to the user cgroup.
• Output the CPU assignments for verification.

Note: If you do not have at least two CPU sockets, this script will exit with an error message. The cgroup_init.sh script provides a basic cgroup setup that will still allow PowerTrace to function, but without socket-level isolation.

Troubleshooting cgroup_ctl_setup.sh:

• At least 2 CPU sockets are required.: This means your system does not have enough physical CPU sockets for this script's intended purpose. You can still proceed with PowerTrace, but without this specific CPU isolation.

Step 4: Reboot Your System

After configuring cgroups, it is essential to reboot your system to ensure all changes are properly applied and the cgroup hierarchy is stable.

sudo reboot

Usage

PowerTrace provides various scripts for running benchmarks, collecting data, and analyzing power.

Running Benchmarks

The run-bench-*.sh scripts in the root directory are the primary entry points for executing benchmarks and power experiments.

• run-bench.sh: General script for running benchmarks.
• run-bench-attr.sh: For running benchmarks with power attribution.
• run-bench-cap.sh: For running benchmarks with power capping.
• run-bench-consolidated.sh: For consolidated power measurements.
• run-bench-initial.sh: For initial benchmark runs.
• run-bench-once.sh: For single benchmark runs.
• run-bench-predict-single.sh: For single prediction runs.
• run-bench-qos-powercap.sh: For QoS-aware power capping benchmarks.

You can explore these scripts to understand their specific functionalities and parameters. It's recommended to open them in a text editor and read any comments or usage instructions within the scripts themselves.

Modules Overview

• attribution/: Contains scripts for attributing power consumption to different system components or processes.
• benchmark-suites/: Houses various benchmark suites like DeathStarBench, filebench, ML-training, and redis.
• control/: Includes scripts and configurations for power capping and control mechanisms.
• data/: Likely stores raw or processed data collected during experiments.
• estimation/: Contains scripts for estimating CPU and total system power.
• MLs/: May contain machine learning models or related scripts for power/performance prediction.
• perf-aware/: Scripts related to performance-aware power management.
• predxnd/: Tools for power and performance prediction, including cgroup monitoring.
• results/: Various subdirectories for storing and parsing experimental results.
• scripts/: Utility scripts for cgroup management, data collection, and result parsing.
• test/: Contains various test workloads and scripts.
• train_test/: Scripts for training and testing power models.

Example Workflow (General)

A typical workflow might involve:

1. Selecting a Benchmark: Choose a benchmark from benchmark-suites/ or test/.
2. Running the Benchmark: Use an appropriate run-bench-*.sh script, potentially modifying it to suit your experimental needs (e.g., setting power caps, specifying attribution methods).
3. Collecting Data: The run-bench-*.sh scripts often integrate with tools in estimation/ or predxnd/ to collect power and performance metrics.
4. Analyzing Results: Use the parse.py or other parsing scripts in the results/ directories to process the collected data and generate reports.

For detailed usage of specific scripts, it is recommended to examine their contents and any inline comments.

Contributing

(Add information on how to contribute if this is an open-source project)

License

(Add license information)