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

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

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

5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering

<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. This setting may also be toggled at runtime by

pressing the <keycap>%</keycap> key.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>-k</option></term>

<listitem><para>Include kernel threads when counting tasks in

control groups. By default, kernel threads are not included in

the count. This setting may also be toggled at runtime by

pressing the <keycap>k</keycap> key.</para></listitem>

</varlistentry>

<varlistentry>

<term><option>--recursive=</option></term>

<listitem><para>Controls whether the number of tasks shown for

a control group shall include all tasks that are contained in

any of the child control groups as well. Takes a boolean

argument, defaults to <literal>yes</literal>. If enabled the

tasks in child control groups are included, if disabled only

the tasks in the control group itself are counted. This

setting may also be toggled at runtime by pressing the

<keycap>r</keycap> key.</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). This setting may also be increased and decreased at

runtime by pressing the <keycap>+</keycap> and

<keycap>-</keycap> keys.</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><keycap>h</keycap></term>

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

</varlistentry>

<varlistentry>

<term><keycap function="space"/></term>

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

</varlistentry>

<varlistentry>

<term><keycap>q</keycap></term>

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

</varlistentry>

<varlistentry>

<term><keycap>p</keycap></term>

<term><keycap>t</keycap></term>

<term><keycap>c</keycap></term>

<term><keycap>m</keycap></term>

<term><keycap>i</keycap></term>

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

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

setting may also be controlled using the

<option>--order=</option> command line

switch.</para></listitem>

</varlistentry>

<varlistentry>

<term><keycap>%</keycap></term>

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

percentage. This setting may also be controlled using the

<option>--cpu=</option> command line switch.</para></listitem>

</varlistentry>

<varlistentry>

<term><keycap>+</keycap></term>

<term><keycap>-</keycap></term>

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

respectively. This setting may also be controlled using the

<option>--delay=</option> command line

switch.</para></listitem>

</varlistentry>

<varlistentry>

<term><keycap>k</keycap></term>

<listitem><para>Toggle between including or excluding kernel

threads in control group task counts. This setting may also be

controlled using the <option>-k</option> command line

switch.</para></listitem>

</varlistentry>

<varlistentry>

<term><keycap>r</keycap></term>

<listitem><para>Toggle between recursively including or

excluding tasks in child control groups in control group task

counts. This setting may also be controlled using the

<option>--recursive=</option> command line

switch.</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>