Skip to content

Commit b4079f6

Browse files
author
Kellian Leveque
committed
docs(reference): Update hwpc-sensor.md
- Add architecture generation next to their names - Wrap some parts in a `details` to shorten the page length - Change some collapsible blocks for non-collapsible blocks - Fix lines highlights of CSV output - Center infos in tables
1 parent 451f504 commit b4079f6

File tree

1 file changed

+71
-69
lines changed

1 file changed

+71
-69
lines changed

‎docs/reference/sensors/hwpc-sensor.md‎

Lines changed: 71 additions & 69 deletions
Original file line numberDiff line numberDiff line change
@@ -3,27 +3,30 @@
33
HardWare Performance Counter (HWPC) Sensor is a tool that monitors the Intel CPU
44
performance counter and the power consumption of CPU.
55

6-
The figure below depicts how Sensor works in general :
6+
The figure below depicts how Sensor works in general :
7+
8+
79
![HWPC Sensor Overview](../../assets/images/reference/sensors/PowerAPI_HWPCSensorOverview.drawio.svg){ width="1000px"}
810

911
HWPC Sensor uses the RAPL (Running Average Power Limit) technology to monitor CPU
1012
power consumption. The following table gives a glimpse of RAPL support regarding
1113
most common architectures:
1214

13-
???+ info "HWPC Sensor PreRequisites"
15+
!!! tip "CPU architecture"
1416
`lscpu` will give you the necessary information about your CPU Architecture
1517

