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">
27 <title>systemd-cgtop
</title>
28 <productname>systemd
</productname>
32 <contrib>Developer
</contrib>
33 <firstname>Lennart
</firstname>
34 <surname>Poettering
</surname>
35 <email>lennart@poettering.net
</email>
41 <refentrytitle>systemd-cgtop
</refentrytitle>
42 <manvolnum>1</manvolnum>
46 <refname>systemd-cgtop
</refname>
47 <refpurpose>Show top control groups by their resource usage
</refpurpose>
52 <command>systemd-cgtop
<arg choice=
"opt" rep=
"repeat">OPTIONS
</arg></command>
57 <title>Description
</title>
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>
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>
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
99 <title>Options
</title>
101 <para>The following options are understood:
</para>
105 <term><option>-h
</option></term>
106 <term><option>--help
</option></term>
108 <listitem><para>Prints a short help
109 text and exits.
</para></listitem>
113 <term><option>-p
</option></term>
115 <listitem><para>Order by control group
116 path name.
</para></listitem>
120 <term><option>-t
</option></term>
122 <listitem><para>Order by number of
124 group (i.e. threads and processes).
</para></listitem>
128 <term><option>-c
</option></term>
130 <listitem><para>Order by CPU load.
</para></listitem>
134 <term><option>-m
</option></term>
136 <listitem><para>Order by memory usage.
</para></listitem>
140 <term><option>-i
</option></term>
142 <listitem><para>Order by disk I/O load.
</para></listitem>
146 <term><option>-d
</option></term>
147 <term><option>--delay=
</option></term>
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
155 unit).
</para></listitem>
159 <term><option>--depth=
</option></term>
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
180 <para><command>systemd-cgtop
</command> is an
181 interactive tool and may be controlled via user input
182 using the following keys:
</para>
188 <listitem><para>Shows a short help text.
</para></listitem>
194 <listitem><para>Immediately refresh output.
</para></listitem>
200 <listitem><para>Terminate the program.
</para></listitem>
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>
221 <listitem><para>Increase,
222 resp. decrease refresh
223 delay.
</para></listitem>
230 <title>Exit status
</title>
232 <para>On success
0 is returned, a non-zero failure
233 code otherwise.
</para>
237 <title>See Also
</title>
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>