Coppers is a custom test harnass for Rust that measures the energy usage of your test suite.

Overview

Coppers

Coppers is a test harness for Rust that can measure the evolution of power consumptions of a Rust program between different versions with the help of Intel RAPL.

Requirements

  • Rust nightly
  • Linux
  • A fairly recent Intel cpu, 2013 or later (why?)

This test harness targets the Rust nightly toolchain because it relies on unstable features of the Rust compiler.

  • First, make sure that you have installed the nightly toolchain with rustup install nightly
  • Then, enable the nightly toolchain on this repository with rustup override set nightly

Installation

To enable the custom test runner in your project, add this to your Cargo.toml file.

[dev-dependencies]
coppers = "0.1"

Add the following two lines to your crate root (most likely lib.rs or main.rs)

#![feature(custom_test_frameworks)]
#![test_runner(coppers::runner)]

Usage

Using Coppers on your project can be done with cargo test. This will run your unit tests and report on the energy usage of each test. A report in JSON format will be generated in target/coppers_results-[seconds since epoch].json. This file contains machine-readable output of the tests.

Before you interpret the results, please consider the accuracy of the results and how you can improve it. See our section about accuracy for more information.

Visualization

Coppers optionally supports visual output of the results. The visualizations can help with determining the change of energy consumption of your tests over time. To enable visualizations, enable the future flag in your Cargo.toml file.

[dev-dependencies]
coppers = { version = "0.1", features = ["visualization"]}

This feature is disabled by default, because it relies on certain Python packages. You can install the packages defined in this repository's requirements.txt file with

pip install -r requirements.txt

Example plot

This example graph is generated by enabling the visualization feature. In this line plot, the test represented by the green line becomes more energy efficient over time.

Stability guarantees

We have developed this project with rust version 1.61.0-nightly (ee915c34e 2022-03-28). A newer nightly version might change some of the compiler features we rely on, such as:

We cannot guarantee that this project works with more recent nightly versions.

Limitations

Our implementation comes with some limitations.

Intel RAPL

Right now, this only works on Intel-based Linux machines with Intel RAPL via the Power Capping Framework. It could be extended for support on non-Intel and non-Linux machines, but this was outside the scope of our project.

Accuracy

Measuring the energy consumption on the level of a single test might be very precise, but not very accurate. Our current method measures the energy consumption of the entire system, which includes and/or is influenced by things like

  • The operating system
  • Your hardware configuration
  • Other programs that are running at the same time
  • Power management settings
  • External devices such as USB drives, external disks, displays etc.
  • Energy consumption of your internet adapter
  • Brightness of your screen
  • Temperature of your hardware
  • Temperature of your real world environment
  • Data in your cache (higher cache hit rate means that less energy is spend on retrieving data from memory)

For the most accurate, reliable and reproducible results, you could take certain precautions when running the tests. The goal of the precautions is to limit the influence of other factors. Precautions can include:

  • Use the exact same hardware when you want to compare results with each other
  • Close all applications that are not strictly necessary
  • Turn of all notifications
  • Only the minimum amount of hardware necessary should be connected, so avoid USB devices, external displays etc. if possible.
  • Kill unnecessary services running in the background
  • Switch off your network if it is not needed
    • If you do need internet, prefer a cable connection over wireless
  • Disable auto brightness and set your brightness level as low as possible
  • Repeating the tests multiple times

Completeness

This project is far from complete, but it is what we could achieve within the short timespan of the course we are following. It could be extended and improved with things like

  • Reporting the correct error code when a test fails
  • Run on more platforms beside Intel based Linux machines
  • Shuffle the tests around during execution, to avoid that tests are more energy efficient because of a high cache hit rate
  • Make certain things more customizable, like the amount of times a test should be repeated or whether to ignore certain tests from the reporting

Troubleshooting

Intel RAPL sensors are not enabled

You might get an error like The location /sys/devices/virtual/powercap/intel-rapl/intel-rapl:0 is unreachable. If you have an Intel based machine, then you can enable on the Intel RAPL sensors with modprobe in the following way modprobe intel_rapl_common for Linux kernels of >= 5. Do you have a kernel version of < 5, then use modprobe intel_rapl. Unfortunatly, Coppers does not support non-Intel based machines at this time.

Running the tests causes Insufficient permissions

If you run cargo test, you might get an

thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: "Insufficient permissions to read from /sys/devices/virtual/powercap/intel-rapl/intel-rapl:0/energy_uj. You might want to retry as root."' 

error. This can be solved in one of two ways:

  1. Either run the tests again with root permissions, with sudo -E cargo test.
  2. Or temporarily add read permissions to /sys/devices/virtual/powercap/intel-rapl/intel-rapl:0/energy_uj by running
    1. sudo chmod o+r /sys/devices/virtual/powercap/intel-rapl/intel-rapl:0/energy_uj
    2. cargo test
    3. sudo chmod o-r /sys/devices/virtual/powercap/intel-rapl/intel-rapl:0/energy_uj

ModuleNotFoundError

If you run with the visualization feature enabled, then you also need to install the required Python packages. This can be done by installing the packages defined in this repositories requirements.txt with pip install -r requirements.txt.

About

This project was done in the context of the 2022 edition of Sustainable Software Engineering course at Delft University of Technology. We chose the name "Coppers" because our project relates to both green software and Rust, and oxidized copper has a green-ish color.

License

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

You might also like...
A small script in rust to get the cpu usage in %'s with a gradient color for the text
A small script in rust to get the cpu usage in %'s with a gradient color for the text

cpu_usage-polybar A small script in rust to get the cpu usage in %'s with a gradient color for the text To get it to work on your PC you will have to

