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