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