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 <!ENTITY % entities SYSTEM "custom-entities.ent" >
   5 %entities;
   6 ]>
   7
   8 <!--
   9   This file is part of systemd.
  10
  11   Copyright 2012 Lennart Poettering
  12
  13   systemd is free software; you can redistribute it and/or modify it
  14   under the terms of the GNU Lesser General Public License as published by
  15   the Free Software Foundation; either version 2.1 of the License, or
  16   (at your option) any later version.
  17
  18   systemd is distributed in the hope that it will be useful, but
  19   WITHOUT ANY WARRANTY; without even the implied warranty of
  20   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  21   Lesser General Public License for more details.
  22
  23   You should have received a copy of the GNU Lesser General Public License
  24   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  25 -->
  26
  27 <refentry id="systemd-cgtop"
  28     xmlns:xi="http://www.w3.org/2001/XInclude">
  29
  30   <refentryinfo>
  31     <title>systemd-cgtop</title>
  32     <productname>systemd</productname>
  33
  34     <authorgroup>
  35       <author>
  36         <contrib>Developer</contrib>
  37         <firstname>Lennart</firstname>
  38         <surname>Poettering</surname>
  39         <email>lennart@poettering.net</email>
  40       </author>
  41     </authorgroup>
  42   </refentryinfo>
  43
  44   <refmeta>
  45     <refentrytitle>systemd-cgtop</refentrytitle>
  46     <manvolnum>1</manvolnum>
  47   </refmeta>
  48
  49   <refnamediv>
  50     <refname>systemd-cgtop</refname>
  51     <refpurpose>Show top control groups by their resource usage</refpurpose>
  52   </refnamediv>
  53
  54   <refsynopsisdiv>
  55     <cmdsynopsis>
  56       <command>systemd-cgtop</command>
  57       <arg choice="opt" rep="repeat">OPTIONS</arg>
  58     </cmdsynopsis>
  59   </refsynopsisdiv>
  60
  61   <refsect1>
  62     <title>Description</title>
  63
  64     <para><command>systemd-cgtop</command> shows the top control
  65     groups of the local Linux control group hierarchy, ordered by
  66     their CPU, memory, or disk I/O load. The display is refreshed in
  67     regular intervals (by default every 1s), similar in style to
  68     <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
  69
  70     <para>If <command>systemd-cgtop</command> is not connected to a tty, no
  71     column headers are printed and the default is to only run one iteration.
  72     The <varname>--iterations</varname> argument, if given, is still honored.
  73     This mode is suitable for scripting.</para>
  74
  75     <para>Resource usage is only accounted for control groups in the
  76     relevant hierarchy, i.e. CPU usage is only accounted for control
  77     groups in the <literal>cpuacct</literal> hierarchy, memory usage
  78     only for those in <literal>memory</literal> and disk I/O usage for
  79     those in <literal>blkio</literal>. If resource monitoring for
  80     these resources is required, it is recommended to add the
  81     <varname>CPUAccounting=1</varname>,
  82     <varname>MemoryAccounting=1</varname> and
  83     <varname>BlockIOAccounting=1</varname> settings in the unit files
  84     in question. See
  85     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  86     for details.</para>
  87
  88     <para>The CPU load value can be between 0 and 100 times the number of
  89     processors the system has. For example, if the system has 8 processors,
  90     the CPU load value is going to be between 0% and 800%. The number of
  91     processors can be found in <literal>/proc/cpuinfo</literal>.</para>
  92
  93     <para>To emphasize this: unless
  94     <literal>CPUAccounting=1</literal>,
  95     <literal>MemoryAccounting=1</literal> and
  96     <literal>BlockIOAccounting=1</literal> are enabled for the
  97     services in question, no resource accounting will be available for
  98     system services and the data shown by
  99     <command>systemd-cgtop</command> will be incomplete.</para>
 100   </refsect1>
 101
 102   <refsect1>
 103     <title>Options</title>
 104
 105     <para>The following options are understood:</para>
 106
 107     <variablelist>
 108       <varlistentry>
 109         <term><option>-p</option></term>
 110
 111         <listitem><para>Order by control group
 112         path name.</para></listitem>
 113       </varlistentry>
 114
 115       <varlistentry>
 116         <term><option>-t</option></term>
 117
 118         <listitem><para>Order by number of tasks in control group
 119         (i.e. threads and processes).</para></listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term><option>-c</option></term>
 124
 125         <listitem><para>Order by CPU load.</para></listitem>
 126       </varlistentry>
 127
 128       <varlistentry>
 129         <term><option>-m</option></term>
 130
 131         <listitem><para>Order by memory usage.</para></listitem>
 132       </varlistentry>
 133
 134       <varlistentry>
 135         <term><option>-i</option></term>
 136
 137         <listitem><para>Order by disk I/O load.</para></listitem>
 138       </varlistentry>
 139
 140       <varlistentry>
 141         <term><option>-b</option></term>
 142         <term><option>--batch</option></term>
 143
 144         <listitem><para>Run in "batch" mode: do not accept input and
 145         run until the iteration limit set with
 146         <option>--iterations</option> is exhausted or until killed.
 147         This mode could be useful for sending output from
 148         <command>systemd-cgtop</command> to other programs or to a
 149         file.</para></listitem>
 150       </varlistentry>
 151
 152       <varlistentry>
 153         <term><option>-r</option></term>
 154         <term><option>--raw</option></term>
 155
 156         <listitem><para>Format byte counts (as in memory usage and IO metrics)
 157         with raw numeric values rather than human-readable
 158         numbers.</para></listitem>
 159       </varlistentry>
 160
 161       <varlistentry>
 162         <term><option>-n</option></term>
 163         <term><option>--iterations=</option></term>
 164
 165         <listitem><para>Perform only this many iterations. A value of 0
 166         indicates that the program should run indefinitely.</para></listitem>
 167       </varlistentry>
 168
 169       <varlistentry>
 170         <term><option>-d</option></term>
 171         <term><option>--delay=</option></term>
 172
 173         <listitem><para>Specify refresh delay in seconds (or if one of
 174         <literal>ms</literal>,
 175         <literal>us</literal>,
 176         <literal>min</literal> is specified as unit in this time
 177         unit).</para></listitem>
 178       </varlistentry>
 179
 180       <varlistentry>
 181         <term><option>--depth=</option></term>
 182
 183         <listitem><para>Maximum control group tree traversal depth.
 184         Specifies how deep <command>systemd-cgtop</command> shall
 185         traverse the control group hierarchies. If 0 is specified,
 186         only the root group is monitored. For 1, only the first level
 187         of control groups is monitored, and so on. Defaults to
 188         3.</para></listitem>
 189       </varlistentry>
 190
 191       <xi:include href="standard-options.xml" xpointer="help" />
 192       <xi:include href="standard-options.xml" xpointer="version" />
 193     </variablelist>
 194
 195   </refsect1>
 196
 197
 198   <refsect1>
 199     <title>Keys</title>
 200
 201     <para><command>systemd-cgtop</command> is an interactive tool and
 202     may be controlled via user input using the following keys:</para>
 203
 204     <variablelist>
 205       <varlistentry>
 206         <term>h</term>
 207
 208         <listitem><para>Shows a short help text.</para></listitem>
 209       </varlistentry>
 210
 211       <varlistentry>
 212         <term>SPACE</term>
 213
 214         <listitem><para>Immediately refresh output.</para></listitem>
 215       </varlistentry>
 216
 217       <varlistentry>
 218         <term>q</term>
 219
 220         <listitem><para>Terminate the program.</para></listitem>
 221       </varlistentry>
 222
 223
 224       <varlistentry>
 225         <term>p</term>
 226         <term>t</term>
 227         <term>c</term>
 228         <term>m</term>
 229         <term>i</term>
 230
 231         <listitem><para>Sort the control groups by path, number of
 232         tasks, CPU load, memory usage, or IO load, respectively.
 233         </para></listitem>
 234       </varlistentry>
 235
 236       <varlistentry>
 237         <term>%</term>
 238
 239         <listitem><para>Toggle between showing CPU time as time or
 240         percentage.</para></listitem>
 241       </varlistentry>
 242
 243       <varlistentry>
 244         <term>+</term>
 245         <term>-</term>
 246
 247         <listitem><para>Increase or decrease refresh delay,
 248         respectively.</para></listitem>
 249       </varlistentry>
 250
 251     </variablelist>
 252   </refsect1>
 253
 254   <refsect1>
 255     <title>Exit status</title>
 256
 257     <para>On success, 0 is returned, a non-zero failure code
 258     otherwise.</para>
 259   </refsect1>
 260
 261   <refsect1>
 262     <title>See Also</title>
 263     <para>
 264       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 265       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 266       <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 267       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 268       <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 269     </para>
 270   </refsect1>
 271
 272 </refentry>