Measure energy consumption around sbt commands.
The workflow this plugin supports is calling energyMonitorPreSample
before you invoke some sbt commands, then calling energyMonitorPostSample
afterward in order to obtain an EnergyDiff
that you can track over time.
In order to use this plugin, you'll need to provide a jar containing jRAPL
as a dependency in your project/
folder -- you can see an example in the scripted tests in this repo. You can use the jar in this repo's lib/
directory, which was copied from Wojciech Mazur's fork of the Energy-Languages
repo.
This plugin requires sbt 1.0.0+. It provides four tasks: energyMonitorPreSample
, energyMonitorPostSample
, energyMonitorPostSampleHttp
, and energyMonitorPostSampleGitHub
and appropriate settings for configuring them.
This task takes an initial snapshot of energy usage and writes the results to the value configured in energyMonitorOutputFile
.
If energyMonitorDisableSampling
is true, this task will do nothing.
This task reads the initial sample from the path configured in energyMonitorOutputFile
, takes a new snapshot,
and prints calculated energy usage to the console.
If energyMonitorDisableSampling
is true, this task will do nothing.
This task works like energyMonitorPostSample
, but instead of printing results to the console, sends
them to an HTTP server with some metadata. The server should accept POSTs to the configured URL, with an HTTP body like:
{
"joules": 23,
"seconds": 8,
"organization": "47degrees",
"repository": "sbt-energymonitor",
"branch": "abcde",
"run": 8,
"recordedAt": "2022-05-05T10:15:00Z"
}
Its behavior is controlled by three settings: energyMonitorPersistenceServerUrl
, and energyMonitorPersistenceTag
.
However, if energyMonitorDisableSampling
is true
, this task will do nothing.
You can see an example usage of this task in the scripted test included in this repository under the energy-monitor-plugin/src/sbt-test/http-store
directory.
This setting determines where the task should send the information about energy consumption. Its default value is http://localhost:8080
, which will be correct if you're experimenting locally and using the demo server provided in the energyMonitorPersistenceApp
module. You should not use a local server for real testing though, since the server's energy consumption will also show up in the power consumed by the CPU / memory during your energy tests.
This setting determines whether some arbitrary string will be included with the energy consumption sample. You might want to do this if there's some significant change that you think should explain differences in energy, for instance, "upgrade to cats-effect 3", or "refine types to shrink validation in core business logic," or something similar. You can put whatever information you want in the tag, or nothing at all. Its default value is None
.
This task works like energyMonitorPostSample
, but instead of printing results to the console, sends them to a pull request comment.
It was written with the aim of posting energy consumption in every GitHub Actions CI run, but that's
not going to work with the
current infrastructure backing GitHub Actions. You can still do this locally though if you're testing a PR and
want to add a comment documenting energy usage. To do so, you'll need to export four environment variables in
the shell session where you're running sbt
:
GITHUB_REPOSITORY
: this value is theorg-name/repo-name
repository that you're working in, e.g.47degrees/sbt-energymonitor
GITHUB_TOKEN
: this value is a GitHub personal access tokenGITHUB_RUN_ATTEMPT
: this value is an integer representing which CI run statistics correspond to. You can set this to any integer value, though tying it to the commit sequence in a pull request might make sense.GITHUB_REF
: this is a reference likerefs/pull/1234/merge
, where1234
is the PR number you want to add the comment to.
You can read more about any of these environment variables in the default environment variables GitHub Actions documentation.
You can see example comments in this sandbox repo for learning droste
.
If energyMonitorDisableSampling
is true, this task will do nothing.
This setting controls whether any of the sampling tasks do anything. If it's set to true
, none of them will do any work, and they'll
log a message that they're not doing any work because sampling is disabled.
This setting contains the path that the energyMonitorPreSample
task should write to and that the energyMonitorPostSample
and energyMonitorPostSampleGitHub
tasks should read from. It defaults to target/energy-sample
, so if you're ignoring
target/
directories in git
, it shouldn't annoy you. However, if you'd like to write the sample somewhere else, you
have that power.
Run test
for regular unit tests.
Run scripted
for sbt script tests.