man/systemd-cgtop.xml

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