<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->

<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"

"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<refentry id="systemd-cgtop"

xmlns:xi="http://www.w3.org/2001/XInclude">

<refentryinfo>

<title>systemd-cgtop</title>

<productname>systemd</productname>

<authorgroup>

<author>

<contrib>Developer</contrib>

<firstname>Lennart</firstname>

<surname>Poettering</surname>

<email>lennart@poettering.net</email>

</author>

</authorgroup>

</refentryinfo>

<refmeta>

<refentrytitle>systemd-cgtop</refentrytitle>

<manvolnum>1</manvolnum>

</refmeta>

<refnamediv>

<refname>systemd-cgtop</refname>

<refpurpose>Show top control groups by their resource usage</refpurpose>

</refnamediv>

<refsynopsisdiv>

<cmdsynopsis>

<command>systemd-cgtop</command>

<arg choice="opt" rep="repeat">OPTIONS</arg>

</cmdsynopsis>

</refsynopsisdiv>

<refsect1>

<title>Description</title>

<para><command>systemd-cgtop</command> shows the top control

groups of the local Linux control group hierarchy, ordered by

their CPU, memory, or disk I/O load. The display is refreshed in

regular intervals (by default every 1s), similar in style to

<citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>

<para>If <command>systemd-cgtop</command> is not connected to a

tty, no column headers are printed and the default is to only run

one iteration. The <varname>--iterations=</varname> argument, if

given, is honored. This mode is suitable for scripting.</para>

<para>Resource usage is only accounted for control groups in the

relevant hierarchy, i.e. CPU usage is only accounted for control

groups in the <literal>cpuacct</literal> hierarchy, memory usage

only for those in <literal>memory</literal> and disk I/O usage for

those in <literal>blkio</literal>. If resource monitoring for

these resources is required, it is recommended to add the

<varname>CPUAccounting=1</varname>,

<varname>MemoryAccounting=1</varname> and

<varname>BlockIOAccounting=1</varname> settings in the unit files

in question. See

<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>

for details.</para>

<para>The CPU load value can be between 0 and 100 times the number of

processors the system has. For example, if the system has 8 processors,

the CPU load value is going to be between 0% and 800%. The number of

processors can be found in <literal>/proc/cpuinfo</literal>.</para>

<para>To emphasize this: unless

<literal>CPUAccounting=1</literal>,

<literal>MemoryAccounting=1</literal> and

<literal>BlockIOAccounting=1</literal> are enabled for the

services in question, no resource accounting will be available for

system services and the data shown by

<command>systemd-cgtop</command> will be incomplete.</para>

</refsect1>

<refsect1>

<title>Options</title>

<para>The following options are understood:</para>

<variablelist>

<varlistentry>

<term><option>-p</option></term>

<term><option>--order=path</option></term>

<listitem><para>Order by control group

path name.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>-t</option></term>

<term><option>--order=tasks</option></term>

<listitem><para>Order by number of processes in control group.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>-c</option></term>

<term><option>--order=cpu</option></term>

<listitem><para>Order by CPU load.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>-m</option></term>

<term><option>--order=memory</option></term>

<listitem><para>Order by memory usage.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>-i</option></term>

<term><option>--order=io</option></term>

<listitem><para>Order by disk I/O load.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>-b</option></term>

<term><option>--batch</option></term>

<listitem><para>Run in "batch" mode: do not accept input and

run until the iteration limit set with

<option>--iterations=</option> is exhausted or until killed.

This mode could be useful for sending output from

<command>systemd-cgtop</command> to other programs or to a

file.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>-r</option></term>

<term><option>--raw</option></term>

<listitem><para>Format byte counts (as in memory usage and IO metrics)

with raw numeric values rather than human-readable

numbers.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--cpu=percentage</option></term>

<term><option>--cpu=time</option></term>

<listitem><para>Controls whether the CPU usage is shown as

percentage or time. By default the CPU usage is shown as

percentage.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>-n</option></term>

<term><option>--iterations=</option></term>

<listitem><para>Perform only this many iterations. A value of 0

indicates that the program should run indefinitely.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>-d</option></term>

<term><option>--delay=</option></term>

<listitem><para>Specify refresh delay in seconds (or if one of

<literal>ms</literal>,

<literal>us</literal>,

<literal>min</literal> is specified as unit in this time

unit).</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--depth=</option></term>

<listitem><para>Maximum control group tree traversal depth.

Specifies how deep <command>systemd-cgtop</command> shall

traverse the control group hierarchies. If 0 is specified,

only the root group is monitored. For 1, only the first level

of control groups is monitored, and so on. Defaults to

3.</para></listitem>

</varlistentry>

<xi:include href="standard-options.xml" xpointer="help" />

<xi:include href="standard-options.xml" xpointer="version" />

</variablelist>

</refsect1>

<refsect1>

<title>Keys</title>

<para><command>systemd-cgtop</command> is an interactive tool and

may be controlled via user input using the following keys:</para>

<variablelist>

<varlistentry>

<term>h</term>

<listitem><para>Shows a short help text.</para></listitem>

</varlistentry>

<varlistentry>

<term>SPACE</term>

<listitem><para>Immediately refresh output.</para></listitem>

</varlistentry>

<varlistentry>

<term>q</term>

<listitem><para>Terminate the program.</para></listitem>

</varlistentry>

<varlistentry>

<term>p</term>

<term>t</term>

<term>c</term>

<term>m</term>

<term>i</term>

<listitem><para>Sort the control groups by path, number of

tasks, CPU load, memory usage, or IO load, respectively.

</para></listitem>

</varlistentry>

<varlistentry>

<term>%</term>

<listitem><para>Toggle between showing CPU time as time or

percentage.</para></listitem>

</varlistentry>

<varlistentry>

<term>+</term>

<term>-</term>

<listitem><para>Increase or decrease refresh delay,

respectively.</para></listitem>

</varlistentry>

</variablelist>

</refsect1>

<refsect1>

<title>Exit status</title>

<para>On success, 0 is returned, a non-zero failure code

otherwise.</para>

</refsect1>

<refsect1>

<title>See Also</title>

<para>

<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,

<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,

<citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>

</para>

</refsect1>

</refentry>