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 processes in 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 IO 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.</para></listitem>
 169       </varlistentry>
 170
 171       <varlistentry>
 172         <term><option>-k</option></term>
 173
 174         <listitem><para>Include kernel threads when counting tasks in
 175         control groups. By default, kernel threads are not included in
 176         the count.</para></listitem>
 177       </varlistentry>
 178
 179       <varlistentry>
 180         <term><option>--recursive=</option></term>
 181
 182         <listitem><para>Controls whether the number of tasks shown for
 183         a control group shall include all tasks that are contained in
 184         any of the child control groups as well. Takes a boolean
 185         argument, defaults to <literal>yes</literal>. If enabled the
 186         tasks in child control groups are included, if disabled only
 187         the tasks in the control group itself are
 188         counted.</para></listitem>
 189       </varlistentry>
 190
 191       <varlistentry>
 192         <term><option>-n</option></term>
 193         <term><option>--iterations=</option></term>
 194
 195         <listitem><para>Perform only this many iterations. A value of 0
 196         indicates that the program should run indefinitely.</para></listitem>
 197       </varlistentry>
 198
 199       <varlistentry>
 200         <term><option>-d</option></term>
 201         <term><option>--delay=</option></term>
 202
 203         <listitem><para>Specify refresh delay in seconds (or if one of
 204         <literal>ms</literal>,
 205         <literal>us</literal>,
 206         <literal>min</literal> is specified as unit in this time
 207         unit).</para></listitem>
 208       </varlistentry>
 209
 210       <varlistentry>
 211         <term><option>--depth=</option></term>
 212
 213         <listitem><para>Maximum control group tree traversal depth.
 214         Specifies how deep <command>systemd-cgtop</command> shall
 215         traverse the control group hierarchies. If 0 is specified,
 216         only the root group is monitored. For 1, only the first level
 217         of control groups is monitored, and so on. Defaults to
 218         3.</para></listitem>
 219       </varlistentry>
 220
 221       <xi:include href="standard-options.xml" xpointer="help" />
 222       <xi:include href="standard-options.xml" xpointer="version" />
 223     </variablelist>
 224
 225   </refsect1>
 226
 227   <refsect1>
 228     <title>Keys</title>
 229
 230     <para><command>systemd-cgtop</command> is an interactive tool and
 231     may be controlled via user input using the following keys:</para>
 232
 233     <variablelist>
 234       <varlistentry>
 235         <term>h</term>
 236
 237         <listitem><para>Shows a short help text.</para></listitem>
 238       </varlistentry>
 239
 240       <varlistentry>
 241         <term>SPACE</term>
 242
 243         <listitem><para>Immediately refresh output.</para></listitem>
 244       </varlistentry>
 245
 246       <varlistentry>
 247         <term>q</term>
 248
 249         <listitem><para>Terminate the program.</para></listitem>
 250       </varlistentry>
 251
 252
 253       <varlistentry>
 254         <term>p</term>
 255         <term>t</term>
 256         <term>c</term>
 257         <term>m</term>
 258         <term>i</term>
 259
 260         <listitem><para>Sort the control groups by path, number of
 261         tasks, CPU load, memory usage, or IO load, respectively.
 262         </para></listitem>
 263       </varlistentry>
 264
 265       <varlistentry>
 266         <term>%</term>
 267
 268         <listitem><para>Toggle between showing CPU time as time or
 269         percentage.</para></listitem>
 270       </varlistentry>
 271
 272       <varlistentry>
 273         <term>+</term>
 274         <term>-</term>
 275
 276         <listitem><para>Increase or decrease refresh delay,
 277         respectively.</para></listitem>
 278       </varlistentry>
 279
 280       <varlistentry>
 281         <term>k</term>
 282
 283         <listitem><para>Toggle between including or excluding kernel
 284         threads in control group task counts.</para></listitem>
 285       </varlistentry>
 286
 287       <varlistentry>
 288         <term>r</term>
 289
 290         <listitem><para>Toggle between recursively including or
 291         excluding tasks in child control groups in control group task
 292         counts.</para></listitem>
 293       </varlistentry>
 294
 295     </variablelist>
 296   </refsect1>
 297
 298   <refsect1>
 299     <title>Exit status</title>
 300
 301     <para>On success, 0 is returned, a non-zero failure code
 302     otherwise.</para>
 303   </refsect1>
 304
 305   <refsect1>
 306     <title>See Also</title>
 307     <para>
 308       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 309       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 310       <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 311       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 312       <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 313     </para>
 314   </refsect1>
 315
 316 </refentry>