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>-d</option></term>
 233         <term><option>--delay=</option></term>
 234
 235         <listitem><para>Specify refresh delay in seconds (or if one of
 236         <literal>ms</literal>, <literal>us</literal>,
 237         <literal>min</literal> is specified as unit in this time
 238         unit). This setting may also be increased and decreased at
 239         runtime by pressing the <keycap>+</keycap> and
 240         <keycap>-</keycap> keys.</para></listitem>
 241       </varlistentry>
 242
 243       <varlistentry>
 244         <term><option>--depth=</option></term>
 245
 246         <listitem><para>Maximum control group tree traversal depth.
 247         Specifies how deep <command>systemd-cgtop</command> shall
 248         traverse the control group hierarchies. If 0 is specified,
 249         only the root group is monitored. For 1, only the first level
 250         of control groups is monitored, and so on. Defaults to
 251         3.</para></listitem>
 252       </varlistentry>
 253
 254       <varlistentry>
 255         <term><option>-M <replaceable>MACHINE</replaceable></option></term>
 256         <term><option>--machine=<replaceable>MACHINE</replaceable></option></term>
 257
 258         <listitem><para>Limit control groups shown to the part
 259         corresponding to the container
 260         <replaceable>MACHINE</replaceable>.
 261         This option may not be used when a control group path is specified.</para></listitem>
 262       </varlistentry>
 263
 264       <xi:include href="standard-options.xml" xpointer="help" />
 265       <xi:include href="standard-options.xml" xpointer="version" />
 266     </variablelist>
 267
 268   </refsect1>
 269
 270   <refsect1>
 271     <title>Keys</title>
 272
 273     <para><command>systemd-cgtop</command> is an interactive tool and
 274     may be controlled via user input using the following keys:</para>
 275
 276     <variablelist>
 277       <varlistentry>
 278         <term><keycap>h</keycap></term>
 279
 280         <listitem><para>Shows a short help text.</para></listitem>
 281       </varlistentry>
 282
 283       <varlistentry>
 284         <term><keycap function="space"/></term>
 285
 286         <listitem><para>Immediately refresh output.</para></listitem>
 287       </varlistentry>
 288
 289       <varlistentry>
 290         <term><keycap>q</keycap></term>
 291
 292         <listitem><para>Terminate the program.</para></listitem>
 293       </varlistentry>
 294
 295       <varlistentry>
 296         <term><keycap>p</keycap></term>
 297         <term><keycap>t</keycap></term>
 298         <term><keycap>c</keycap></term>
 299         <term><keycap>m</keycap></term>
 300         <term><keycap>i</keycap></term>
 301
 302         <listitem><para>Sort the control groups by path, number of
 303         tasks, CPU load, memory usage, or I/O load, respectively.  This
 304         setting may also be controlled using the
 305         <option>--order=</option> command line
 306         switch.</para></listitem>
 307       </varlistentry>
 308
 309       <varlistentry>
 310         <term><keycap>%</keycap></term>
 311
 312         <listitem><para>Toggle between showing CPU time as time or
 313         percentage. This setting may also be controlled using the
 314         <option>--cpu=</option> command line switch.</para></listitem>
 315       </varlistentry>
 316
 317       <varlistentry>
 318         <term><keycap>+</keycap></term>
 319         <term><keycap>-</keycap></term>
 320
 321         <listitem><para>Increase or decrease refresh delay,
 322         respectively. This setting may also be controlled using the
 323         <option>--delay=</option> command line
 324         switch.</para></listitem>
 325       </varlistentry>
 326
 327       <varlistentry>
 328         <term><keycap>P</keycap></term>
 329
 330         <listitem><para>Toggle between counting all tasks, or only
 331         userspace processes. This setting may also be controlled using
 332         the <option>-P</option> command line switch (see
 333         above).</para></listitem>
 334       </varlistentry>
 335
 336       <varlistentry>
 337         <term><keycap>k</keycap></term>
 338
 339         <listitem><para>Toggle between counting all tasks, or only
 340         userspace processes and kernel threads. This setting may also
 341         be controlled using the <option>-k</option> command line
 342         switch (see above).</para></listitem>
 343       </varlistentry>
 344
 345       <varlistentry>
 346         <term><keycap>r</keycap></term>
 347
 348         <listitem><para>Toggle between recursively including or
 349         excluding processes in child control groups in control group
 350         process counts. This setting may also be controlled using the
 351         <option>--recursive=</option> command line switch. This key is
 352         not available if all tasks are counted, it is only available
 353         if processes are counted, as enabled with the
 354         <keycap>P</keycap> or <keycap>k</keycap>
 355         keys.</para></listitem>
 356       </varlistentry>
 357
 358     </variablelist>
 359   </refsect1>
 360
 361   <refsect1>
 362     <title>Exit status</title>
 363
 364     <para>On success, 0 is returned, a non-zero failure code
 365     otherwise.</para>
 366   </refsect1>
 367
 368   <refsect1>
 369     <title>See Also</title>
 370     <para>
 371       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 372       <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 373       <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 374       <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
 375       <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 376     </para>
 377   </refsect1>
 378
 379 </refentry>