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>-p</option></term>
 114
 115                                 <listitem><para>Order by control group
 116                                 path name.</para></listitem>
 117                         </varlistentry>
 118
 119                         <varlistentry>
 120                                 <term><option>-t</option></term>
 121
 122                                 <listitem><para>Order by number of
 123                                 tasks in control
 124                                 group (i.e. threads and processes).</para></listitem>
 125                         </varlistentry>
 126
 127                         <varlistentry>
 128                                 <term><option>-c</option></term>
 129
 130                                 <listitem><para>Order by CPU load.</para></listitem>
 131                         </varlistentry>
 132
 133                         <varlistentry>
 134                                 <term><option>-m</option></term>
 135
 136                                 <listitem><para>Order by memory usage.</para></listitem>
 137                         </varlistentry>
 138
 139                         <varlistentry>
 140                                 <term><option>-i</option></term>
 141
 142                                 <listitem><para>Order by disk I/O load.</para></listitem>
 143                         </varlistentry>
 144
 145                         <varlistentry>
 146                                 <term><option>-d</option></term>
 147                                 <term><option>--delay=</option></term>
 148
 149                                 <listitem><para>Specify refresh delay
 150                                 in seconds (or if one of
 151                                 <literal>ms</literal>,
 152                                 <literal>us</literal>,
 153                                 <literal>min</literal> is specified as
 154                                 unit in this time
 155                                 unit).</para></listitem>
 156                         </varlistentry>
 157
 158                         <varlistentry>
 159                                 <term><option>--depth=</option></term>
 160
 161                                 <listitem><para>Maximum control group
 162                                 tree traversal depth. Specifies how
 163                                 deep <command>systemd-cgtop</command>
 164                                 shall traverse the control group
 165                                 hierarchies. If 0 is specified only
 166                                 the root group is monitored, for 1
 167                                 only the first level of control groups
 168                                 is monitored, and so on. Defaults to
 169                                 3.</para></listitem>
 170                         </varlistentry>
 171
 172                 </variablelist>
 173
 174         </refsect1>
 175
 176
 177         <refsect1>
 178                 <title>Keys</title>
 179
 180                 <para><command>systemd-cgtop</command> is an
 181                 interactive tool and may be controlled via user input
 182                 using the following keys:</para>
 183
 184                 <variablelist>
 185                         <varlistentry>
 186                                 <term>h</term>
 187
 188                                 <listitem><para>Shows a short help text.</para></listitem>
 189                         </varlistentry>
 190
 191                         <varlistentry>
 192                                 <term>SPACE</term>
 193
 194                                 <listitem><para>Immediately refresh output.</para></listitem>
 195                         </varlistentry>
 196
 197                         <varlistentry>
 198                                 <term>q</term>
 199
 200                                 <listitem><para>Terminate the program.</para></listitem>
 201                         </varlistentry>
 202
 203
 204                         <varlistentry>
 205                                 <term>p</term>
 206                                 <term>t</term>
 207                                 <term>c</term>
 208                                 <term>m</term>
 209                                 <term>i</term>
 210
 211                                 <listitem><para>Change ordering of control groups
 212                                 by path, number of tasks, CPU load,
 213                                 memory usage resp. IO
 214                                 load.</para></listitem>
 215                         </varlistentry>
 216
 217                         <varlistentry>
 218                                 <term>+</term>
 219                                 <term>-</term>
 220
 221                                 <listitem><para>Increase,
 222                                 resp. decrease refresh
 223                                 delay.</para></listitem>
 224                         </varlistentry>
 225
 226                 </variablelist>
 227         </refsect1>
 228
 229         <refsect1>
 230                 <title>Exit status</title>
 231
 232                 <para>On success 0 is returned, a non-zero failure
 233                 code otherwise.</para>
 234         </refsect1>
 235
 236         <refsect1>
 237                 <title>See Also</title>
 238                 <para>
 239                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 240                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 241                         <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 242                         <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 243                 </para>
 244         </refsect1>
 245
 246 </refentry>