Skip to content

Commit 6172f9b

Browse files
davidkoppdavidkopp
authored
Add missing doc pages for disc metric providers (#102)
* Add missing documentation of metric provider 'Disk IO - cgroup - container' * Add missing documentation of metric provider 'Disk IO - procfs - system' * Add missing documentation of metric provider 'Disk used - statvfs - system'
1 parent 1dd801c commit 6172f9b

File tree

3 files changed

+218
-0
lines changed

3 files changed

+218
-0
lines changed

‎content/en/docs/measuring/metric-providers/disk-io-cgroup-container.md

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
title: "Disk IO - cgroup - container"
3+
description: "Documentation for DiskIoCgroupContainerProvider of the Green Metrics Tool"
4+
date: 2025-07-07T15:52:00+00:00
5+
weight: 205
6+
---
7+
8+
### What it does
9+
10+
It reads the total amount of read and written bytes from disk devices by the cgroup of the container. More information about cgroups can be found [here](https://www.man7.org/linux/man-pages/man7/cgroups.7.html).
11+
12+
### Classname
13+
14+
- `DiskIoCgroupContainerProvider`
15+
16+
### Metric Name
17+
18+
- `disk_io_cgroup_container`
19+
20+
### Input Parameters
21+
22+
- args
23+
- `-s`: container-ids separated by commas
24+
- `-i`: interval in milliseconds (optional, default: 1000 ms)
25+
26+
Example measuring two containers with an interval of 100 ms:
27+
28+
```bash
29+
./metric-provider-binary -i 100 -s 7f38a4c25fb8f9d5f8651d6ed986b3658dba20d1f5fec98a1f71c141c2b48f4b,c3592e1385d63f9c7810470b12aa00f7d6f7c0e2b9981ac2bdb4371126a0660a
30+
```
31+
32+
### Output
33+
34+
This metric provider prints to Stdout a continuous stream of data. The format of the data is as follows:
35+
36+
`TIMESTAMP RBYTES WBYTES CONTAINER-ID`
37+
38+
Where:
39+
40+
- `TIMESTAMP`: Unix timestamp, in microseconds
41+
- `RBYTES`: The cumulative amount of bytes read from disk since container start
42+
- `WBYTES`: The cumulative amount of bytes written to disk since container start
43+
- `CONTAINER-ID`: The container ID that this reading is for
44+
45+
Any errors are printed to Stderr.
46+
47+
### How it works
48+
49+
The provider assumes that you have [cgroups v2](https://www.man7.org/linux/man-pages/man7/cgroups.7.html) enabled on your system.
50+
51+
It reads from the cgroup's `io.stat` file which provides per-device I/O statistics for the container.
52+
53+
The provider:
54+
55+
- parses the `io.stat` file to extract `rbytes` and `wbytes` values
56+
- filters out virtual devices that don't represent actual disk I/O:
57+
- Memory devices (major 1)
58+
- Floppy disk controllers (major 2)
59+
- Loopback devices (major 7)
60+
- SCSI CD-ROM (major 11)
61+
- ALSA sound devices (major 116)
62+
- Xen virtual block devices (major 202)
63+
- only counts whole disk devices (minor number divisible by 16)
64+
- sums up the read and write bytes across all real disk devices
65+
66+
#### Device filtering
67+
68+
The provider filters out virtual and non-disk devices to focus on actual disk I/O operations that consume energy. It checks the major device numbers against a list of known virtual devices and excludes them from the calculations.
69+
70+
If partition devices are encountered (minor number not divisible by 16), the provider will exit with an error as this should not happen in a properly configured container environment.
71+
72+
#### Attribution of disk I/O
73+
74+
The disk I/O is attributed directly to each container based on the cgroup accounting. This provides accurate per-container disk usage without double-counting or attribution issues.
75+
76+
Since containers share the same underlying disk devices, the measurements represent the actual bytes read from and written to the physical storage by each container's processes.

‎content/en/docs/measuring/metric-providers/disk-io-procfs-system.md

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: "Disk IO - procfs - system"
3+
description: "Documentation for DiskIoProcfsSystemProvider of the Green Metrics Tool"
4+
date: 2025-07-07T16:10:00+00:00
5+
weight: 206
6+
---
7+
8+
### What it does
9+
10+
It reads the total amount of sectors read and written from all disk devices on the system by parsing `/proc/diskstats`. This provides system-wide disk I/O statistics.
11+
12+
### Classname
13+
14+
- `DiskIoProcfsSystemProvider`
15+
16+
### Metric Name
17+
18+
- `disk_io_procfs_system`
19+
20+
### Input Parameters
21+
22+
- args
23+
- `-i`: interval in milliseconds (optional, default: 1000 ms)
24+
25+
Example measuring system disk I/O with an interval of 100 ms:
26+
27+
```bash
28+
./metric-provider-binary -i 100
29+
```
30+
31+
### Output
32+
33+
This metric provider prints to Stdout a continuous stream of data. The format of the data is as follows:
34+
35+
`TIMESTAMP SECTORS_READ SECTORS_WRITTEN DEVICE_NAME`
36+
37+
Where:
38+
39+
- `TIMESTAMP`: Unix timestamp, in microseconds
40+
- `SECTORS_READ`: The cumulative number of sectors read from the device since system boot
41+
- `SECTORS_WRITTEN`: The cumulative number of sectors written to the device since system boot
42+
- `DEVICE_NAME`: The name of the disk device (e.g., sda, nvme0n1)
43+
44+
Any errors are printed to Stderr.
45+
46+
### How it works
47+
48+
The provider reads from `/proc/diskstats` which provides kernel-level disk I/O statistics for all block devices on the system.
49+
50+
The provider:
51+
52+
- parses `/proc/diskstats` to extract sectors read and written for each device
53+
- filters out virtual devices that don't represent actual disk I/O:
54+
- Memory devices (major 1)
55+
- Floppy disk controllers (major 2)
56+
- Loopback devices (major 7)
57+
- SCSI CD-ROM (major 11)
58+
- ALSA sound devices (major 116)
59+
- Xen virtual block devices (major 202)
60+
- only counts whole disk devices (minor number divisible by 16), skipping partitions
61+
- outputs statistics for each qualifying disk device
62+
63+
#### Device filtering
64+
65+
The provider filters out virtual and non-disk devices to focus on actual physical disk devices that consume energy. Partition devices (minor number not divisible by 16) are also skipped to avoid double-counting, as the whole disk statistics already include all partition activity.
66+
67+
#### Sectors vs Bytes
68+
69+
The output is in sectors rather than bytes. To convert to bytes, multiply by the sector size (typically 512 bytes for most devices, but can vary). The sector size can be obtained from `/sys/block/<device>/queue/logical_block_size`.
70+
71+
#### System-wide monitoring
72+
73+
Unlike container-specific providers, this metric provider monitors all disk I/O activity on the system, providing a complete picture of disk utilization across all processes and containers.
74+
75+
The values are cumulative since system boot, so calculating actual I/O rates requires taking differences between consecutive measurements.

‎content/en/docs/measuring/metric-providers/disk-used-statvfs-system.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: "Disk Used - statvfs - system"
3+
description: "Documentation for DiskUsedStatvfsSystemProvider of the Green Metrics Tool"
4+
date: 2025-07-07T16:15:00+00:00
5+
weight: 207
6+
---
7+
8+
### What it does
9+
10+
It reads the total amount of disk space used on the root filesystem by using the `statvfs()` system call. This provides system-wide disk usage information.
11+
12+
### Classname
13+
14+
- `DiskUsedStatvfsSystemProvider`
15+
16+
### Metric Name
17+
18+
- `disk_used_statvfs_system`
19+
20+
### Input Parameters
21+
22+
- args
23+
- `-i`: interval in milliseconds (optional, default: 1000 ms)
24+
25+
Example measuring system disk usage with an interval of 100 ms:
26+
27+
```bash
28+
./metric-provider-binary -i 100
29+
```
30+
31+
### Output
32+
33+
This metric provider prints to Stdout a continuous stream of data. The format of the data is as follows:
34+
35+
`TIMESTAMP BYTES_USED`
36+
37+
Where:
38+
39+
- `TIMESTAMP`: Unix timestamp, in microseconds
40+
- `BYTES_USED`: The total amount of disk space used on the root filesystem, in bytes
41+
42+
Any errors are printed to Stderr.
43+
44+
### How it works
45+
46+
The provider uses the `statvfs()` system call to query filesystem statistics for the root filesystem (`/`).
47+
48+
The provider:
49+
50+
- calls `statvfs("/", &buf)` to get filesystem statistics
51+
- calculates total space as `f_blocks * f_frsize`
52+
- calculates free space as `f_bfree * f_frsize`
53+
- returns used space as `total_space - free_space`
54+
55+
#### statvfs vs statfs
56+
57+
This provider uses `statvfs()` which is the POSIX-compliant version of filesystem statistics, providing portable access to filesystem information across different Unix-like systems.
58+
59+
#### Free space calculation
60+
61+
The provider uses `f_bfree` (free blocks available to superuser) rather than `f_bavail` (free blocks available to non-privileged users) to calculate free space. This means the "used" calculation includes space reserved for the superuser, providing a more accurate representation of actual disk utilization.
62+
63+
#### Root filesystem monitoring
64+
65+
This provider specifically monitors the root filesystem (`/`) usage. In most systems, this represents the primary disk where the operating system and most applications are installed. If you have separate mount points for different filesystems, this provider will only report usage for the root filesystem.
66+
67+
The measurement represents the current total disk usage and is not cumulative - it's an absolute measurement of how much disk space is currently occupied on the filesystem.

0 commit comments

Comments
 (0)