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</command>
53 <arg choice="opt" rep="repeat">OPTIONS</arg>
58 <title>Description</title>
60 <para><command>systemd-cgtop</command> shows the top
61 control groups of the local Linux control group
62 hierarchy, ordered by their CPU, memory, or disk I/O load. The
63 display is refreshed in regular intervals (by default
64 every 1s), similar in style to
65 <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
66 If <command>systemd-cgtop</command> is not connected
67 to a tty, only one iteration is performed and no
68 columns headers are printed. This mode is suitable for
71 <para>Resource usage is only accounted for control
72 groups in the relevant hierarchy, i.e. CPU usage is
73 only accounted for control groups in the
74 <literal>cpuacct</literal> hierarchy, memory usage
75 only for those in <literal>memory</literal> and disk
76 I/O usage for those in
77 <literal>blkio</literal>. <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
78 by default places all services in their own control
79 group in the <literal>cpuacct</literal> hierarchy, but
80 not in <literal>memory</literal> nor
81 <literal>blkio</literal>. If resource monitoring for
82 these resources is required it is recommended to add
83 <literal>blkio</literal> and <literal>memory</literal>
84 to the <varname>DefaultControllers=</varname> setting
85 in <filename>/etc/systemd/system.conf</filename> (see
86 <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
87 for details). Alternatively, it is possible to enable
88 resource accounting individually for services, by
89 making use of the <varname>ControlGroup=</varname>
90 option in the unit files (See
91 <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
94 <para>To emphasize this: unless
95 <literal>blkio</literal> and <literal>memory</literal>
96 are enabled for the services in question with either
97 of the options suggested above no resource accounting
98 will be available for system services and the data shown
99 by <command>systemd-cgtop</command> will be
104 <title>Options</title>
106 <para>The following options are understood:</para>
110 <term><option>-h</option></term>
111 <term><option>--help</option></term>
113 <listitem><para>Prints a short help
114 text and exits.</para></listitem>
118 <term><option>--version</option></term>
120 <listitem><para>Prints a version string and
121 exits.</para></listitem>
125 <term><option>-p</option></term>
127 <listitem><para>Order by control group
128 path name.</para></listitem>
132 <term><option>-t</option></term>
134 <listitem><para>Order by number of
136 group (i.e. threads and processes).</para></listitem>
140 <term><option>-c</option></term>
142 <listitem><para>Order by CPU load.</para></listitem>
146 <term><option>-m</option></term>
148 <listitem><para>Order by memory usage.</para></listitem>
152 <term><option>-i</option></term>
154 <listitem><para>Order by disk I/O load.</para></listitem>
158 <term><option>-b</option></term>
159 <term><option>--batch</option></term>
161 <listitem><para>Run in "batch" mode:
162 do not accept input and run until the
163 iteration limit set with
164 <option>--iterations</option> is
165 exhausted or until killed. This mode
166 could be useful for sending output
167 from <command>systemd-cgtop</command>
168 to other programs or to a
169 file.</para></listitem>
173 <term><option>-n</option></term>
174 <term><option>--iterations=</option></term>
176 <listitem><para>Perform only this many
177 iterations.</para></listitem>
181 <term><option>-d</option></term>
182 <term><option>--delay=</option></term>
184 <listitem><para>Specify refresh delay
185 in seconds (or if one of
186 <literal>ms</literal>,
187 <literal>us</literal>,
188 <literal>min</literal> is specified as
190 unit).</para></listitem>
194 <term><option>--depth=</option></term>
196 <listitem><para>Maximum control group
197 tree traversal depth. Specifies how
198 deep <command>systemd-cgtop</command>
199 shall traverse the control group
200 hierarchies. If 0 is specified only
201 the root group is monitored, for 1
202 only the first level of control groups
203 is monitored, and so on. Defaults to
215 <para><command>systemd-cgtop</command> is an
216 interactive tool and may be controlled via user input
217 using the following keys:</para>
223 <listitem><para>Shows a short help text.</para></listitem>
229 <listitem><para>Immediately refresh output.</para></listitem>
235 <listitem><para>Terminate the program.</para></listitem>
246 <listitem><para>Sort the control groups
247 by path, number of tasks, CPU load,
249 load, respectively.</para></listitem>
255 <listitem><para>Toggle between showing CPU time as
256 time or percentage.</para></listitem>
263 <listitem><para>Increase
265 delay, respectively.</para></listitem>
272 <title>Exit status</title>
274 <para>On success 0 is returned, a non-zero failure
275 code otherwise.</para>
279 <title>See Also</title>
281 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
282 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
283 <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
284 <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>