man/systemd-cgtop.xml

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