Cgroup metric source

Cgroup v2 metric source for joule-profiler.

This crate implements a MetricReader from joule-profiler-core and collects process-level and system-wide metrics using Linux cgroup v2 interfaces.

Control groups (cgroups v2) are a Linux kernel feature that allows grouping processes and tracking/limiting their resource usage. This source uses cgroup files exposed under /sys/fs/cgroup.

Setup

Before using this source, the required cgroup controllers cpu, memory, io must be enabled on the cgroup hierarchy. This source does not enables them automatically, it is your responsibility to ensure controllers are active.

To enable them on the root cgroup:

echo "+cpu +memory +io" | sudo tee /sys/fs/cgroup/cgroup.subtree_control

To verify which controllers are currently enabled:

cat /sys/fs/cgroup/cgroup.subtree_control

To enable the required controllers for the root cgroup:

echo "+cpu +memory +io" | sudo tee /sys/fs/cgroup/cgroup.subtree_control

If you are using a nested cgroup, each ancestor must propagate the controllers down. For example, if your cgroup lives under /sys/fs/cgroup/nested_cgroup/mycgroup:

echo "+cpu +memory +io" | sudo tee /sys/fs/cgroup/cgroup.subtree_control
echo "+cpu +memory +io" | sudo tee /sys/fs/cgroup/nested_cgroup/cgroup.subtree_control

[!IMPORTANT] By default, a nested cgroup inherit its parent controllers files. Nonetheless, the parent of the nested cgroup must enable the controllers.

[!NOTE] On systemd-based systems, some controllers may already be enabled. Check /sys/fs/cgroup/cgroup.subtree_control first.

Manual cgroup creation / process attachment

Alternatively, you can configure the source to not create the cgroup or not attach the pid to the configured cgroup with the create_cgroup and attach_pid options in the config.

To create a cgroup, do:

sudo mkdir /sys/fs/cgroup/{your_cgroup_path}

You can also create a cgroup slice using systemd to be able to spawn processes directly in it:

cat <<EOF | sudo tee /etc/systemd/system/{your_slice_name} >/dev/null
[Unit]
Description={description}

[Slice]
CPUWeight=100
IOWeight=100
MemoryMax=infinity
EOF

After that you can use systemd to spawn a process directly in your slice:

systemd-run --scope --slice={your_slice_name} {your_command}

By configuring the cgroup source with create_cgroup and attach_pid to false, Joule Profiler will be able to profile the process directly at spawn. This configuration can also benefits to the perf_event source. See perf_event source documentation for further information.

Implemented metrics

All metrics are reported for both the process cgroup and the root cgroup, thus they are prefixed with a proc or a global.

Here is the list of the metrics implemented.

CPU

Memory

I/O

Requirements