man/systemd-cgtop.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="systemd-cgtop"
  10     xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>systemd-cgtop</title>
  14     <productname>systemd</productname>
  15
  16     <authorgroup>
  17       <author>
  18         <contrib>Developer</contrib>
  19         <firstname>Lennart</firstname>
  20         <surname>Poettering</surname>
  21         <email>lennart@poettering.net</email>
  22       </author>
  23     </authorgroup>
  24   </refentryinfo>
  25
  26   <refmeta>
  27     <refentrytitle>systemd-cgtop</refentrytitle>
  28     <manvolnum>1</manvolnum>
  29   </refmeta>
  30
  31   <refnamediv>
  32     <refname>systemd-cgtop</refname>
  33     <refpurpose>Show top control groups by their resource usage</refpurpose>
  34   </refnamediv>
  35
  36   <refsynopsisdiv>
  37     <cmdsynopsis>
  38       <command>systemd-cgtop</command>
  39       <arg choice="opt" rep="repeat">OPTIONS</arg>
  40       <arg choice="opt">GROUP</arg>
  41     </cmdsynopsis>
  42   </refsynopsisdiv>
  43
  44   <refsect1>
  45     <title>Description</title>
  46
  47     <para><command>systemd-cgtop</command> shows the top control
  48     groups of the local Linux control group hierarchy, ordered by
  49     their CPU, memory, or disk I/O load. The display is refreshed in
  50     regular intervals (by default every 1s), similar in style to
  51     <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  52     If a control group path is specified, shows only the services of
  53     the specified control group.</para>
  54
  55     <para>If <command>systemd-cgtop</command> is not connected to a
  56     tty, no column headers are printed and the default is to only run
  57     one iteration.  The <varname>--iterations=</varname> argument, if
  58     given, is honored. This mode is suitable for scripting.</para>
  59
  60     <para>Resource usage is only accounted for control groups in the
  61     relevant hierarchy, i.e. CPU usage is only accounted for control
  62     groups in the <literal>cpuacct</literal> hierarchy, memory usage
  63     only for those in <literal>memory</literal> and disk I/O usage for
  64     those in <literal>blkio</literal>. If resource monitoring for
  65     these resources is required, it is recommended to add the
  66     <varname>CPUAccounting=1</varname>,
  67     <varname>MemoryAccounting=1</varname> and
  68     <varname>BlockIOAccounting=1</varname> settings in the unit files
  69     in question. See
  70     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  71     for details.</para>
  72
  73     <para>The CPU load value can be between 0 and 100 times the number of
  74     processors the system has. For example, if the system has 8 processors,
  75     the CPU load value is going to be between 0% and 800%. The number of
  76     processors can be found in <literal>/proc/cpuinfo</literal>.</para>
  77
  78     <para>To emphasize this: unless
  79     <literal>CPUAccounting=1</literal>,
  80     <literal>MemoryAccounting=1</literal> and
  81     <literal>BlockIOAccounting=1</literal> are enabled for the
  82     services in question, no resource accounting will be available for
  83     system services and the data shown by
  84     <command>systemd-cgtop</command> will be incomplete.</para>
  85   </refsect1>
  86
  87   <refsect1>
  88     <title>Options</title>
  89
  90     <para>The following options are understood:</para>
  91
  92     <variablelist>
  93       <varlistentry>
  94         <term><option>-p</option></term>
  95         <term><option>--order=path</option></term>
  96
  97         <listitem><para>Order by control group
  98         path name.</para></listitem>
  99       </varlistentry>
 100
 101       <varlistentry>
 102         <term><option>-t</option></term>
 103         <term><option>--order=tasks</option></term>
 104
 105         <listitem><para>Order by number of tasks/processes in the control group.</para></listitem>
 106       </varlistentry>
 107
 108       <varlistentry>
 109         <term><option>-c</option></term>
 110         <term><option>--order=cpu</option></term>
 111
 112         <listitem><para>Order by CPU load.</para></listitem>
 113       </varlistentry>
 114
 115       <varlistentry>
 116         <term><option>-m</option></term>
 117         <term><option>--order=memory</option></term>
 118
 119         <listitem><para>Order by memory usage.</para></listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term><option>-i</option></term>
 124         <term><option>--order=io</option></term>
 125
 126         <listitem><para>Order by disk I/O load.</para></listitem>
 127       </varlistentry>
 128
 129       <varlistentry>
 130         <term><option>-b</option></term>
 131         <term><option>--batch</option></term>
 132
 133         <listitem><para>Run in "batch" mode: do not accept input and
 134         run until the iteration limit set with
 135         <option>--iterations=</option> is exhausted or until killed.
 136         This mode could be useful for sending output from
 137         <command>systemd-cgtop</command> to other programs or to a
 138         file.</para></listitem>
 139       </varlistentry>
 140
 141       <varlistentry>
 142         <term><option>-r</option></term>
 143         <term><option>--raw</option></term>
 144
 145         <listitem><para>Format byte counts (as in memory usage and I/O metrics)
 146         with raw numeric values rather than human-readable
 147         numbers.</para></listitem>
 148       </varlistentry>
 149
 150       <varlistentry>
 151         <term><option>--cpu=percentage</option></term>
 152         <term><option>--cpu=time</option></term>
 153
 154         <listitem><para>Controls whether the CPU usage is shown as
 155         percentage or time. By default, the CPU usage is shown as
 156         percentage. This setting may also be toggled at runtime by
 157         pressing the <keycap>%</keycap> key.</para></listitem>
 158       </varlistentry>
 159
 160       <varlistentry>
 161         <term><option>-P</option></term>
 162
 163         <listitem><para>Count only userspace processes instead of all
 164         tasks. By default, all tasks are counted: each kernel thread
 165         and each userspace thread individually. With this setting,
 166         kernel threads are excluded from the counting and each
 167         userspace process only counts as one, regardless how many
 168         threads it consists of. This setting may also be toggled at
 169         runtime by pressing the <keycap>P</keycap> key. This option
 170         may not be combined with
 171         <option>-k</option>.</para></listitem>
 172       </varlistentry>
 173
 174       <varlistentry>
 175         <term><option>-k</option></term>
 176
 177         <listitem><para>Count only userspace processes and kernel
 178         threads instead of all tasks. By default, all tasks are
 179         counted: each kernel thread and each userspace thread
 180         individually. With this setting, kernel threads are included in
 181         the counting and each userspace process only counts as on one,
 182         regardless how many threads it consists of. This setting may
 183         also be toggled at runtime by pressing the <keycap>k</keycap>
 184         key. This option may not be combined with
 185         <option>-P</option>.</para></listitem>
 186       </varlistentry>
 187
 188       <varlistentry>
 189         <term><option>--recursive=</option></term>
 190
 191         <listitem><para>Controls whether the number of processes shown
 192         for a control group shall include all processes that are
 193         contained in any of the child control groups as well. Takes a
 194         boolean argument, which defaults to <literal>yes</literal>. If
 195         enabled, the processes in child control groups are included, if
 196         disabled, only the processes in the control group itself are
 197         counted. This setting may also be toggled at runtime by
 198         pressing the <keycap>r</keycap> key. Note that this setting
 199         only applies to process counting, i.e. when the
 200         <option>-P</option> or <option>-k</option> options are
 201         used. It has not effect if all tasks are counted, in which
 202         case the counting is always recursive.</para></listitem>
 203       </varlistentry>
 204
 205       <varlistentry>
 206         <term><option>-n</option></term>
 207         <term><option>--iterations=</option></term>
 208
 209         <listitem><para>Perform only this many iterations. A value of
 210         0 indicates that the program should run
 211         indefinitely.</para></listitem>
 212       </varlistentry>
 213
 214       <varlistentry>
 215         <term><option>-1</option></term>
 216
 217         <listitem><para>A shortcut for <option>--iterations=1</option>.</para></listitem>
 218       </varlistentry>
 219
 220       <varlistentry>
 221         <term><option>-d</option></term>
 222         <term><option>--delay=</option></term>
 223
 224         <listitem><para>Specify refresh delay in seconds (or if one of
 225         <literal>ms</literal>, <literal>us</literal>,
 226         <literal>min</literal> is specified as unit in this time
 227         unit). This setting may also be increased and decreased at
 228         runtime by pressing the <keycap>+</keycap> and
 229         <keycap>-</keycap> keys.</para></listitem>
 230       </varlistentry>
 231
 232       <varlistentry>
 233         <term><option>--depth=</option></term>
 234
 235         <listitem><para>Maximum control group tree traversal depth.
 236         Specifies how deep <command>systemd-cgtop</command> shall
 237         traverse the control group hierarchies. If 0 is specified,
 238         only the root group is monitored. For 1, only the first level
 239         of control groups is monitored, and so on. Defaults to
 240         3.</para></listitem>
 241       </varlistentry>
 242
 243       <varlistentry>
 244         <term><option>-M <replaceable>MACHINE</replaceable></option></term>
 245         <term><option>--machine=<replaceable>MACHINE</replaceable></option></term>
 246
 247         <listitem><para>Limit control groups shown to the part
 248         corresponding to the container
 249         <replaceable>MACHINE</replaceable>.
 250         This option may not be used when a control group path is specified.</para></listitem>
 251       </varlistentry>
 252
 253       <xi:include href="standard-options.xml" xpointer="help" />
 254       <xi:include href="standard-options.xml" xpointer="version" />
 255     </variablelist>
 256
 257   </refsect1>
 258
 259   <refsect1>
 260     <title>Keys</title>
 261
 262     <para><command>systemd-cgtop</command> is an interactive tool and
 263     may be controlled via user input using the following keys:</para>
 264
 265     <variablelist>
 266       <varlistentry>
 267         <term><keycap>h</keycap></term>
 268
 269         <listitem><para>Shows a short help text.</para></listitem>
 270       </varlistentry>
 271
 272       <varlistentry>
 273         <term><keycap function="space"/></term>
 274
 275         <listitem><para>Immediately refresh output.</para></listitem>
 276       </varlistentry>
 277
 278       <varlistentry>
 279         <term><keycap>q</keycap></term>
 280
 281         <listitem><para>Terminate the program.</para></listitem>
 282       </varlistentry>
 283
 284       <varlistentry>
 285         <term><keycap>p</keycap></term>
 286         <term><keycap>t</keycap></term>
 287         <term><keycap>c</keycap></term>
 288         <term><keycap>m</keycap></term>
 289         <term><keycap>i</keycap></term>
 290
 291         <listitem><para>Sort the control groups by path, number of
 292         tasks, CPU load, memory usage, or I/O load, respectively.  This
 293         setting may also be controlled using the
 294         <option>--order=</option> command line
 295         switch.</para></listitem>
 296       </varlistentry>
 297
 298       <varlistentry>
 299         <term><keycap>%</keycap></term>
 300
 301         <listitem><para>Toggle between showing CPU time as time or
 302         percentage. This setting may also be controlled using the
 303         <option>--cpu=</option> command line switch.</para></listitem>
 304       </varlistentry>
 305
 306       <varlistentry>
 307         <term><keycap>+</keycap></term>
 308         <term><keycap>-</keycap></term>
 309
 310         <listitem><para>Increase or decrease refresh delay,
 311         respectively. This setting may also be controlled using the
 312         <option>--delay=</option> command line
 313         switch.</para></listitem>
 314       </varlistentry>
 315
 316       <varlistentry>
 317         <term><keycap>P</keycap></term>
 318
 319         <listitem><para>Toggle between counting all tasks, or only
 320         userspace processes. This setting may also be controlled using
 321         the <option>-P</option> command line switch (see
 322         above).</para></listitem>
 323       </varlistentry>
 324
 325       <varlistentry>
 326         <term><keycap>k</keycap></term>
 327
 328         <listitem><para>Toggle between counting all tasks, or only
 329         userspace processes and kernel threads. This setting may also
 330         be controlled using the <option>-k</option> command line
 331         switch (see above).</para></listitem>
 332       </varlistentry>
 333
 334       <varlistentry>
 335         <term><keycap>r</keycap></term>
 336
 337         <listitem><para>Toggle between recursively including or
 338         excluding processes in child control groups in control group
 339         process counts. This setting may also be controlled using the
 340         <option>--recursive=</option> command line switch. This key is
 341         not available if all tasks are counted, it is only available
 342         if processes are counted, as enabled with the
 343         <keycap>P</keycap> or <keycap>k</keycap>
 344         keys.</para></listitem>
 345       </varlistentry>
 346
 347     </variablelist>
 348   </refsect1>
 349
 350   <refsect1>
 351     <title>Exit status</title>
 352
 353     <para>On success, 0 is returned, a non-zero failure code
 354     otherwise.</para>
 355   </refsect1>
 356
 357   <refsect1>
 358     <title>See Also</title>
 359     <para>
 360       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 361       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 362       <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 363       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 364       <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 365     </para>
 366   </refsect1>
 367
 368 </refentry>