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