man/systemd-cgtop.xml

   1 <?xml version='1.0'?> <!--*-nxml-*-->
   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
  26         <refentryinfo>
  27                 <title>systemd-cgtop</title>
  28                 <productname>systemd</productname>
  29
  30                 <authorgroup>
  31                         <author>
  32                                 <contrib>Developer</contrib>
  33                                 <firstname>Lennart</firstname>
  34                                 <surname>Poettering</surname>
  35                                 <email>lennart@poettering.net</email>
  36                         </author>
  37                 </authorgroup>
  38         </refentryinfo>
  39
  40         <refmeta>
  41                 <refentrytitle>systemd-cgtop</refentrytitle>
  42                 <manvolnum>1</manvolnum>
  43         </refmeta>
  44
  45         <refnamediv>
  46                 <refname>systemd-cgtop</refname>
  47                 <refpurpose>Show top control groups by their resource usage</refpurpose>
  48         </refnamediv>
  49
  50         <refsynopsisdiv>
  51                 <cmdsynopsis>
  52                         <command>systemd-cgtop</command>
  53                         <arg choice="opt" rep="repeat">OPTIONS</arg>
  54                 </cmdsynopsis>
  55         </refsynopsisdiv>
  56
  57         <refsect1>
  58                 <title>Description</title>
  59
  60                 <para><command>systemd-cgtop</command> shows the top
  61                 control groups of the local Linux control group
  62                 hierarchy, ordered by their CPU, memory, or disk I/O load. The
  63                 display is refreshed in regular intervals (by default
  64                 every 1s), similar in style to
  65                 <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
  66                 If <command>systemd-cgtop</command> is not connected
  67                 to a tty, only one iteration is performed and no
  68                 columns headers are printed. This mode is suitable for
  69                 scripting.</para>
  70
  71                 <para>Resource usage is only accounted for control
  72                 groups in the relevant hierarchy, i.e. CPU usage is
  73                 only accounted for control groups in the
  74                 <literal>cpuacct</literal> hierarchy, memory usage
  75                 only for those in <literal>memory</literal> and disk
  76                 I/O usage for those in
  77                 <literal>blkio</literal>. <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
  78                 by default places all services in their own control
  79                 group in the <literal>cpuacct</literal> hierarchy, but
  80                 not in <literal>memory</literal> nor
  81                 <literal>blkio</literal>. If resource monitoring for
  82                 these resources is required it is recommended to add
  83                 <literal>blkio</literal> and <literal>memory</literal>
  84                 to the <varname>DefaultControllers=</varname> setting
  85                 in <filename>/etc/systemd/system.conf</filename> (see
  86                 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  87                 for details). Alternatively, it is possible to enable
  88                 resource accounting individually for services, by
  89                 making use of the <varname>ControlGroup=</varname>
  90                 option in the unit files (See
  91                 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  92                 for details).</para>
  93
  94                 <para>To emphasize this: unless
  95                 <literal>blkio</literal> and <literal>memory</literal>
  96                 are enabled for the services in question with either
  97                 of the options suggested above no resource accounting
  98                 will be available for system services and the data shown
  99                 by <command>systemd-cgtop</command> will be
 100                 incomplete.</para>
 101         </refsect1>
 102
 103         <refsect1>
 104                 <title>Options</title>
 105
 106                 <para>The following options are understood:</para>
 107
 108                 <variablelist>
 109                         <varlistentry>
 110                                 <term><option>-h</option></term>
 111                                 <term><option>--help</option></term>
 112
 113                                 <listitem><para>Prints a short help
 114                                 text and exits.</para></listitem>
 115                         </varlistentry>
 116
 117                         <varlistentry>
 118                                 <term><option>--version</option></term>
 119
 120                                 <listitem><para>Prints a version string and
 121                                 exits.</para></listitem>
 122                         </varlistentry>
 123
 124                         <varlistentry>
 125                                 <term><option>-p</option></term>
 126
 127                                 <listitem><para>Order by control group
 128                                 path name.</para></listitem>
 129                         </varlistentry>
 130
 131                         <varlistentry>
 132                                 <term><option>-t</option></term>
 133
 134                                 <listitem><para>Order by number of
 135                                 tasks in control
 136                                 group (i.e. threads and processes).</para></listitem>
 137                         </varlistentry>
 138
 139                         <varlistentry>
 140                                 <term><option>-c</option></term>
 141
 142                                 <listitem><para>Order by CPU load.</para></listitem>
 143                         </varlistentry>
 144
 145                         <varlistentry>
 146                                 <term><option>-m</option></term>
 147
 148                                 <listitem><para>Order by memory usage.</para></listitem>
 149                         </varlistentry>
 150
 151                         <varlistentry>
 152                                 <term><option>-i</option></term>
 153
 154                                 <listitem><para>Order by disk I/O load.</para></listitem>
 155                         </varlistentry>
 156
 157                         <varlistentry>
 158                                 <term><option>-b</option></term>
 159                                 <term><option>--batch</option></term>
 160
 161                                 <listitem><para>Run in "batch" mode:
 162                                 do not accept input and run until the
 163                                 iteration limit set with
 164                                 <option>--iterations</option> is
 165                                 exhausted or until killed. This mode
 166                                 could be useful for sending output
 167                                 from <command>systemd-cgtop</command>
 168                                 to other programs or to a
 169                                 file.</para></listitem>
 170                         </varlistentry>
 171
 172                         <varlistentry>
 173                                 <term><option>-n</option></term>
 174                                 <term><option>--iterations=</option></term>
 175
 176                                 <listitem><para>Perform only this many
 177                                 iterations.</para></listitem>
 178                         </varlistentry>
 179
 180                         <varlistentry>
 181                                 <term><option>-d</option></term>
 182                                 <term><option>--delay=</option></term>
 183
 184                                 <listitem><para>Specify refresh delay
 185                                 in seconds (or if one of
 186                                 <literal>ms</literal>,
 187                                 <literal>us</literal>,
 188                                 <literal>min</literal> is specified as
 189                                 unit in this time
 190                                 unit).</para></listitem>
 191                         </varlistentry>
 192
 193                         <varlistentry>
 194                                 <term><option>--depth=</option></term>
 195
 196                                 <listitem><para>Maximum control group
 197                                 tree traversal depth. Specifies how
 198                                 deep <command>systemd-cgtop</command>
 199                                 shall traverse the control group
 200                                 hierarchies. If 0 is specified only
 201                                 the root group is monitored, for 1
 202                                 only the first level of control groups
 203                                 is monitored, and so on. Defaults to
 204                                 3.</para></listitem>
 205                         </varlistentry>
 206
 207                 </variablelist>
 208
 209         </refsect1>
 210
 211
 212         <refsect1>
 213                 <title>Keys</title>
 214
 215                 <para><command>systemd-cgtop</command> is an
 216                 interactive tool and may be controlled via user input
 217                 using the following keys:</para>
 218
 219                 <variablelist>
 220                         <varlistentry>
 221                                 <term>h</term>
 222
 223                                 <listitem><para>Shows a short help text.</para></listitem>
 224                         </varlistentry>
 225
 226                         <varlistentry>
 227                                 <term>SPACE</term>
 228
 229                                 <listitem><para>Immediately refresh output.</para></listitem>
 230                         </varlistentry>
 231
 232                         <varlistentry>
 233                                 <term>q</term>
 234
 235                                 <listitem><para>Terminate the program.</para></listitem>
 236                         </varlistentry>
 237
 238
 239                         <varlistentry>
 240                                 <term>p</term>
 241                                 <term>t</term>
 242                                 <term>c</term>
 243                                 <term>m</term>
 244                                 <term>i</term>
 245
 246                                 <listitem><para>Sort the control groups
 247                                 by path, number of tasks, CPU load,
 248                                 memory usage, or IO
 249                                 load, respectively.</para></listitem>
 250                         </varlistentry>
 251
 252                         <varlistentry>
 253                                 <term>%</term>
 254
 255                                 <listitem><para>Toggle between showing CPU time as
 256                                 time or percentage.</para></listitem>
 257                         </varlistentry>
 258
 259                         <varlistentry>
 260                                 <term>+</term>
 261                                 <term>-</term>
 262
 263                                 <listitem><para>Increase
 264                                 or decrease refresh
 265                                 delay, respectively.</para></listitem>
 266                         </varlistentry>
 267
 268                 </variablelist>
 269         </refsect1>
 270
 271         <refsect1>
 272                 <title>Exit status</title>
 273
 274                 <para>On success 0 is returned, a non-zero failure
 275                 code otherwise.</para>
 276         </refsect1>
 277
 278         <refsect1>
 279                 <title>See Also</title>
 280                 <para>
 281                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 282                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 283                         <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 284                         <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 285                 </para>
 286         </refsect1>
 287
 288 </refentry>