You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
If you want to monitor the energy consumption of your process we have some
4
-
ready-to-use tools
3
+
In this tutorial, we will guide you through the first steps to get started with PowerAPI.
4
+
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.
5
+
A few things are required before we start:
5
6
6
-
???+ info "Source and Destination"
7
-
In order to use any Formula, you need to run a Source and a Destination. The former is used by a Sensor to store metrics. The later allows the Formula to make available the estimations. For starting, you can use [MongoDB](https://hub.docker.com/_/mongo) as Source and [InfluxDB:2.X](https://hub.docker.com/_/influxdb) as Destination by installing them as Docker containers.
8
-
For more details about Sources and Destinations please check this [section](reference/database/sources_destinations.md).
7
+
- A compatible processor (you can see the compatible CPU architecture [here](./reference/sensors/hwpc-sensor.md#)), and you can look on the following pages to find your CPU architecture:
8
+
* For [Intel Processor](https://en.wikipedia.org/wiki/List_of_Intel_processors)
9
+
* For [Intel Xeon Processor](https://en.wikipedia.org/wiki/List_of_Intel_Xeon_processors)
10
+
* For [AMD Processor](https://en.wikipedia.org/wiki/Table_of_AMD_processors)
11
+
- A python installation ready
12
+
- Docker & Docker-Compose ready (refer to [this official documentation](https://docs.docker.com/engine/install/) and the [post-install steps](https://docs.docker.com/engine/install/linux-postinstall/) if needed !)
13
+
- Root access
14
+
- Optional : [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to proceed by cloning the repository
9
15
16
+
## Which components to get a complete stack
10
17
11
-
<!---
12
-
## **RAPL Formula**
18
+
If you wish to get started as soon as possible, the archive below will allow you to deploy the following elements:
13
19
14
-
!!! note ""
15
-
for monitoring the energy consumption of your device
20
+
1. A MongoDB instance to store the [Sensor](./reference/sensors/hwpc-sensor.md)
21
+
Reports
16
22
17
-
RAPL Formula is made for tracking the energy consumption of your machine.
18
-
To install RAPL Formula on a baremetal server or a PC run [the following
19
-
script](script/rapl_install.sh) in a Terminal.
23
+
3. An [HWPC-Sensor](./reference/sensors/hwpc-sensor.md) that outputs its
24
+
[HWPC Reports](./reference/reports/reports.md#hwpc-reports) in a MongoDB Database,
25
+
within the HWPC Report Collection
20
26
21
-
The script explains what it will do and then pauses before it does it.
27
+
4. A [SmartWatts](./reference/formulas/smartwatts.md) that streams the
28
+
[HWPC Reports](./reference/reports/reports.md#hwpc-reports) from the MongoDB
29
+
Database Collection, processes it and outputs its
30
+
[Power Reports](./reference/reports/reports.md#power-reports) as CSV files for a
31
+
quick glimpse
22
32
23
-
Please notice that you need a **Linux distribution** in order to use the HWPC Sensor installed by the script as
24
-
well as a **comptible Intel** (Sandy Bridge and newer) or **AMD Processor** (Zen). **Power/ARM/RISCV are not supported** architectures. HWPC Sensor will **not work on a Virtual Machine**. However, you can install the Formula by hand in a Virtual Machine if need it.
25
-
-->
33
+
## Preparation
26
34
27
-
## **SmartWatts Formula**
35
+
You can either download the archive by cloning the repository or using wget.
28
36
29
-
!!! note ""
30
-
for monitoring the power consumption of your process
cd powerapi-ng.github.io/docs/script/getting-started
41
+
```
31
42
32
-
Smartwatts is made for tracking the power consumption of processes on a
33
-
machine.
34
-
To install Smartwatts on a baremetal server or a PC run [the following
35
-
script](script/smartwatts_install.sh) in a Terminal. Please notice that you will need [pip](https://pip.pypa.io/en/stable/installation/) or [docker](https://docs.docker.com/engine/install/) in order to use the Formula.
43
+
=== "wget"
44
+
```
45
+
wget -c https://raw.githubusercontent.com/powerapi-ng/powerapi-ng.github.io/refs/heads/master/docs/script/getting_started.tar.gz -O - | tar -xz
46
+
cd getting_started
47
+
```
36
48
37
-
The script explains what it will do and then pauses before it does it.
49
+
At this stage, you will have all the essential files to begin. Let's go through each element in detail.
50
+
### Archive content
38
51
39
-
Please notice that you need a **Linux distribution** in order to use the HWPC Sensor installed by the script as
40
-
well as a **comptible Intel** (Sandy Bridge and newer) or **AMD Processor** (Zen). You also need [docker](https://docs.docker.com/engine/install/). **Power/ARM/RISCV are not supported** architectures. HWPC Sensor will **not work on a Virtual Machine**. However, you can install the Formula by hand in a Virtual Machine if need it.
52
+
```sh
53
+
getting_started/
54
+
|--csv/
55
+
|--formula/
56
+
|----smartwatts-mongodb-csv.json
57
+
|--sensor/
58
+
|----hwpc-mongodb.json
59
+
|--start.sh
60
+
|--start.py
61
+
|--stop.sh
62
+
|--pretty_print.py
63
+
|--docker-compose.yaml
64
+
|--.env
65
+
```
41
66
67
+
#### HWPC-Sensor and SmartWatts Configuration
42
68
69
+
As described in the [HWPC-Sensor Documentation](./reference/sensors/hwpc-sensor.md#global-parameters) and in the [SmartWatts Documentation](./reference/formulas/smartwatts.md#global-parameters),
70
+
several parameters can be set, both globally and for specific Groups monitored for the sensor or the formula.
43
71
44
-
#### CGroups
45
-
If you need to monitor a process or a group of process via SmartWatts by using HWPC Sensor **version 1.2 or older**, you can follow this [tutorial](reference/cgroup/cgroup.md). Please notice that **cgroup V1** is required **only**for HWPC Sensor **version 1.2 or older**. If you need to enable this `cgroup` version please follow this [tutorial](reference/cgroup/cgroup_v1_activation.md).
72
+
The provided docker-compose.yaml file uses configuration files and the **.env** to set those parameters.
73
+
You can find examples of both those configuration files in the archive under the **formula** and **sensor**directories.
46
74
47
-
<!---
48
-
## **Jouleit**
49
75
50
-
!!! note ""
51
-
for mesuring the energy consumption of a program
76
+
## Turn the key
52
77
53
-
Jouleit is made for tracking the energy consumption of a program.
54
-
Jouleit need `gawk` to run.
55
-
You can get the script from the [github repository](https://github.com/powerapi-ng/jouleit)
56
-
Start jouleit by using `./jouleit.sh cmd`.
57
-
-->
78
+
Once all set, you shall be able to initiate the stack with:
79
+
80
+
```sh
81
+
python3 start.py
82
+
```
83
+
84
+
After the 2 minutes of monitoring, you will be able to see the result inside the **csv** directory.
85
+
If you have trouble understanding the output, you can read the [Power Report documentation](./reference/reports/reports.md#power-reports).
86
+
87
+
!!! info "Quick results overview"
88
+
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.
@@ -30,7 +34,7 @@ The list of accepted parameters are:
30
34
|`db` (`database` for `HWPCSensor`) | string |`d` (`D` for `HWPCSensor`) | N/A | Yes | The name of your database |
31
35
|`collection`| string |`c` (`C` for `HWPCSensor`) | N/A | Yes | The name of the collection inside `db`|
32
36
|`name`| string |`n`|`"puller_mongodb"` (Source), `pusher_mongodb` (Destination)| No | The related puller/pusher name. This parameter is not used by `HWPCSensor`|
33
-
|`model`| string |`m`|`"HWPCReport"` (Source), `PowerReport` (Destination) | No | The Report type stored by the database |
37
+
|`model`| string |`m`|`"HWPC Report"` (Source), `Power Report` (Destination) | No | The Report type stored by the database |
34
38
35
39
### JSON File Excerpt
36
40
@@ -64,7 +68,7 @@ The list of accepted parameters are:
64
68
|`org`| string |`g`| N/A | Yes | The name of the organization associated to the bucket |
65
69
|`tags`| string |`t`| N/A | No | List of metadata keys of the report separated by `,` that will be kept. `sensor` and `target` are always kept as report metadata |
66
70
|`name`| string |`n`|`"pusher_influxdb2"`| No | The related pusher name |
67
-
|`model`| string |`m`|`"PowerReport"`| No | The Report type stored by the database |
71
+
|`model`| string |`m`|`"Power Report"`| No | The Report type stored by the database |
68
72
69
73
70
74
InfluxDB2 can only be used as a Destination.
@@ -75,7 +79,7 @@ Below you find an example of configuration excerpt for this kind of Destination.
75
79
76
80
```json
77
81
{
78
-
"model": "PowerReport",
82
+
"model": "Power Report",
79
83
"type": "influxdb2",
80
84
"uri": "http://127.0.0.1",
81
85
"port": 8086,
@@ -100,7 +104,7 @@ The list of accepted parameters are:
100
104
|`files`(Source)| string |`f`| Empty list | No | The list of input CSV files with the format file1,file2,file3... |
101
105
|`directory` (Destination and `HWPCSensor`)| string |`d` (`U` for `HWPCSensor`) | Current directory | No |The directory where output CSV files will be written |
102
106
|`name`| string |`n`|`"puller_csv"` (Source), `"pusher_csv"` (Destination)| No | The related puller/pusher name. This parameter is not used by `HWPCSensor`|
103
-
|`model`| string |`m`|`"HWPCReport"` (Source), `"PowerReport"` (Destination) | No | The Report type stored in CSV files. This parameter is not used by `HWPCSensor`|
107
+
|`model`| string |`m`|`"HWPC Report"` (Source), `"Power Report"` (Destination) | No | The Report type stored in CSV files. This parameter is not used by `HWPCSensor`|
104
108
105
109
### JSON File Excerpt
106
110
@@ -128,7 +132,7 @@ The list of accepted parameters are:
128
132
|`port`| int |`P`| N/A | Yes | The port of communication |
129
133
|`uri`/ `host`| int |`U`| N/A | Yes | The IP address of the machine running the socket |
130
134
|`name`| string |`n`|`"puller_socket"`| No | The related puller name |
131
-
|`model`| string |`m`|`"HWPCReport"`| No | The Report type managed by the socket |
135
+
|`model`| string |`m`|`"HWPC Report"`| No | The Report type managed by the socket |
132
136
133
137
134
138
### JSON File Excerpt
@@ -158,7 +162,7 @@ The list of accepted parameters are:
Copy file name to clipboardexpand all lines: docs/reference/formulas/configuration_files.md
+3-6
Original file line number
Diff line number
Diff line change
@@ -11,14 +11,11 @@ The table below shows basic parameters.
11
11
|`verbose`|`bool` (flag) |`v`|`NOTSET`| Verbose or quiet mode |
12
12
|`stream`|`bool` (flag) |`s`|`False`| Real time or post-mortem mode |
13
13
|`sensor-report-sampling-interval`|`int`| N/A |`1000`| The time in milliseconds between two reports (`stream` = `True`) |
14
-
|`input`|`string`(Source)| N/A | N/A |Source used as input. More information about Sources and their related parameters can be found [here](../database/sources_destinations.md)|
15
-
|`output`|`string`(Destination)| N/A | N/A |Destination used as output. More information about Destinations and their related parameters can be found [here](../database/sources_destinations.md)|
14
+
|`input`|`string`| N/A | N/A |SmartWatts input, shall match an existing Sensor output and contain HPWCReports. See [here](./smartwatts.md#smartwatts-inputs)|
15
+
|`output`|`string`| N/A | N/A |SmartWatts output to store Power Report. See [here](./smartwatts.md#smartwatts-outputs)|
16
16
|`pre-processor`|`string`| N/A | N/A | Pre-Processor to modify reports generated by a sensor. More information about Processors and their related parameters can be found [here](../processors/processors.md)|
17
17
|`post-processor`|`string`| N/A | N/A | Post-Processor to modify reports generated by a formula. More information about Processors and their related parameters can be found [here](../processors/processors.md)|
0 commit comments