1618
| Architecture | RAPL Supported |
1719
|--------------|----------------|
18-
| Intel Tiger Lake | :material-close: Not Supported |
19-
| Intel Alder Lake | :material-close: Not Supported |
20-
| Intel Raptor Lake | :material-close: Not Supported |
20+
| Intel Tiger Lake (11th Gen) | :material-close: Not Supported |
21+
| Intel Alder Lake (12th Gen) | :material-close: Not Supported |
22+
| Intel Raptor Lake (13th & 14th Gen) | :material-close: Not Supported |
2123
| Power / ARM / RISCV | :material-close: Not Supported |
2224
| AMD Zen (1, 2, 3, 4) | :material-check: Supported |
2325
| Intel Sandy Bridge and [newer](https://en.wikipedia.org/wiki/List_of_Intel_Core_processors#Core_i_(2nd_gen)) (except for above mentions) | :material-check: Supported |
2426

25-
???+ info "HWPC Sensor PreRequisites"
27+
!!! note "HWPC Sensor PreRequisites"
2628
In addition of a supported architecture, there is some pre-requisites:
29+
2730
- Using a Linux distribution exposing the [perf](https://perf.wiki.kernel.org/index.php/Main_Page) api
2831
- Using Cgroup version 1 when using version 1.2 or older. See [this section](../cgroup/cgroup_v1_activation.md) about its configuration
2932
- Deploying on a physical device as the HWPC Sensor must have access to the real CPU register
@@ -49,82 +52,82 @@ Here is a sample to deploy the latest image version available.
4952

5053
The following tabs gives a complete overview of available parameters, along with their default values and description.
5154

52-
### Global parameters
55+
??? info "Global Parameters"
5356

54-
The table below shows the different parameters related to the Sensor global configuration, nested objects (system, container, output) are described in dedicated sections below:
57+
The table below shows the different parameters related to the Sensor global configuration, nested objects (system, container, output) are described in dedicated sections below:
5558

56-
| Parameter | Type | CLI shortcut | Default Value | Description |
57-
| ------------- | ----- | ------------- | ------------- | ------------------------------------ |
58-
|`verbose` | `bool` (flag) | `v` | `false` | Verbose or quiet mode |
59-
|`frequency` | `int` | `f` | `1000` | The time in milliseconds between two reports |
60-
|`name` | `string` | `n` | - | Name of the sensor |
61-
|`cgroup_basepath` | `string` | `p` | `/sys/fs/cgroup` (`cgroup` V2) | The base path for `cgroups`. To use `cgroup` V1 `/sys/fs/cgroup/perf_event` needs to be used as value |
62-
|`system` | `dict` | `s` | - | A system group with a monitoring type and a list of system events (cf. [`system` Group Parameters](hwpc-sensor.md#system-and-container-groups-parameters)) |
63-
|`container` | `dict` | `c` | - | A group with a monitoring type and a list of events (cf. [`system` Group Parameters](hwpc-sensor.md#system-and-container-groups-parameters)) |
64-
|`output` | `dict`| `r` | { "type": "csv", "directory": "." } | The [output information](hwpc-sensor.md#output), the Sensor only supports [MongoDB](./hwpc-sensor.md#mongodb-output) (`mongodb`), [CSV](./hwpc-sensor.md#csv-output) (`csv`) and [socket](./hwpc-sensor.md#socket-output) as output. |
59+
| Parameter | Type | CLI shortcut | Default Value | Description |
60+
| ------------- | ----- | :-------------: | :-------------: | ------------------------------------ |
61+
|`verbose` | `bool` (flag) | `v` | `false` | Verbose or quiet mode |
62+
|`frequency` | `int` | `f` | `1000` | The time in milliseconds between two reports |
63+
|`name` | `string` | `n` | - | Name of the sensor |
64+
|`cgroup_basepath` | `string` | `p` | `/sys/fs/cgroup` (`cgroup` V2) | The base path for `cgroups`. To use `cgroup` V1 `/sys/fs/cgroup/perf_event` needs to be used as value |
65+
|`system` | `dict` | `s` | - | A system group with a monitoring type and a list of system events (cf. [`system` Group Parameters](hwpc-sensor.md#system-and-container-groups-parameters)) |
66+
|`container` | `dict` | `c` | - | A group with a monitoring type and a list of events (cf. [`system` Group Parameters](hwpc-sensor.md#system-and-container-groups-parameters)) |
67+
|`output` | `dict`| `r` | { "type": "csv", "directory": "." } | The [output information](hwpc-sensor.md#output), the Sensor only supports [MongoDB](./hwpc-sensor.md#mongodb-output) (`mongodb`), [CSV](./hwpc-sensor.md#csv-output) (`csv`) and [socket](./hwpc-sensor.md#socket-output) as output. |
6568

66-
### `system` and `container` Groups Parameters
69+
??? info "Group Parameters (`system` and `container`)"
6770

68-
The table below shows the different parameters related to the Sensor `system` and `container` configuration fields:
71+
The table below shows the different parameters related to the Sensor `system` and `container` configuration fields:
6972

70-
| Parameter | Type | CLI shortcut | Default Value | Description |
71-
| ------------- | ----- | ------------- | ------------- | ------------------------------------ |
72-
|`events` | `string` | `e` | - | List of events to be monitored. As CLI parameter, each event is indicated with `e`. The structure of events is given [below](hwpc-sensor.md#events) |
73-
|`monitoring_type` | `string` ( **one of** `MONITOR_ONE_CPU_PER_SOCKET` **or** `MONITOR_ALL_CPU_PER_SOCKET` ) | `o` (flag) | `MONITOR_ALL_CPU_PER_SOCKET` | The monitoring type. If `o` is specified as CLI parameter, `MONITOR_ONE_CPU_PER_SOCKET` is used as type |
73+
| Parameter | Type | CLI shortcut | Default Value | Description |
74+
| ------------- | ----- | :-------------: | :-------------: | ------------------------------------ |
75+
|`events` | `string` | `e` | - | List of events to be monitored. As CLI parameter, each event is indicated with `e`. The structure of events is given [below](hwpc-sensor.md#events) |
76+
|`monitoring_type` | `string` ( **one of** `MONITOR_ONE_CPU_PER_SOCKET` **or** `MONITOR_ALL_CPU_PER_SOCKET` ) | `o` (flag) | `MONITOR_ALL_CPU_PER_SOCKET` | The monitoring type. If `o` is specified as CLI parameter, `MONITOR_ONE_CPU_PER_SOCKET` is used as type |
7477

75-
### Events
78+
??? info "Group Events"
7679

77-
Table below depicts the different group events for compatible Intel and AMD architectures.
80+
Table below depicts the different group events for compatible Intel and AMD architectures.
7881

79-
| Architectures | Group | Events |
80-
| ------------- | ----- | ------------- |
81-
|Intel Sandy Bridge and newer, AMD Zen 2 | `rapl` | `RAPL_ENERGY_PKG`, `RAPL_ENERGY_DRAM`|
82-
|Intel Sandy Bridge and newer, AMD Zen 2 | `msr` | `TSC`, `APERF`, `MPERF`|
83-
|Intel Skylake, Whiskey Lake, Coffee Lake| `core` | `CPU_CLK_THREAD_UNHALTED:REF_P`, `CPU_CLK_THREAD_UNHALTED:THREAD_P`, `LLC_MISSES`,`INSTRUCTIONS_RETIRED`|
84-
|Intel Sandy Bridge, Comet Lake | `core` | `CPU_CLK_UNHALTED:REF_P`, `CPU_CLK_UNHALTED:THREAD_P`, `LLC_MISSES`,`INSTRUCTIONS_RETIRED`|
85-
|AMD Zen 2 | `core`| `CYCLES_NOT_IN_HALT`, `RETIRED_INSTRUCTIONS` , `RETIRED_UOPS`|
86-
|AMD Zen 3 | `core`| `CYCLES_NOT_IN_HALT`, `RETIRED_INSTRUCTIONS` , `RETIRED_OPS`|
82+
| Architectures | Group | Events |
83+
| ------------- | ----- | ------------- |
84+
|Intel Sandy Bridge and newer, AMD Zen 2 | `rapl` | `RAPL_ENERGY_PKG`, `RAPL_ENERGY_DRAM`|
85+
|Intel Sandy Bridge and newer, AMD Zen 2 | `msr` | `TSC`, `APERF`, `MPERF`|
86+
|Intel Skylake, Whiskey Lake, Coffee Lake| `core` | `CPU_CLK_THREAD_UNHALTED:REF_P`, `CPU_CLK_THREAD_UNHALTED:THREAD_P`, `LLC_MISSES`,`INSTRUCTIONS_RETIRED`|
87+
|Intel Sandy Bridge, Comet Lake | `core` | `CPU_CLK_UNHALTED:REF_P`, `CPU_CLK_UNHALTED:THREAD_P`, `LLC_MISSES`,`INSTRUCTIONS_RETIRED`|
88+
|AMD Zen 2 | `core`| `CYCLES_NOT_IN_HALT`, `RETIRED_INSTRUCTIONS` , `RETIRED_UOPS`|
89+
|AMD Zen 3 | `core`| `CYCLES_NOT_IN_HALT`, `RETIRED_INSTRUCTIONS` , `RETIRED_OPS`|
8790

8891
### Output
8992

90-
As precised, two kinds of outputs are supported, MongoDB and CSV files.
93+
As precised, three kinds of outputs are supported: Socket, MongoDB and CSV files.
9194

92-
#### MongoDB Output
95+
??? info "MongoDB Output"
9396

94-
Table below depicts the different parameters for MongoDB type output with HWPC Sensor:
97+
Table below depicts the different parameters for MongoDB type output with HWPC Sensor:
9598

96-
| Parameter | Type | CLI shortcut | Default Value | Mandatory | Description |
97-
| ------------- | ----- | ------------- | ------------- | ---------- | ------------------------------------ |
98-
| `uri` | string | `U` | - | Yes | The IP address of your MongoDB instance |
99-
| `database` | string | `D` | - | Yes | The name of your database |
100-
| `collection` | string | `C` | - | Yes | The name of the collection inside `db` |
99+
| Parameter | Type | CLI shortcut | Default Value | Mandatory | Description |
100+
| ------------- | ----- | :-------------: | :-------------: | :----------: | ------------------------------------ |
101+
| `uri` | string | `U` | - | Yes | The IP address of your MongoDB instance |
102+
| `database` | string | `D` | - | Yes | The name of your database |
103+
| `collection` | string | `C` | - | Yes | The name of the collection inside `db` |
101104

102-
#### CSV Output
105+
??? info "CSV Output"
103106

104-
Table below depicts the different parameters for CSV type output:
107+
Table below depicts the different parameters for CSV type output:
105108

106-
| Parameter | Type | CLI shortcut | Default Value | Mandatory | Description |
107-
| ------------- | ----- | ------------- | ------------- | ----------| ------------------------------------ |
108-
| `directory` | string | `U` | "." (Current directory) | No |The directory where output CSV files will be written |
109+
| Parameter | Type | CLI shortcut | Default Value | Mandatory | Description |
110+
| ------------- | ----- | :-------------: | :-------------: | :----------:| ------------------------------------ |
111+
| `directory` | string | `U` | "." (Current directory) | No |The directory where output CSV files will be written |
109112

110-
#### Socket Output
113+
??? info "Socket Output"
111114

112-
Table below depicts the different parameters for Socket type output:
115+
Table below depicts the different parameters for Socket type output:
113116

114-
| Parameter | Type | CLI shortcut | Default Value | Mandatory | Description |
115-
| ------------- | ----- | ------------- | ------------- | ----------| ------------------------------------ |
116-
| `uri` | string | `U` | - | Yes | The IP address of the machine running the socket |
117-
| `port` | int | `P` | - | Yes | The port of communication |
117+
| Parameter | Type | CLI shortcut | Default Value | Mandatory | DQuoteescription |
118+
| ------------- | ----- | :-------------: | :-------------: | :----------:| ------------------------------------ |
119+
| `uri` | string | `U` | - | Yes | The IP address of the machine running the socket |
120+
| `port` | int | `P` | - | Yes | The port of communication |
118121

119122
### Running the Sensor with a Configuration File
120123

121124
The following snippets describe the configuration file of an HWPC Sensor instance, two examples are provided for both possible outputs:
122125

123-
???+ example "Examples using a Configuration File"
126+
!!! example "Examples using a Configuration File"
124127

125128
=== "MongoDB Output"
126129

127-
```json hl_lines="7 8 9 10" title="config_file.json"
130+
```json hl_lines="5-10" title="config_file.json"
128131
{
129132
"name": "sensor",
130133
"verbose": true,
@@ -159,7 +162,7 @@ The following snippets describe the configuration file of an HWPC Sensor instanc
159162

160163
=== "CSV Output"
161164

162-
```json hl_lines="6 7" title="config_file.json"
165+
```json hl_lines="5-8" title="config_file.json"
163166
{
164167
"name": "sensor",
165168
"verbose": true,
@@ -194,24 +197,24 @@ The following CLI command shows how to use this configuration file in the deploy
194197

195198
=== "Docker"
196199

197-
```sh hl_lines="9 10"
200+
```sh
198201
docker run --rm \
199-
--net=host \
200-
--privileged \
201-
--pid=host \
202-
-v /sys:/sys \
203-
-v /var/lib/docker/containers:/var/lib/docker/containers:ro \
204-
-v /tmp/powerapi-sensor-reporting:/reporting \
205-
-v $(pwd):/srv \
206-
-v $(pwd)/config_file.json:/config_file.json \
207-
powerapi/hwpc-sensor --config-file /config_file.json
202+
--net=host \
203+
--privileged \
204+
--pid=host \
205+
-v /sys:/sys \
206+
-v /var/lib/docker/containers:/var/lib/docker/containers:ro \
207+
-v /tmp/powerapi-sensor-reporting:/reporting \
208+
-v $(pwd):/srv \
209+
-v $(pwd)/config_file.json:/config_file.json \
210+
powerapi/hwpc-sensor --config-file /config_file.json
208211
```
209212

210213
### Running the Sensor via CLI parameters
211214

212215
The following CLI command shows how to launch an instance of HWPC Sensor with the same configuration as [above](hwpc-sensor.md#running-the-sensor-with-a-configuration-file), again two example are provided for both possible output:
213216

214-
???+ example "Examples using a CLI Parameters"
217+
!!! example "Examples using a CLI Parameters"
215218

216219
=== "CLI with MongoDB Output"
217220

@@ -251,9 +254,8 @@ The following CLI command shows how to launch an instance of HWPC Sensor with th
251254
-c "core" -e "CPU_CLK_THREAD_UNHALTED:REF_P" -e "CPU_CLK_THREAD_UNHALTED:THREAD_P" -e "LLC_MISSES" -e "INSTRUCTIONS_RETIRED"
252255
```
253256

254-
255-
???+ info "Reports' Storage"
257+
!!! note "Reports' Storage"
256258
Your [`HWPCReports`](../reports/reports.md#hwpc-reports) will be stored on MongoDB or in the `hwpc_reports.d`directory regarding the output type selected.
257259

258-
???+ tip "CLI parameters' names"
260+
!!! tip "CLI parameters' names"
259261
You can only use shortcuts.

0 commit comments

Comments
 (0)