Merge pull request #18 from powerapi-ng/revert-15-7_doc/nld_proofread

Revert "7_doc/nld proofread"

Author: roda82

README.md

@@ -2,23 +2,3 @@
 PowerAPI website use [MKDocs](https://www.mkdocs.org/). 
 
 You can push your changes on `master` branch to deploy them on the website. 
-
-## Local development  
-
-When redacting changes for this documentation, you may want to visualize the 
-output the way it will be presented in the final website once compiled.  
-
-One way to do so is to:  
-
-1. Install the necessary packages : mkdocs, mkdocs-material, mkdocs-material-extensions  
-This can be done with: `pip install mkdocs mkdocs-material mkdocs-material-extensions`  
-
-2. Have a local copy of this repository (taking care of *checkout-ing* the right ref)  
-
-3. From the CLI, have this particular repository as PWD  
-
-4. Use mkdocs in order to serve locally (default on http://localhost:8000)  
-This can be done with: `mkdocs serve -o`  
-
-5. Check the URL it serves to, targets will be rebuild on modifications in the 
-current directory or in any nested elements (use -W to add paths to be considered for hot reloading)  

docs/assets/images/reference/sensors/PowerAPI_HWPCSensorOverview.drawio

@@ -1,92 +1,57 @@
 # 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: 
+If you want to monitor the energy consumption of your process we have some
+ready-to-use tools
 
-- 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:  
-    * For [Intel Processor](https://en.wikipedia.org/wiki/List_of_Intel_processors)  
-    * For [Intel Xeon Processor](https://en.wikipedia.org/wiki/List_of_Intel_Xeon_processors)  
-    * For [AMD Processor](https://en.wikipedia.org/wiki/Table_of_AMD_processors)  
-- A python installation ready
-- 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 !)
-- Root access
-- Optional : [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) to proceed by cloning the repository
+???+ info "Source and Destination"
+    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.
+    For more details about Sources and Destinations please check this [section](reference/database/sources_destinations.md).
 
-## 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:  
+<!---
+## **RAPL Formula**
 
-1. A MongoDB instance to store the [Sensor](./reference/sensors/hwpc-sensor.md)
-Reports
+!!! note ""
+    for monitoring the energy consumption of your device
 
-3. An [HWPC-Sensor](./reference/sensors/hwpc-sensor.md) that outputs its 
-[HWPC Reports](./reference/reports/reports.md#hwpc-reports) in a MongoDB Database, 
-within the HWPC Report Collection
+RAPL Formula is made for tracking the energy consumption of your machine.
+To install RAPL Formula on a baremetal server or a PC run [the following
+script](script/rapl_install.sh) in a Terminal.
 
-4. A [SmartWatts](./reference/formulas/smartwatts.md) that streams the 
-[HWPC Reports](./reference/reports/reports.md#hwpc-reports) from the MongoDB 
-Database Collection, processes it and outputs its 
-[Power Reports](./reference/reports/reports.md#power-reports) as CSV files for a 
-quick glimpse 
+The script explains what it will do and then pauses before it does it.
 
-## Preparation
+Please notice that you need a **Linux distribution** in order to use the HWPC Sensor installed by the script as
+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.
+-->
 
-You can either download the archive by cloning the repository or using wget.
+## **SmartWatts Formula**
 
-=== "git"
-    ```sh 
-    git clone https://github.com/powerapi-ng/powerapi-ng.github.io.git
-    cd powerapi-ng.github.io/docs/script/getting-started
-    ```
+!!! note ""
+    for monitoring the power consumption of your process
 
-=== "wget"
-    ```
-    wget -c https://github.com/raw/powerapi-ng/powerapi-ng.github.io/refs/heads/master/docs/script/getting_started.tar.gz -O - | tar -xz
-    cd getting_started
-    ```
+Smartwatts is made for tracking the power consumption of processes on a
+machine.
+To install Smartwatts on a baremetal server or a PC run [the following
+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.
 
-At this stage, you will have all the essential files to begin. Let's go through each element in detail.
-### Archive content
+The script explains what it will do and then pauses before it does it.
 
-```sh
-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
-```
+Please notice that you need a **Linux distribution** in order to use the HWPC Sensor installed by the script as
+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.
 
-#### HWPC-Sensor and SmartWatts Configuration
 
-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), 
-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.
+#### CGroups
+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).    
 
+<!---
+## **Jouleit**
 
-## Turn the key 
+!!! note ""
+    for mesuring the energy consumption of a program
 
-Once all set, you shall be able to initiate the stack with:  
-
-```sh
-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](./reference/reports/reports.md#power-reports).
-
-!!! 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
-    ```
+Jouleit is made for tracking the energy consumption of a program.
+Jouleit need `gawk` to run.
+You can get the script from the [github repository](https://github.com/powerapi-ng/jouleit)
+Start jouleit by using `./jouleit.sh cmd`.
+-->

docs/assets/images/reference/sensors/PowerAPI_HWPCSensorOverview.drawio.svg

@@ -1,23 +1,19 @@
-# Storage Options
+# Sources and Destinations
 
-Different storage options are available to serve different purpose both for [Sensors](../overview.md#Sensor) and [Formulas](../overview.md#Formula).  
+A PowerAPI Formula uses Sources and Destinations in order to retrieve metrics and store estimations.
 
-Storage is needed to save reports produced by each components.  
-- Sensors store their usage reports  
-- Formulas retrieve usage reports and store energy consumption reports  
-- Visualization tools or individuals need to access reports for analysis  
+For each Source/Destination the parameters to specify are different. For each one of them,
+its parameters are specified in following sections.
 
 ## Summary
-
-The following table defines the existing storage options for Sensors usage reports :  
-
-| Name      | CLI `ouput` parameter value  | JSON `type` tag parameter value|
-| ------------ | --------------------------------------| -------------------------------------------|
-| MongoDB | mongodb | mongodb |
-| CSV |  csv | csv |
-| Socket | socket | socket    |
-| File Database | filedb | filedb |
-
+| Name     | Source   | Destination  | CLI `input`/`ouput` parameter value                                      | JSON `type` tag parameter value                             |
+| ------------- | -----  | ------------- | -------------                                      | ------------------------------------    |
+| MongoDB | Yes  | Yes | mongodb                                      | mongodb    |
+| InfluxDB2 | No  | Yes | influxdb2                                      | influxdb2    |
+| CSV | Yes  | Yes | csv                                      | csv    |
+| Socket | Yes  | No | socket                                      | socket    |
+| File Database | Yes  | Yes | filedb                                      | filedb    |
+| Prometheus | No  | Yes | prometheus                                      | prometheus    |
 
 ## MongoDB
 
@@ -34,7 +30,7 @@ The list of accepted parameters are:
 |`db` (`database` for `HWPCSensor`)           | string | `d` (`D` for `HWPCSensor`)            | N/A | Yes                                                       | The name of your database               |
 |`collection`   | string | `c` (`C` for `HWPCSensor`)          | N/A | Yes                                                       | The name of the collection inside `db`  |
 |`name`         | string | `n`           | `"puller_mongodb"` (Source), `pusher_mongodb` (Destination)| No | The related puller/pusher name. This parameter is not used by `HWPCSensor`                 |
-|`model`        | string | `m`           | `"HWPC Report"` (Source), `Power Report` (Destination) | No         | The Report type stored by the database  |
+|`model`        | string | `m`           | `"HWPCReport"` (Source), `PowerReport` (Destination) | No         | The Report type stored by the database  |
 
 ### JSON File Excerpt
 
@@ -68,7 +64,7 @@ The list of accepted parameters are:
 |`org`          | string | `g`           | N/A           | Yes | The name of the organization associated to the bucket               |
 |`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                           |
 |`name`         | string | `n`           | `"pusher_influxdb2"` | No                                    | The related pusher name                 |
-|`model`        | string | `m`           | `"Power Report"`  | No | The Report type stored by the database  |
+|`model`        | string | `m`           | `"PowerReport"`  | No | The Report type stored by the database  |
 
 
 InfluxDB2 can only be used as a Destination.
@@ -79,7 +75,7 @@ Below you find an example of configuration excerpt for this kind of Destination.
 
 ```json
 {
-  "model": "Power Report",
+  "model": "PowerReport",
   "type": "influxdb2",
   "uri": "http://127.0.0.1",
   "port": 8086,
@@ -104,7 +100,7 @@ The list of accepted parameters are:
 |`files`(Source)| string  | `f`           | Empty list           | No | The list of input CSV files with the format file1,file2,file3...              |
 |`directory` (Destination and `HWPCSensor`)| string         |`d` (`U` for `HWPCSensor`)          | Current directory           | No |The directory where output CSV files will be written          |
 |`name`         | string | `n`           | `"puller_csv"` (Source), `"pusher_csv"` (Destination)| No | The related puller/pusher name. This parameter is not used by `HWPCSensor`                 |
-|`model`        | string | `m`           | `"HWPC Report"` (Source), `"Power Report"` (Destination)   | No | The Report type stored in CSV files. This parameter is not used by `HWPCSensor`     |
+|`model`        | string | `m`           | `"HWPCReport"` (Source), `"PowerReport"` (Destination)   | No | The Report type stored in CSV files. This parameter is not used by `HWPCSensor`     |
 
 ### JSON File Excerpt
 
@@ -132,7 +128,7 @@ The list of accepted parameters are:
 |`port`         | int    | `P`           | N/A | Yes                                               | The port of communication               |
 |`uri`/ `host`         | int    | `U`           | N/A | Yes                                               | The IP address of the machine running the socket               |
 |`name`         | string | `n`           | `"puller_socket"`| No | The related puller name  |
-|`model`        | string | `m`           | `"HWPC Report"` | No | The Report type managed by the socket |
+|`model`        | string | `m`           | `"HWPCReport"` | No | The Report type managed by the socket |
 
 
 ### JSON File Excerpt
@@ -162,7 +158,7 @@ The list of accepted parameters are:
 | ------------- | -----  | ------------- | -------------| ----------                                        | ------------------------------------    |
 |`filename`     | int    | `f`           | N/A                                                | Yes | The name of the file                    |
 |`name`         | string | `n`           | `"pusher_filedb"` | No | The related pusher name |
-|`model`        | string | `m`           | `"HWPC Report"` (Source) `"Power Report"` (Destination)| No  | The Report type stored in the file      |
+|`model`        | string | `m`           | `"HWPCReport"` (Source) `"PowerReport"` (Destination)| No  | The Report type stored in the file      |
 
 ### JSON File Excerpt
 
@@ -192,7 +188,7 @@ The list of accepted parameters are:
 |`metric-name`  | string | `M`           | N/A | Yes                                              | The exposed metric name                    |
 |`metric-description`  | string | `d`    | `"energy consumption"` | No                             | The exposed metric description                    |
 |`name`         | string | `n`           | `"pusher_prom"` | No | The related pusher name                 |
-|`model`        | string | `m`           | `"Power Report"` | No | The Report type exposed by Prometheus       |
+|`model`        | string | `m`           | `"PowerReport"` | No | The Report type exposed by Prometheus       |
 
 
 Prometheus can only be used as a Destination that monitors reports but they will be not stored by this service.

docs/getting_started.md

@@ -11,11 +11,14 @@ The table below shows basic parameters.
 | `verbose`                            | `bool` (flag)               | `v`           |`NOTSET`                              | Verbose or quiet mode                |
 | `stream`                             | `bool` (flag)  | `s`           |`False`                               | Real time or post-mortem mode         |
 | `sensor-report-sampling-interval`    | `int`         | N/A           | `1000`                                 | The time in milliseconds between two reports (`stream` = `True`) |
-| `input`     | `string`      | N/A | N/A     | SmartWatts input, shall match an existing Sensor output and contain HPWCReports. See [here](./smartwatts.md#smartwatts-inputs) |
-| `output`     | `string` | N/A | N/A            | SmartWatts output to store Power Report. See [here](./smartwatts.md#smartwatts-outputs) |
+| `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)|
+| `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)|
 | `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) |
 | `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) |
 
+???+ tip "Sources and Destinations' values"
+    - Sources: `mongodb`, `csv`, `socket`, `filedb`
+    - Destinations: `mongodb`, `influxedb`, `influxedb2`, `csv`, `socket`, `filedb`, `prom`
 
 ???+ tip "Processors' values"
     - Pre-Processors: `k8s`, `libvirt`
@@ -49,5 +52,5 @@ PowerAPI Formulas use `json` files. These files follow the next template:
   $formula_parameters
 }
 ```
-???+ info "input and output' `json` tags"
+???+ info "Sources and Destinations' `json` tags"
     More information related to `json` tags for each Source/Destination can be found [here](../database/sources_destinations.md)

docs/reference/database/sources_destinations.md

@@ -7,7 +7,7 @@ The RAPL Formula is designed to mesure power consumption of domains (CPU or RAM)
 in real time.
 
 The RAPL Formula takes HWPC Report with RAPL event for each domains. It then
-returns the mesured power in a Power Report for each domain.
+returns the mesured power in a PowerReport for each domain.
 This Formula does not perform any other computation as its goal is only to track
 global power consumption in a more readable way than raw RAPL.
 
@@ -29,7 +29,7 @@ You can use [the following script](../script/rapl_install.sh) to install RAPL Fo
 
 ## Usage
 
-For running the RAPL Formula you need: a Source and a Destination, a Sensor that provides `HWPC Reports` and a configuration.
+For running the RAPL Formula you need: a Source and a Destination, a Sensor that provides `HWPCReports` and a configuration.
 
 ### Source and Destination
 
@@ -42,7 +42,7 @@ docker run -d --name mongo_source_destination -p 27017:27017 mongo
 ```
 
 ### Sensor
-[HWPC Sensor](../sensors/hwpc-sensor.md) is used in order to get `HWPC Reports`. Start by installing the HWPC Sensor (see
+[HWPC Sensor](../sensors/hwpc-sensor.md) is used in order to get `HWPCReports`. Start by installing the HWPC Sensor (see
 [here](../sensors/hwpc-sensor.md#installation)) and start it (see
 [here](../sensors/hwpc-sensor.md#usage)).
 
@@ -69,7 +69,7 @@ Below an example is provided by using MongoDB as Source and Destination.
   "stream": true,
   "input": {
     "puller": {
-      "model": "HWPC Report",
+      "model": "HWPCReport",
       "type": "mongodb",
       "uri": "mongodb://127.0.0.1",
       "db": "test",
@@ -79,7 +79,7 @@ Below an example is provided by using MongoDB as Source and Destination.
   "output": {
     "pusher_power": {
       "type": "mongodb",
-      "model": "Power Report",
+      "model": "PowerReport",
       "type": "mongodb",
       "uri": "mongodb://127.0.0.1",
       "db": "test",
@@ -124,8 +124,8 @@ the installation you use:
      docker run -t \
      --net=host \
      powerapi/powerapi --verbose \
-     --input mongodb --model HWPC Report --uri mongodb://127.0.0.1 --db test --collection prep \
-     --output mongodb --model Power Report --uri mongodb://127.0.0.1 --db test --collection results \
+     --input mongodb --model HWPCReport --uri mongodb://127.0.0.1 --db test --collection prep \
+     --output mongodb --model PowerReport --uri mongodb://127.0.0.1 --db test --collection results \
      --disable-dram-formula \
      --sensor-report-sampling-interval 500
      ```
@@ -134,14 +134,14 @@ the installation you use:
 
     ```sh
     python -m powerapi --verbose \
-    --input mongodb --model HWPC Report --uri mongodb://127.0.0.1 --db test --collection prep \
-    --output mongodb --model Power Report --uri mongodb://127.0.0.1 --db test --collection results \
+    --input mongodb --model HWPCReport --uri mongodb://127.0.0.1 --db test --collection prep \
+    --output mongodb --model PowerReport --uri mongodb://127.0.0.1 --db test --collection results \
     --disable-dram-formula \
     --sensor-report-sampling-interval 500
     ```
 
 ???+ info "Estimations' Storage"
-    Your `Power Reports` will be stored on MongoDB.
+    Your `PowerReports` will be stored on MongoDB.
 
 ???+ tip "Using shortcuts for parameters' names"
     You use `-` instead of `--`.

docs/reference/formulas/configuration_files.md

@@ -39,7 +39,7 @@ You can use [the following script](../script/smartwatts_install.sh) to install S
 
 ## Usage
 
-For running the SmartWatts Formula you need: a Source and a Destination, a Sensor that provides `HWPC Reports` and a configuration.
+For running the SmartWatts Formula you need: a Source and a Destination, a Sensor that provides `HWPCReports` and a configuration.
 
 ### Source and Destination
 For running SmartWatts we are using MongoDB as Source and InfluxDB as Destination as dockers containers.
@@ -57,7 +57,7 @@ docker run -d --name influx_dest -p 8086:8086 influxdb:1.8
 
 
 ### Sensor
-[HWPC Sensor](../sensors/hwpc-sensor.md) is used in order to get `HWPC Reports`. Start by installing the HWPC Sensor (see
+[HWPC Sensor](../sensors/hwpc-sensor.md) is used in order to get `HWPCReports`. Start by installing the HWPC Sensor (see
 [here](../sensors/hwpc-sensor.md#installation)) and start it (see
 [here](../sensors/hwpc-sensor.md#usage)).
 
@@ -91,7 +91,7 @@ Below an example is provided by using MongoDB as Source and InfluxDB as Destinat
   "stream": true,
   "input": {
     "puller": {
-      "model": "HWPC Report",
+      "model": "HWPCReport",
       "type": "mongodb",
       "uri": "mongodb://127.0.0.1",
       "db": "test",
@@ -148,8 +148,8 @@ the installation you used:
      docker run -t \
      --net=host \
      powerapi/smartwatts-formula --verbose \
-     --input mongodb --model HWPC Report --uri mongodb://127.0.0.1 --db test --collection prep \
-     --output influxdb --model Power Report --uri 127.0.0.1 --port 8086 --db test_result \
+     --input mongodb --model HWPCReport --uri mongodb://127.0.0.1 --db test --collection prep \
+     --output influxdb --model PowerReport --uri 127.0.0.1 --port 8086 --db test_result \
      --cpu-base-freq 1900 \
      --cpu-error-threshold 2.0 \
      --disable-dram-formula \
@@ -161,8 +161,8 @@ the installation you used:
     ```sh
     python -m smartwatts \
     --verbose \
-    --input mongodb --model HWPC Report --uri mongodb://127.0.0.1 --db test --collection prep \
-    --output influxdb --model Power Report --uri 127.0.0.1 --port 8086 --db test_result \
+    --input mongodb --model HWPCReport --uri mongodb://127.0.0.1 --db test --collection prep \
+    --output influxdb --model PowerReport --uri 127.0.0.1 --port 8086 --db test_result \
     --cpu-base-freq 1900 \
     --cpu-error-threshold 2.0 \
     --disable-dram-formula \
@@ -172,7 +172,7 @@ the installation you used:
 
 
 ???+ info "Estimations' Storage"
-    Your `Power Reports` will be stored on InfluxDB. You can watch them in a grafana by using the [following tutorial](../grafana/grafana.md).
+    Your `PowerReports` will be stored on InfluxDB. You can watch them in a grafana by using the [following tutorial](../grafana/grafana.md).
 
 ???+ tip "Using shortcuts for parameters' names"
     You use `-` instead of `--`.

docs/reference/formulas/rapl.md

@@ -2,27 +2,20 @@
 
 Here it is explained how to visualize the power estimation computed by a Formula on a Grafana dashboard to obtain this kind of visualisation:
 
-![Visualization by process](../../assets/images/reference/grafana/viz_by_process.png){ width="1000px"}
-
-<!--img
+<img
 src="https://powerapi.org/assets/images/reference/grafana/viz_by_process.png"
-alt="viz_by_process" width="1000px"-->
-
-This screenshot shows the visualisation of power consumption of a `Firefox` web browser and tools used for monitoring (MongoDB, InfluxDB, Sensor, Formula)
+alt="viz_by_process" width="1000px">
 
-In this tutorial, we describe how to connect a Formula to a Grafana instance by using InfluxDB 2.X as output for Power Report.  
-Then, we will see how to configure Grafana to visualize the power estimation computed by the Formula.  
+This screenshot shows the visualisation of power consumption of a Web browser and tools used for monitoring (Source, Destination, Sensor, Formula)
 
-This tutorial assumes that you know how launch a Formula and a Sensor to compute power estimation and that you have an InfluxDB 2.X running on your local machine.  
+In this tutorial, we describe how to connect a Formula to a Grafana instance by using InfluxDB 2.X as Destination.
+Then, we will see how to configure Grafana to visualize the power estimation computed by the Formula.
 
-The InfluxDB 2.X instances listen on port `8086` by default.
+This tutorial assumes that you know how launch a Formula and a Sensor to compute power estimation and that you have an InfluxDB 2.X and a Grafana instances running on your local machine.
+The InfluxDB 2.X instance listen on port `8086`.
 
 ## Setup Grafana
 
-The default installation is done through Docker container.  
-The different images can be found on the [Docker Hub](https://hub.docker.com/r/grafana/grafana)  
-
-Here is an example to deploy the latest image version available.
 ```sh
 docker run -d -p 3000:3000 grafana/grafana
 ```
@@ -31,40 +24,49 @@ After the launch, Grafana will be available at http://localhost:3000. On the sig
 
 ## Connect Grafana to the InfluxDB 2.X instance
 
-Follow [this documentation](https://grafana.com/docs/grafana/latest/datasources/influxdb/#configure-the-data-source) in order to add InfluxDB as a DataSource.  
-Be carefull to use the documentation matching your Grafana version.  
+Connect to your Grafana instance and go to the `"Data sources"`` section (in the configuration part of the side bar).
 
+<img
+src="https://powerapi.org/assets/images/reference/grafana/grafana_home.png"
+alt="grafana_home" width="300px">
 
-## Visualize the power consumption on a dashboard in real-time
+Click on the `"Add new data source"` button and select `"InfluxDB"`. Enter:   
+
+1. A data source *Name* (here we choose "InfluxDB-2"),
+2. A *Query Language*, i.e., `InfluxQL`
+3. An instance *URL* (`http://localhost:8086`)
+4. A *Custom HTTP Header* called `Authorization` with Value `Token <mytoken>`, where `<mytoken>` is the token provided by InfluxDB 2.X for your organization.
+5. A *Database* name, (here we choose `power_consumption`) that is the `db` value of your destination defined in your formula configuration.
+
+Then click on the `"Save & test"` button. *User* and *Password* are not required as we use a token for authentification.  
 
-1. Go to the `"Dashboard"` section on the side bar and select on `New > New dashboard`
-2. Then click on `+ Add visualisation`
-3. Then select the previously added datasource as data source
 
-![Add Dashboard](../../assets/images/reference/grafana/add_dashboard.png){ width="1000px"}
+<img
+src="https://powerapi.org/assets/images/reference/grafana/add_db.png"
+alt="add_db" width="400px">
 
-<!--img
+## Visualize the power consumption on a dashboard in real-time
+
+Go to the `"Dashboard"` section on the side bar and select on `New > New dashboard`. Then click on `+ Add visualisation` Then select `influxdb-2` as data source.
+
+<img
 src="https://powerapi.org/assets/images/reference/grafana/add_dashboard.png"
-alt="add_dashboard" width="1000px"-->
+alt="add_dashboard" width="1000px">
 
-4. Click on the query edition button (the one with a pencil on it) and write the following query on the `Query` field to request the power estimations from the InfluxDB 2.X measurement:
+Click on the query edition button (the one with a pencil on it) and write the following query on the `Query` field to request the power estimations from the InfluxDB 2.X measurement:
 
 ```sql
 SELECT power FROM "power_consumption" GROUP BY target
 ```
 
 Then write `$tag_target` on the `ALIAS BY` field to label each graph with the target name
 
-![Add query by process](../../assets/images/reference/grafana/add_query_by_process.png){ width="1000px"}
-
-<!--img
+<img
 src="https://powerapi.org/assets/images/reference/grafana/add_query_by_process.png"
-alt="add_query_by_process" width="600px"-->
+alt="add_query_by_process" width="600px">
 
 To display the power consumption in real time, you can update the range of the visualisation to `last 5 minutes` and the `refresh dashboard` parameter to `5s`. This parameter are on the top-right corner of the UI.
 
-![Change the refresh interval](../../assets/images/reference/grafana/refresh.png){ width="1000px"}
-
-<!--img
+<img
 src="https://powerapi.org/assets/images/reference/grafana/refresh.png"
-alt="refresh" width="600px"-->
+alt="refresh" width="600px">

docs/reference/formulas/smartwatts.md

@@ -1,71 +1,63 @@
 # PowerAPI Overview
 
-This project aims to offer a range of tools to promote greener computing. The focus is on creating software-defined PowerMeters to measure the power consumption of various programs.  
-At the heart of this initiative is the [PowerAPI](https://github.com/powerapi-ng/powerapi) toolkit, which facilitates the development of these PowerMeters.
+The goal of this project is to provide a set of tools to go forward a greener
+computing.
+The idea is to provide software-defined PowerMeters to mesure the power
+consumption of programs.
+The core of this project is the [PowerAPI](https://github.com/powerapi-ng/powerapi) toolkit for building
+such PowerMeters.
+
+
 
 ## Software PowerMeters
 
-A software PowerMeter is an application built using PowerAPI components, designed to measure the power consumption of software running on a single machine or across a cluster of machines.
+A software PowerMeter is an application built with the PowerAPI components that can
+measure the power consumption of software running on a single machine or on a
+cluster of machine.
 
-The diagram below illustrates the overall architecture of a PowerMeter within the PowerAPI framework.
+The Figure below depicts the global architecture of a software PowerMeter in PowerAPI.
 
 ![PowerAPI Architecture Overview](../assets/images/reference/overview/global-architecture.jpg){ width="1000px"}
 
-A PowerMeter consists of two essential components:   
 
-- a [Sensor](#Sensor), which collects system usage metrics and generates usage reports.  
-- a [Formula](#Formula), which applies a computational model to the usage reports, producing power consumption data (in watts).
+<!--img
+src="assets/images/intro/global-architecture.png"
+alt="PowerMeter Architecture" width="1000px"-->
 
-Additionally, [Preprocessors](./overview.md#Preprocessors) can be utilized to modify usage reports before they are processed by the Formula.
+A PowerMeter has two components, a Sensor and a Formula, used to
+produce an estimation of the power consumption of a monitored software.
 
 ## Sensor
 
-The Sensor is a standalone software tool that gathers basic data related to the power usage of the software it monitors.
-
-It collects this data by querying the hardware on the same machine where the monitored software runs. The Sensor needs to operate in parallel to the monitored software for the entire duration of its execution.
+The Sensor is an independent software that collects raw data (metrics) correlated with the power consumption of the
+monitored software.
 
-The raw data collected is then stored as usage Reports in various formats, either locally or remotely. These formats include CSV, MongoDB, FileDB, and UNIX sockets, among others.
+Data are collected by querying the hardware’s machine that hosts the monitored
+software. The sensor must be executed on the same machine as the monitored
+software. The data are collected throughout the duration of the software. For
+this reason, the sensor must operate in parallel.
 
-### Existing Sensors
+Collected raw data are stored in an external Source to make the data available to
+the Formula. This Source may be hosted on an other machine.
 
-| Sensor | Documentation | Repository | Description | Supported |
-| :---------------: |----------------------|--------------------------|----------------|---------------|
-| HWPC            | [HWPC Documentation](./sensors/hwpc-sensor.md) | [Github](https://github.com/powerapi-ng/hwpc-sensor) | Hardware Performance Counters monitoring agent for containers |  :material-check: Supported |
+### Usage
 
+Currently, PowerAPI proposes one Sensor: [HWPC](sensors/hwpc-sensor.md).
+Refer to the Sensor documentation to know how to use it.
 
 ## Formula
 
-A Formula is a computational module that estimates the power consumption of the monitored software using the data collected by the Sensor.
-
-There are two modes in which a Formula can operate:
-
-- **Stream mode**: In this mode, the Formula processes data from the Sensor as it is generated, providing real-time insights  
-
-- **Post-mortem mode**: In this mode, the Formula analyzes data that has already been collected by the Sensor during a previous monitoring phase  
-
-### Existing Formulas
-
-| Formula | Documentation | Repository | Description | Supported |
-| :---------------: |----------------------|--------------------------|----------------|---------------|
-| SmartWatts            | [SmartWatts Documentation](./formulas/smatwatts.md) | [Github](https://github.com/powerapi-ng/smartwatts-formula) | HSmartWatts is a formula for a self-adaptive software-defined power meter based on the PowerAPI framework.  |  :material-check: Supported |
-
-## Processors
-
-Processors allow for the customized filtering and modification of Reports. While optional, they offer additional flexibility, but Software PowerMeters can still function without them.
-
-The diagram below shows where Processors are integrated into the architecture of a Software PowerMeter.
-
-![Processor integration in the processing pipeline](../assets/images/reference/processors/processors.jpg)
+A Formula is a computational module that computes an estimation of the power
+consumption of monitored software from the data collected by the sensor.
 
-### Preprocessors
+A Formula has two working modes:
 
-Preprocessors are positioned between the [Sensor](./overview.md#Sensor) and the [Formula](./overview.md#Formula).  
-Their role is to pre-process usage reports before the power consumption estimations are computed.
+- `stream` mode where the Formula read the data from the Sensor as they are
+  produced (in realtime).
 
-#### Existing Preprocessors
+- `post-mortem` mode where the Formula analyses the data already collected by the Sensor in a past monitoring phase.
 
-| Preprocessor | Documentation | Repository | Description | Supported |
-| :---------------: |----------------------|--------------------------|----------------|---------------|
-| k8sPreprocessor            | [k8sPreprocessor Documentation](./processors/processors.md#k8spreprocessor) | [Github](https://github.com/powerapi-ng/powerapi/tree/master/src/powerapi/processor/pre/k8s) | Add K8S Specific metadata to corresponding Reports |  :material-check: Supported |
-| libvirt | [libvirtPreprocessor Documentation](.processors/processors.md#libvirt) | [Github](https://github.com/powerapi-ng/powerapi/tree/master/src/powerapi/processor/pre/libvirt) | Replace `libvirt ID` in Reports with `Open Stack UUID` | :material-check: Supported |
+### Usage
 
+Currently, there is one Formula: [SmartWatts](formulas/smartwatts.md).
+Refer to the Formula documentation to know how to use it.

docs/reference/formulas/smartwatts.md.save

@@ -3,8 +3,8 @@
 Processors enable customized filtering and/or modifications of `Reports`.
 There are two kinds of processors:
 
-- `PreProcessors`: They are located between the `Puller` and the `Dispatcher`. They are supposed to pre-process the `HWPC Reports` before computing estimations.
-- `PostProcessors`: They are located between, the `Formula` and the `Pusher`. They process `Power Reports` before storing them on the output storage option.
+- `PreProcessors`: They are located between the `Puller` and the `Dispatcher`. They are supposed to pre-process the `HWPCReports` before computing estimations.
+- `PostProcessors`: They are located between, the `Formula` and the `Pusher`. They process `PowerReports` before storing them on the `Destination`.
 
 Figure below depicts where are they introduced in the architecture of a Software `PowerMeters`.
 
@@ -60,8 +60,8 @@ As notice, a `PreProcessor` is defined inside the `pre-processor` group. In this
      docker run -t \
      --net=host \
      powerapi/smartwatts-formula --verbose \
-     --input mongodb --model HWPC Report --uri mongodb://127.0.0.1 --db test --collection prep \
-     --output influxdb --model Power Report --uri 127.0.0.1 --port 8086 --db test_result \
+     --input mongodb --model HWPCReport --uri mongodb://127.0.0.1 --db test --collection prep \
+     --output influxdb --model PowerReport --uri 127.0.0.1 --port 8086 --db test_result \
      {==--pre-processor k8s --name p1 --api-mode local --puller puller==} \
      --cpu-base-freq 1900 \
      --cpu-error-threshold 2.0 \
@@ -74,8 +74,8 @@ As notice, a `PreProcessor` is defined inside the `pre-processor` group. In this
     ```sh
     python -m smartwatts \
     --verbose \
-    --input mongodb --model HWPC Report --uri mongodb://127.0.0.1 --db test --collection prep \
-    --output influxdb --model Power Report --uri 127.0.0.1 --port 8086 --db test_result \
+    --input mongodb --model HWPCReport --uri mongodb://127.0.0.1 --db test --collection prep \
+    --output influxdb --model PowerReport --uri 127.0.0.1 --port 8086 --db test_result \
     {==--pre-processor k8s --name p1 --api-mode local --puller puller==} \
     --cpu-base-freq 1900 \
     --cpu-error-threshold 2.0 \
@@ -96,12 +96,12 @@ As notice, a `PreProcessor` is defined inside the `pre-processor` group. In this
     -e POWERAPI_CPU_ERROR_THRESHOLD=2.0 \
     -e POWERAPI_DISABLE_DRAM_FORMULA=true \
     -e POWERAPI_SENSOR_REPORTS_FREQUENCY=1000 \
-    -e POWERAPI_INPUT_PULLER_MODEL=HWPC Report \
+    -e POWERAPI_INPUT_PULLER_MODEL=HWPCReport \
     -e POWERAPI_INPUT_PULLER_TYPE=mongodb \
     -e POWERAPI_INPUT_PULLER_URI=mongodb://127.0.0.1 \
     -e POWERAPI_INPUT_PULLER_DB=test \
     -e POWERAPI_INPUT_PULLER_COLLECTION=prep \
-    -e POWERAPI_OUTPUT_PUSHER_POWER_MODEL=Power Report \
+    -e POWERAPI_OUTPUT_PUSHER_POWER_MODEL=PowerReport \
     -e POWERAPI_OUTPUT_PUSHER_POWER_TYPE=influxdb \
     -e POWERAPI_OUTPUT_PUSHER_POWER_URI=127.0.0.1 \
     -e POWERAPI_OUTPUT_PUSHER_POWER_PORT=8086 \
@@ -121,12 +121,12 @@ As notice, a `PreProcessor` is defined inside the `pre-processor` group. In this
     export POWERAPI_CPU_ERROR_THRESHOLD=2.0
     export POWERAPI_DISABLE_DRAM_FORMULA=true
     export POWERAPI_SENSOR_REPORTS_FREQUENCY=1000
-    export POWERAPI_INPUT_PULLER_MODEL=HWPC Report
+    export POWERAPI_INPUT_PULLER_MODEL=HWPCReport
     export POWERAPI_INPUT_PULLER_TYPE=mongodb
     export POWERAPI_INPUT_PULLER_URI=mongodb://127.0.0.1
     export POWERAPI_INPUT_PULLER_DB=test
     export POWERAPI_INPUT_PULLER_COLLECTION=prep
-    export POWERAPI_OUTPUT_PUSHER_POWER_MODEL=Power Report
+    export POWERAPI_OUTPUT_PUSHER_POWER_MODEL=PowerReport
     export POWERAPI_OUTPUT_PUSHER_POWER_TYPE=influxdb
     export POWERAPI_OUTPUT_PUSHER_POWER_URI=127.0.0.1
     export POWERAPI_OUTPUT_PUSHER_POWER_PORT=8086
@@ -140,15 +140,15 @@ As notice, a `PreProcessor` is defined inside the `pre-processor` group. In this
 
 ### Example of Usage with SmartWatts Formula via a Configuration File
 
-Below an example is provided by using MongoDB as input and InfluxDB as output.
+Below an example is provided by using MongoDB as Source and InfluxDB as Destination.
 
 ```json
 {
   "verbose": true,
   "stream": true,
   "input": {
     "puller": {
-      "model": "HWPC Report",
+      "model": "HWPCReport",
       "type": "mongodb",
       "uri": "mongodb://127.0.0.1",
       "db": "test",

docs/reference/grafana/grafana.md

@@ -2,56 +2,59 @@
 
 PowerAPI toolkit is modular, which means any sensor can be plugged to any monitoring
 tool as long as the needed information is provided.
-We fixed the way of encoding the information. Those encoding are called `Reports`.  
+We fixed the way of encoding the information. Those encoding are called reports.
 
 A report type specify the `json` fields that has to be provided to pass information of
 a certain kind. All reports types have a common basis:
 
 
-- `timestamp`: at the [format](https://en.wikipedia.org/wiki/ISO_8601) "YYYY-MM-DDThh\:mm\:ss\.sss". The timestamp indicates when the data was collected, not when it was processed.  
+- `timestamp`: at the format "year-month-dayThour:minutes:seconds". The
+  timestamp reflects the time at which the information correspond, not the
+  time the information was computed.
+  For example if a power consumption of a CPU is measured at time `t` and used to
+  determine the power consumption of a `cgroup` in a `PowerReport`, this report
+  has timestamp `t`.
 
-- `target`: The target refers to the entity being measured. For example, if a report contains data related to a specific program, domain, or other entity, the target identifies that subject. In this context, it corresponds to the cgroup name.
+- `target`: the target is the subject of the measure. For example if
+    you produce a report that contain information relative to a program, domain,
+    etc., the target refers to it. It corresponds to the `cgroup` name.
 
 - `sensor`: it's a name field that is used to identify the reports produced by or computed thanks to a sensor.  
 
-Therefore, a report shall match the following description: 
+  Therefore, a report have the following format:
 
-```json
-{  
+  ```json
   "timestamp":$timestamp,
   "target":$target,
   "sensor":$sensor,
   $report_specific_fields
-}
-```
-
-A valid JSON-Schema to can be found [here](https://raw.githubusercontent.com/powerapi-ng/powerapi-ng.github.io/refs/heads/master/docs/reference/reports/basis-reports.schema.json).
 
+  ```
 In the following sections we specify the `$report_specific_fields` for each type of report.
 
 ## HWPC Reports
 
-A `HWPC Report` is used to report performance counters and RAPL.
+A `HWPCReport` is used to report performance counters and RAPL.
 Its specific fields are the following:
 
 - `groups`: a list of subreport that can be of three kind, `rapl`, `core` and
   `msr`.
 
   Each group is represented in the same way:
 
-```json
+  ```json
   {
     $type: {
       $core_number : {
         $socket_number : {
-          Each counter name and their measured value for the type/core_number/socket_number considered triplet
+          List of counter and their value
         }
       }
     }
   }
-```
+  ```
 
-Below you can find an example of `HWPC Report`:
+Below you can find an example of `HWPCReport`:
 
 ```json
 {
@@ -120,12 +123,12 @@ Below you can find an example of `HWPC Report`:
 
 ## Power Reports
 
-A `Power Report` is used to transfer information about power consumption estimations.
+A `PowerReport` is used to transfer information about power consumption estimations.
 Its specific fields are the following:
 
 - `power`: a power value in Watts.
 
-Below you find an exemple of `Power Report`:
+Below you find an exemple of `PowerReport`:
 
 ```json
 {

docs/reference/overview.md

@@ -17,7 +17,7 @@ echo "
   "stream": true,
   "input": {
     "puller": {
-      "model": "HWPC Report",
+      "model": "HWPCReport",
       "type": "socket",
       "uri": "127.0.0.1",
       "port": 8080,

docs/reference/processors/processors.md

@@ -84,9 +84,9 @@ nav:
   - Formulas:
     #- RAPL: reference/formulas/rapl.md
     - SmartWatts: reference/formulas/smartwatts.md
-    #- Configuration Files: reference/formulas/configuration_files.md
-# - Sources/Destinations:
-# - Description: reference/database/sources_destinations.md
+    - Configuration Files: reference/formulas/configuration_files.md
+  - Sources/Destinations:
+    - Description: reference/database/sources_destinations.md
   - Processors:
     - Description: reference/processors/processors.md
   - Reports: