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">
6 This file is part of systemd.
8 Copyright 2012 Lennart Poettering
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.
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.
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/>.
24 <refentry id=
"systemd-cgtop"
25 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
28 <title>systemd-cgtop
</title>
29 <productname>systemd
</productname>
33 <contrib>Developer
</contrib>
34 <firstname>Lennart
</firstname>
35 <surname>Poettering
</surname>
36 <email>lennart@poettering.net
</email>
42 <refentrytitle>systemd-cgtop
</refentrytitle>
43 <manvolnum>1</manvolnum>
47 <refname>systemd-cgtop
</refname>
48 <refpurpose>Show top control groups by their resource usage
</refpurpose>
53 <command>systemd-cgtop
</command>
54 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
59 <title>Description
</title>
61 <para><command>systemd-cgtop
</command> shows the top control
62 groups of the local Linux control group hierarchy, ordered by
63 their CPU, memory, or disk I/O load. The display is refreshed in
64 regular intervals (by default every
1s), similar in style to
65 <citerefentry project='man-pages'
><refentrytitle>top
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>
67 <para>If
<command>systemd-cgtop
</command> is not connected to a tty, no
68 column headers are printed and the default is to only run one iteration.
69 The
<varname>--iterations
</varname> argument, if given, is still honored.
70 This mode is suitable for scripting.
</para>
72 <para>Resource usage is only accounted for control groups in the
73 relevant hierarchy, i.e. CPU usage is only accounted for control
74 groups in the
<literal>cpuacct
</literal> hierarchy, memory usage
75 only for those in
<literal>memory
</literal> and disk I/O usage for
76 those in
<literal>blkio
</literal>. If resource monitoring for
77 these resources is required, it is recommended to add the
78 <varname>CPUAccounting=
1</varname>,
79 <varname>MemoryAccounting=
1</varname> and
80 <varname>BlockIOAccounting=
1</varname> settings in the unit files
82 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
85 <para>The CPU load value can be between
0 and
100 times the number of
86 processors the system has. For example, if the system has
8 processors,
87 the CPU load value is going to be between
0% and
800%. The number of
88 processors can be found in
<literal>/proc/cpuinfo
</literal>.
</para>
90 <para>To emphasize this: unless
91 <literal>CPUAccounting=
1</literal>,
92 <literal>MemoryAccounting=
1</literal> and
93 <literal>BlockIOAccounting=
1</literal> are enabled for the
94 services in question, no resource accounting will be available for
95 system services and the data shown by
96 <command>systemd-cgtop
</command> will be incomplete.
</para>
100 <title>Options
</title>
102 <para>The following options are understood:
</para>
106 <term><option>-p
</option></term>
108 <listitem><para>Order by control group
109 path name.
</para></listitem>
113 <term><option>-t
</option></term>
115 <listitem><para>Order by number of tasks in control group
116 (i.e. threads and processes).
</para></listitem>
120 <term><option>-c
</option></term>
122 <listitem><para>Order by CPU load.
</para></listitem>
126 <term><option>-m
</option></term>
128 <listitem><para>Order by memory usage.
</para></listitem>
132 <term><option>-i
</option></term>
134 <listitem><para>Order by disk I/O load.
</para></listitem>
138 <term><option>-b
</option></term>
139 <term><option>--batch
</option></term>
141 <listitem><para>Run in
"batch" mode: do not accept input and
142 run until the iteration limit set with
143 <option>--iterations
</option> is exhausted or until killed.
144 This mode could be useful for sending output from
145 <command>systemd-cgtop
</command> to other programs or to a
146 file.
</para></listitem>
150 <term><option>-r
</option></term>
151 <term><option>--raw
</option></term>
153 <listitem><para>Format byte counts (as in memory usage and IO metrics)
154 with raw numeric values rather than human-readable
155 numbers.
</para></listitem>
159 <term><option>-n
</option></term>
160 <term><option>--iterations=
</option></term>
162 <listitem><para>Perform only this many iterations. A value of
0
163 indicates that the program should run indefinitely.
</para></listitem>
167 <term><option>-d
</option></term>
168 <term><option>--delay=
</option></term>
170 <listitem><para>Specify refresh delay in seconds (or if one of
171 <literal>ms
</literal>,
172 <literal>us
</literal>,
173 <literal>min
</literal> is specified as unit in this time
174 unit).
</para></listitem>
178 <term><option>--depth=
</option></term>
180 <listitem><para>Maximum control group tree traversal depth.
181 Specifies how deep
<command>systemd-cgtop
</command> shall
182 traverse the control group hierarchies. If
0 is specified,
183 only the root group is monitored. For
1, only the first level
184 of control groups is monitored, and so on. Defaults to
188 <xi:include href=
"standard-options.xml" xpointer=
"help" />
189 <xi:include href=
"standard-options.xml" xpointer=
"version" />
198 <para><command>systemd-cgtop
</command> is an interactive tool and
199 may be controlled via user input using the following keys:
</para>
205 <listitem><para>Shows a short help text.
</para></listitem>
211 <listitem><para>Immediately refresh output.
</para></listitem>
217 <listitem><para>Terminate the program.
</para></listitem>
228 <listitem><para>Sort the control groups by path, number of
229 tasks, CPU load, memory usage, or IO load, respectively.
236 <listitem><para>Toggle between showing CPU time as time or
237 percentage.
</para></listitem>
244 <listitem><para>Increase or decrease refresh delay,
245 respectively.
</para></listitem>
252 <title>Exit status
</title>
254 <para>On success,
0 is returned, a non-zero failure code
259 <title>See Also
</title>
261 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
262 <citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
263 <citerefentry><refentrytitle>systemd-cgls
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
264 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
265 <citerefentry project='man-pages'
><refentrytitle>top
</refentrytitle><manvolnum>1</manvolnum></citerefentry>