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