The application that can be used for personal usage to manage jira from terminal.

Jira Terminal This application can be used for personal usage to manage jira from terminal. Installation This application can be used in multiple plat

Zenith - sort of like top or htop but with zoom-able charts, CPU, GPU, network, and disk usage
Zenith - sort of like top or htop but with zoom-able charts, CPU, GPU, network, and disk usage

Zenith - sort of like top or htop but with zoom-able charts, CPU, GPU, network, and disk usage

Memory usage monitor for process trees

gotta-watch-em-all Executes a process with given arguments and monitors, logs when memory usage grows to a new peak. Example: cargo run -- cargo -- bu

Calculate a player's skill level using Elo, DWZ, Ingo, TrueSkill, Glicko and Glicko-2 algorithms known from their usage in chess and online games.

skillratings Skillratings allows you to calculate the player's skill instantly in 1v1 matches or after tournaments/rating periods with a list of resul

App to collect ram/cpu usage from OS and show it in pretty graphs
App to collect ram/cpu usage from OS and show it in pretty graphs

System info collector This is simple app to collect data about system cpu and memory usage over time. After collecting results into csv file, html fil

Scan the symbols of all ELF binaries in all Arch Linux packages for usage of malloc_usable_size

Scan the symbols of all ELF binaries in all Arch Linux packages for usage of malloc_usable_size (-D_FORTIFY_SOURCE=3 compatibility)

Cross-platform GameMaker extension for getting system information and resource usage
Cross-platform GameMaker extension for getting system information and resource usage

GM Sysinfo Cross-platform GameMaker extension for getting system information and resource usage Table of Contents Table of Contents Examples Display m

Rust implementation of custom numeric base conversion.

base_custom Use any characters as your own numeric base and convert to and from decimal. This can be taken advantage of in various ways: Mathematics:

Comments
  • Floor the result values

    Floor the result values

    In the generated report, values of the most and least energy consuming tests do have decimal values. I think this is not neccesary and should therefore be floored to the nearest integer. Making it easier to read and distinguish the size of the values displayed. See example image below: afbeelding

    opened by JeffreyBouman 0
Releases(v0.1.1)
  • v0.1.1(Apr 5, 2022)

    What's Changed

    • Round values everywhere in the report by @KatjaSchmahl in https://github.com/ThijsRay/coppers/pull/11
    • Fix generation of barplot by not reusing the dataframe by @KatjaSchmahl in https://github.com/ThijsRay/coppers/pull/12

    Full Changelog: https://github.com/ThijsRay/coppers/compare/v0.1.0...v0.1.1

    Source code(tar.gz)
    Source code(zip)
  • v0.1.0(Mar 30, 2022)

Owner
Thijs Raymakers
Thijs Raymakers
dua (-> Disk Usage Analyzer) is a tool to conveniently learn about the usage of disk space of a given directory

dua (-> Disk Usage Analyzer) is a tool to conveniently learn about the usage of disk space of a given directory. It's parallel by default and will max

Sebastian Thiel 1.8k Jan 2, 2023
auto-epp-rs is a program that manages the energy performance preferences (EPP) of your AMD CPU using the AMD-Pstate driver.

auto-epp-rs is a program that manages the energy performance preferences (EPP) of your AMD CPU using the AMD-Pstate driver. It adjusts the EPP settings based on whether your system is running on AC power or battery power, helping optimize power consumption and performance. This project is a rewrite of the original Python version jothi-prasath/auto-epp in Rust, aiming to improve memory efficiency and overall performance.

Taufik Hidayat 3 Nov 3, 2023
ABQ is a universal test runner that runs test suites in parallel. It’s the best tool for splitting test suites into parallel jobs locally or on CI

?? abq.build   ?? @rwx_research   ?? discord   ?? documentation ABQ is a universal test runner that runs test suites in parallel. It’s the best tool f

RWX 13 Apr 7, 2023
The hacker's BLE (bluetooth low energy) browser terminal app

Blendr is a terminal UI app for browsing BLE (Bluetooth Low Energy) devices. It allows you to inspect, search, connect, and analyze data coming from B

Dmitriy Kovalenko 120 Jul 4, 2023
🦚 A web-app pentesting suite written in rust .

Kanha - A web-app pentesting suite written in rust ?? Installation ⦾ Subcommands ⦾ Contribute Kanha is a tool that can help you perform, a variety of

Nabeen Tiwaree 79 Sep 19, 2023
Holo is a suite of routing protocols designed to support high-scale and automation-driven networks.

Holo is a suite of routing protocols designed to support high-scale and automation-driven networks. For a description of what a routing protocol is, p

Renato Westphal 42 Apr 16, 2023
JA4+ is a suite of network fingerprinting standards

JA4+ Network Fingerprinting JA4+ is a suite of network fingerprinting methods that are easy to use and easy to share. These methods are both human and

FoxIO 94 Oct 5, 2023
A CLI tool which can help you automatically kill process of your choice. Useful for freeing up memory and CPU usage!

Quickiller There are always programs such as chrome that keep eating up your resources even when closed! The only way to prevent this is to kill all o

Codingsquirrel 1 Dec 8, 2021
Gives custom drugs to your terminal 💊

Linux on drugs ?? Gives custom drugs to your terminal ?? Output random colors really fast Installation ?? Arch Linux Linux on drugs is in the AUR yay

Skwal 3 Sep 10, 2022
Blazingly fast Rust CLI app to sync data from a folder of excel workbooks into generated c# code for unity usage

Extensions supported ( .xls, .xlsx, .xlsm, .xlsb, .xla, .xlam, .ods ) Speed Test Image shows the results of 5000defs synced from 2 workbooks and 5 she

null 4 Feb 16, 2023