getting_started.md

Getting started

In this tutorial, we will guide you through the first steps to get started with PowerAPI. The objective is to get a quick view of the capabilities of PowerAPI, by monitoring a process and getting a quick glimpse at the energy consumption. A few things are required before we start:

• A compatible processor (you can see the compatible CPU architecture here), and you can look on the following pages to find your CPU architecture:
  • For Intel Processor
  • For Intel Xeon Processor
  • For AMD Processor
• A python installation ready
• Docker & Docker-Compose ready (refer to this official documentation and the post-install steps if needed !)
• Root access
• Optional : Git to proceed by cloning the repository

Which components to get a complete stack

If you wish to get started as soon as possible, the archive below will allow you to deploy the following elements:

1. A MongoDB instance to store the Sensor Reports

2. An HWPC-Sensor that outputs its HWPC Reports in a MongoDB Database, within the HWPC Report Collection

3. A SmartWatts that streams the HWPC Reports from the MongoDB Database Collection, processes it and outputs its Power Reports as CSV files for a quick glimpse

Preparation

You can either download the archive by cloning the repository or using wget.

=== "git" sh git clone https://github.com/powerapi-ng/powerapi-ng.github.io.git cd powerapi-ng.github.io/docs/script/getting-started

=== "wget" wget -c https://raw.githubusercontent.com/powerapi-ng/powerapi-ng.github.io/refs/heads/master/docs/script/getting_started.tar.gz -O - | tar -xz cd getting_started

At this stage, you will have all the essential files to begin. Let's go through each element in detail.

Archive content

getting_started/
 |--csv/
 |--formula/
 |----smartwatts-mongodb-csv.json
 |--sensor/
 |----hwpc-mongodb.json
 |--start.sh
 |--start.py
 |--stop.sh
 |--pretty_print.py
 |--docker-compose.yaml
 |--.env

HWPC-Sensor and SmartWatts Configuration

As described in the HWPC-Sensor Documentation and in the SmartWatts Documentation, several parameters can be set, both globally and for specific Groups monitored for the sensor or the formula.

The provided docker-compose.yaml file uses configuration files and the .env to set those parameters. You can find examples of both those configuration files in the archive under the formula and sensor directories.

Turn the key

Once all set, you shall be able to initiate the stack with:

python3 start.py

After the 2 minutes of monitoring, you will be able to see the result inside the csv directory. If you have trouble understanding the output, you can read the Power Report documentation.

!!! info "Quick results overview" Only in the context of this testing archive, after the monitoring, you can use the following command to get a pretty print of the result directly inside the terminal.

```sh
python3 pretty_print.py
```