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