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 very simple third-party cargo subcommand to execute a custom command

cargo-x A very simple third-party cargo subcommand to execute a custom command Usage install cargo-x cargo install cargo-x or upgrade cargo install -

git-cliff can generate changelog files from the Git history by utilizing conventional commits as well as regex-powered custom parsers.⛰️
git-cliff can generate changelog files from the Git history by utilizing conventional commits as well as regex-powered custom parsers.⛰️

git-cliff can generate changelog files from the Git history by utilizing conventional commits as well as regex-powered custom parsers. The changelog template can be customized with a configuration file to match the desired format.

Reference implementation of a decentralized exchange for custom instruments, risk, and fees

Dexterity What is Dexterity At a high level, Dexterity is a smart contract (or collection of smart contracts) that allow for the creation of a decentr

An efficient pictures manager based on custom tags and file system organization.

PicturesManager An efficient pictures manager based on custom tags and file system organization. Developed with Tauri (web app) with a Rust backend an

🐢 Atuin replaces your existing shell history with a SQLite database, and records additional context for your commands
🐢 Atuin replaces your existing shell history with a SQLite database, and records additional context for your commands

Atuin replaces your existing shell history with a SQLite database, and records additional context for your commands. Additionally, it provides optional and fully encrypted synchronisation of your history between machines, via an Atuin server.

Save image from your clipboard 📋 as an image file directly from your command line! 🔥

Clpy 📋 Save copied image from clipboard as an image file directly from your command line! Note It works only on windows as of now. I'll be adding sup

FastSSH is a TUI that allows you to quickly connect to your services by navigating through your SSH config.
FastSSH is a TUI that allows you to quickly connect to your services by navigating through your SSH config.

Connect quickly to your services 🚀 FastSSH is a TUI that allows you to quickly connect to your services by navigating through your SSH config. Instal

Deadliner helps you keep track of the time left for your deadline by dynamically updating the wallpaper of your desktop with the time left.
Deadliner helps you keep track of the time left for your deadline by dynamically updating the wallpaper of your desktop with the time left.

Deadliner Watch the YouTube video What's Deadliner? Deadliner is a cross-platform desktop application for setting deadline for a project and keeping t

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

Amrit Ghimire 109 Dec 16, 2022
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

Benjamin Vaisvil 1.6k Jan 4, 2023
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

Aaron Friel 8 Dec 8, 2022
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

null 10 Dec 30, 2022
Black-box integration tests for your REST API using the Rust and its test framework

restest Black-box integration test for REST APIs in Rust. This crate provides the [assert_api] macro that allows to declaratively test, given a certai

IOmentum 10 Nov 23, 2022
create and test the style and formatting of text in your terminal applications

description: create and test the style and formatting of text in your terminal applications docs: https://docs.rs/termstyle termstyle is a library tha

Rett Berg 18 Jul 3, 2021
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:

Daniel P. Clark 5 Dec 28, 2021
Easy access of struct fields in strings using different/custom pre/postfix: "Hello, {field}" in rust

Easy access to struct fields in strings ?? add strung to the dependencies in the Cargo.toml: [dependencies] strung = "0.1.3" ?? use/import everything

Dekirisu 2 Sep 19, 2022