systemd-cgtop

Start an interactive view

$ systemd-cgtop

$ systemd-cgtop --order [cpu|memory|path|tasks|io]

$ systemd-cgtop --cpu=percentage

$ systemd-cgtop [[-d|--delay]] [interval]

$ systemd-cgtop -P

systemd-cgtop [OPTIONS...]

-h, --help
    Show a help message and exit.

--version
    Show version information and exit.

-p, --_pretty
    Pretty print output, using human-readable units (e.g., '1.5G' instead of '1500000000').

-b, --batch
    Run in batch mode, printing output once and exiting. Useful for scripting and redirecting output.

-d, --delay=SEC
    Set the update delay in seconds for interactive mode. The default is 3 seconds.

-M, --json=MODE
    Output in JSON format. MODE can be 'pretty', 'short', or 'off'.

-c, --color
    Enable colored output, enhancing readability.

-k, --kill-cgroup=PATH
    Immediately kill all processes within the specified cgroup PATH. Use with extreme caution.

-P, --no-pager
    Do not pipe output into a pager, showing it directly in the terminal.

-n, --lines=NUMBER
    In batch mode, show the top NUMBER of cgroups. (Implies --batch).

-u, --user
    Only show cgroups belonging to user sessions (scope units).

-r, --recursive
    Show recursive cgroup usage, including all descendants. This is the default behavior.

-a, --all
    Show all cgroups, including those with zero resource usage.

-m, --memory
    Sort the output by memory usage.

-i, --io
    Sort the output by I/O usage.

-T, --tasks
    Sort the output by the number of tasks (PIDs) in each cgroup.

-C, --cpu
    Sort the output by CPU usage. This is the default sort order.

systemd-cgtop is a command-line utility provided by the systemd init system. It offers a real-time, interactive overview of resource usage (CPU, memory, I/O, PIDs) categorized by control groups (cgroups). Similar to top but focused on the hierarchical cgroup structure, it allows system administrators and developers to quickly identify resource-intensive services, slices, and other systemd units.

It's an invaluable tool for diagnosing performance bottlenecks, understanding resource consumption patterns, and ensuring fair resource allocation across different applications and services managed by systemd. By default, it sorts by CPU usage, but can be configured to sort by other metrics or operate in a non-interactive batch mode for scripting and reporting.

Viewing all cgroups and their detailed resource usage often requires root privileges or specific capabilities. The -k, --kill-cgroup option is extremely powerful and can immediately terminate critical system services if misused, potentially leading to system instability or crashes. Output on very busy systems can be extensive; judicious use of sorting and filtering options is recommended.

By default, systemd-cgtop runs in an interactive mode, providing a dynamic, refreshing display. Users can interact with the view using various keyboard shortcuts: for example, pressing 'm' will sort by memory, 'c' by CPU, 'i' by I/O, and 'q' will quit the application. This interactivity makes it highly suitable for real-time monitoring and troubleshooting.

The command is designed to work seamlessly with cgroup V2, the unified cgroup hierarchy, which systemd primarily uses for resource control. It provides a clear, hierarchical representation of resource consumption, making it easier to understand how resources are being used across different levels of the systemd unit tree (slices, scopes, services).

systemd-cgtop is an integral part of the systemd init system, which first emerged in 2010. Its development is closely tied to systemd's increasing reliance on and management of Linux control groups (cgroups), particularly with the adoption of cgroup V2 for resource isolation and accounting. It was introduced to provide a more native and detailed view into systemd's resource management features, offering insights into how services and other units utilize system resources within their defined cgroup hierarchies.

systemd(1), top(1), htop(1), cgroups(7), systemctl(1), systemd-cgls(1), systemd-analyze(1)