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