man/systemd-cgtop.xml

   1 <?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
   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   SPDX-License-Identifier: LGPL-2.1+
   7
   8   This file is part of systemd.
   9
  10   Copyright 2012 Lennart Poettering
  11
  12   systemd is free software; you can redistribute it and/or modify it
  13   under the terms of the GNU Lesser General Public License as published by
  14   the Free Software Foundation; either version 2.1 of the License, or
  15   (at your option) any later version.
  16
  17   systemd is distributed in the hope that it will be useful, but
  18   WITHOUT ANY WARRANTY; without even the implied warranty of
  19   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  20   Lesser General Public License for more details.
  21
  22   You should have received a copy of the GNU Lesser General Public License
  23   along with systemd; If not, see <http://www.gnu.org/licenses/>.
  24 -->
  25
  26 <refentry id="systemd-cgtop"
  27     xmlns:xi="http://www.w3.org/2001/XInclude">
  28
  29   <refentryinfo>
  30     <title>systemd-cgtop</title>
  31     <productname>systemd</productname>
  32
  33     <authorgroup>
  34       <author>
  35         <contrib>Developer</contrib>
  36         <firstname>Lennart</firstname>
  37         <surname>Poettering</surname>
  38         <email>lennart@poettering.net</email>
  39       </author>
  40     </authorgroup>
  41   </refentryinfo>
  42
  43   <refmeta>
  44     <refentrytitle>systemd-cgtop</refentrytitle>
  45     <manvolnum>1</manvolnum>
  46   </refmeta>
  47
  48   <refnamediv>
  49     <refname>systemd-cgtop</refname>
  50     <refpurpose>Show top control groups by their resource usage</refpurpose>
  51   </refnamediv>
  52
  53   <refsynopsisdiv>
  54     <cmdsynopsis>
  55       <command>systemd-cgtop</command>
  56       <arg choice="opt" rep="repeat">OPTIONS</arg>
  57       <arg choice="opt">GROUP</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>.
  69     If a control group path is specified, shows only the services of
  70     the specified control group.</para>
  71
  72     <para>If <command>systemd-cgtop</command> is not connected to a
  73     tty, no column headers are printed and the default is to only run
  74     one iteration.  The <varname>--iterations=</varname> argument, if
  75     given, is honored. This mode is suitable for scripting.</para>
  76
  77     <para>Resource usage is only accounted for control groups in the
  78     relevant hierarchy, i.e. CPU usage is only accounted for control
  79     groups in the <literal>cpuacct</literal> hierarchy, memory usage
  80     only for those in <literal>memory</literal> and disk I/O usage for
  81     those in <literal>blkio</literal>. If resource monitoring for
  82     these resources is required, it is recommended to add the
  83     <varname>CPUAccounting=1</varname>,
  84     <varname>MemoryAccounting=1</varname> and
  85     <varname>BlockIOAccounting=1</varname> settings in the unit files
  86     in question. See
  87     <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
  88     for details.</para>
  89
  90     <para>The CPU load value can be between 0 and 100 times the number of
  91     processors the system has. For example, if the system has 8 processors,
  92     the CPU load value is going to be between 0% and 800%. The number of
  93     processors can be found in <literal>/proc/cpuinfo</literal>.</para>
  94
  95     <para>To emphasize this: unless
  96     <literal>CPUAccounting=1</literal>,
  97     <literal>MemoryAccounting=1</literal> and
  98     <literal>BlockIOAccounting=1</literal> are enabled for the
  99     services in question, no resource accounting will be available for
 100     system services and the data shown by
 101     <command>systemd-cgtop</command> will be incomplete.</para>
 102   </refsect1>
 103
 104   <refsect1>
 105     <title>Options</title>
 106
 107     <para>The following options are understood:</para>
 108
 109     <variablelist>
 110       <varlistentry>
 111         <term><option>-p</option></term>
 112         <term><option>--order=path</option></term>
 113
 114         <listitem><para>Order by control group
 115         path name.</para></listitem>
 116       </varlistentry>
 117
 118       <varlistentry>
 119         <term><option>-t</option></term>
 120         <term><option>--order=tasks</option></term>
 121
 122         <listitem><para>Order by number of tasks/processes in the control group.</para></listitem>
 123       </varlistentry>
 124
 125       <varlistentry>
 126         <term><option>-c</option></term>
 127         <term><option>--order=cpu</option></term>
 128
 129         <listitem><para>Order by CPU load.</para></listitem>
 130       </varlistentry>
 131
 132       <varlistentry>
 133         <term><option>-m</option></term>
 134         <term><option>--order=memory</option></term>
 135
 136         <listitem><para>Order by memory usage.</para></listitem>
 137       </varlistentry>
 138
 139       <varlistentry>
 140         <term><option>-i</option></term>
 141         <term><option>--order=io</option></term>
 142
 143         <listitem><para>Order by disk I/O load.</para></listitem>
 144       </varlistentry>
 145
 146       <varlistentry>
 147         <term><option>-b</option></term>
 148         <term><option>--batch</option></term>
 149
 150         <listitem><para>Run in "batch" mode: do not accept input and
 151         run until the iteration limit set with
 152         <option>--iterations=</option> is exhausted or until killed.
 153         This mode could be useful for sending output from
 154         <command>systemd-cgtop</command> to other programs or to a
 155         file.</para></listitem>
 156       </varlistentry>
 157
 158       <varlistentry>
 159         <term><option>-r</option></term>
 160         <term><option>--raw</option></term>
 161
 162         <listitem><para>Format byte counts (as in memory usage and I/O metrics)
 163         with raw numeric values rather than human-readable
 164         numbers.</para></listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term><option>--cpu=percentage</option></term>
 169         <term><option>--cpu=time</option></term>
 170
 171         <listitem><para>Controls whether the CPU usage is shown as
 172         percentage or time. By default, the CPU usage is shown as
 173         percentage. This setting may also be toggled at runtime by
 174         pressing the <keycap>%</keycap> key.</para></listitem>
 175       </varlistentry>
 176
 177       <varlistentry>
 178         <term><option>-P</option></term>
 179
 180         <listitem><para>Count only userspace processes instead of all
 181         tasks. By default, all tasks are counted: each kernel thread
 182         and each userspace thread individually. With this setting,
 183         kernel threads are excluded from the counting and each
 184         userspace process only counts as one, regardless how many
 185         threads it consists of. This setting may also be toggled at
 186         runtime by pressing the <keycap>P</keycap> key. This option
 187         may not be combined with
 188         <option>-k</option>.</para></listitem>
 189       </varlistentry>
 190
 191       <varlistentry>
 192         <term><option>-k</option></term>
 193
 194         <listitem><para>Count only userspace processes and kernel
 195         threads instead of all tasks. By default, all tasks are
 196         counted: each kernel thread and each userspace thread
 197         individually. With this setting, kernel threads are included in
 198         the counting and each userspace process only counts as on one,
 199         regardless how many threads it consists of. This setting may
 200         also be toggled at runtime by pressing the <keycap>k</keycap>
 201         key. This option may not be combined with
 202         <option>-P</option>.</para></listitem>
 203       </varlistentry>
 204
 205       <varlistentry>
 206         <term><option>--recursive=</option></term>
 207
 208         <listitem><para>Controls whether the number of processes shown
 209         for a control group shall include all processes that are
 210         contained in any of the child control groups as well. Takes a
 211         boolean argument, which defaults to <literal>yes</literal>. If
 212         enabled, the processes in child control groups are included, if
 213         disabled, only the processes in the control group itself are
 214         counted. This setting may also be toggled at runtime by
 215         pressing the <keycap>r</keycap> key. Note that this setting
 216         only applies to process counting, i.e. when the
 217         <option>-P</option> or <option>-k</option> options are
 218         used. It has not effect if all tasks are counted, in which
 219         case the counting is always recursive.</para></listitem>
 220       </varlistentry>
 221
 222       <varlistentry>
 223         <term><option>-n</option></term>
 224         <term><option>--iterations=</option></term>
 225
 226         <listitem><para>Perform only this many iterations. A value of
 227         0 indicates that the program should run
 228         indefinitely.</para></listitem>
 229       </varlistentry>
 230
 231       <varlistentry>
 232         <term><option>-1</option></term>
 233
 234         <listitem><para>A shortcut for <option>--iterations=1</option>.</para></listitem>
 235       </varlistentry>
 236
 237       <varlistentry>
 238         <term><option>-d</option></term>
 239         <term><option>--delay=</option></term>
 240
 241         <listitem><para>Specify refresh delay in seconds (or if one of
 242         <literal>ms</literal>, <literal>us</literal>,
 243         <literal>min</literal> is specified as unit in this time
 244         unit). This setting may also be increased and decreased at
 245         runtime by pressing the <keycap>+</keycap> and
 246         <keycap>-</keycap> keys.</para></listitem>
 247       </varlistentry>
 248
 249       <varlistentry>
 250         <term><option>--depth=</option></term>
 251
 252         <listitem><para>Maximum control group tree traversal depth.
 253         Specifies how deep <command>systemd-cgtop</command> shall
 254         traverse the control group hierarchies. If 0 is specified,
 255         only the root group is monitored. For 1, only the first level
 256         of control groups is monitored, and so on. Defaults to
 257         3.</para></listitem>
 258       </varlistentry>
 259
 260       <varlistentry>
 261         <term><option>-M <replaceable>MACHINE</replaceable></option></term>
 262         <term><option>--machine=<replaceable>MACHINE</replaceable></option></term>
 263
 264         <listitem><para>Limit control groups shown to the part
 265         corresponding to the container
 266         <replaceable>MACHINE</replaceable>.
 267         This option may not be used when a control group path is specified.</para></listitem>
 268       </varlistentry>
 269
 270       <xi:include href="standard-options.xml" xpointer="help" />
 271       <xi:include href="standard-options.xml" xpointer="version" />
 272     </variablelist>
 273
 274   </refsect1>
 275
 276   <refsect1>
 277     <title>Keys</title>
 278
 279     <para><command>systemd-cgtop</command> is an interactive tool and
 280     may be controlled via user input using the following keys:</para>
 281
 282     <variablelist>
 283       <varlistentry>
 284         <term><keycap>h</keycap></term>
 285
 286         <listitem><para>Shows a short help text.</para></listitem>
 287       </varlistentry>
 288
 289       <varlistentry>
 290         <term><keycap function="space"/></term>
 291
 292         <listitem><para>Immediately refresh output.</para></listitem>
 293       </varlistentry>
 294
 295       <varlistentry>
 296         <term><keycap>q</keycap></term>
 297
 298         <listitem><para>Terminate the program.</para></listitem>
 299       </varlistentry>
 300
 301       <varlistentry>
 302         <term><keycap>p</keycap></term>
 303         <term><keycap>t</keycap></term>
 304         <term><keycap>c</keycap></term>
 305         <term><keycap>m</keycap></term>
 306         <term><keycap>i</keycap></term>
 307
 308         <listitem><para>Sort the control groups by path, number of
 309         tasks, CPU load, memory usage, or I/O load, respectively.  This
 310         setting may also be controlled using the
 311         <option>--order=</option> command line
 312         switch.</para></listitem>
 313       </varlistentry>
 314
 315       <varlistentry>
 316         <term><keycap>%</keycap></term>
 317
 318         <listitem><para>Toggle between showing CPU time as time or
 319         percentage. This setting may also be controlled using the
 320         <option>--cpu=</option> command line switch.</para></listitem>
 321       </varlistentry>
 322
 323       <varlistentry>
 324         <term><keycap>+</keycap></term>
 325         <term><keycap>-</keycap></term>
 326
 327         <listitem><para>Increase or decrease refresh delay,
 328         respectively. This setting may also be controlled using the
 329         <option>--delay=</option> command line
 330         switch.</para></listitem>
 331       </varlistentry>
 332
 333       <varlistentry>
 334         <term><keycap>P</keycap></term>
 335
 336         <listitem><para>Toggle between counting all tasks, or only
 337         userspace processes. This setting may also be controlled using
 338         the <option>-P</option> command line switch (see
 339         above).</para></listitem>
 340       </varlistentry>
 341
 342       <varlistentry>
 343         <term><keycap>k</keycap></term>
 344
 345         <listitem><para>Toggle between counting all tasks, or only
 346         userspace processes and kernel threads. This setting may also
 347         be controlled using the <option>-k</option> command line
 348         switch (see above).</para></listitem>
 349       </varlistentry>
 350
 351       <varlistentry>
 352         <term><keycap>r</keycap></term>
 353
 354         <listitem><para>Toggle between recursively including or
 355         excluding processes in child control groups in control group
 356         process counts. This setting may also be controlled using the
 357         <option>--recursive=</option> command line switch. This key is
 358         not available if all tasks are counted, it is only available
 359         if processes are counted, as enabled with the
 360         <keycap>P</keycap> or <keycap>k</keycap>
 361         keys.</para></listitem>
 362       </varlistentry>
 363
 364     </variablelist>
 365   </refsect1>
 366
 367   <refsect1>
 368     <title>Exit status</title>
 369
 370     <para>On success, 0 is returned, a non-zero failure code
 371     otherwise.</para>
 372   </refsect1>
 373
 374   <refsect1>
 375     <title>See Also</title>
 376     <para>
 377       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 378       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 379       <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 380       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 381       <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 382     </para>
 383   </refsect1>
 384
 385 </refentry>