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