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>.
66 If <command>systemd-cgtop</command> is not connected to a tty,
67 only one iteration is performed and no columns headers are
68 printed. This mode is suitable for scripting.</para>
70 <para>Resource usage is only accounted for control groups in the
71 relevant hierarchy, i.e. CPU usage is only accounted for control
72 groups in the <literal>cpuacct</literal> hierarchy, memory usage
73 only for those in <literal>memory</literal> and disk I/O usage for
74 those in <literal>blkio</literal>. If resource monitoring for
75 these resources is required, it is recommended to add the
76 <varname>CPUAccounting=1</varname>,
77 <varname>MemoryAccounting=1</varname> and
78 <varname>BlockIOAccounting=1</varname> settings in the unit files
80 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
83 <para>To emphasize this: unless
84 <literal>CPUAccounting=1</literal>,
85 <literal>MemoryAccounting=1</literal> and
86 <literal>BlockIOAccounting=1</literal> are enabled for the
87 services in question, no resource accounting will be available for
88 system services and the data shown by
89 <command>systemd-cgtop</command> will be incomplete.</para>
93 <title>Options</title>
95 <para>The following options are understood:</para>
99 <term><option>-p</option></term>
101 <listitem><para>Order by control group
102 path name.</para></listitem>
106 <term><option>-t</option></term>
108 <listitem><para>Order by number of tasks in control group
109 (i.e. threads and processes).</para></listitem>
113 <term><option>-c</option></term>
115 <listitem><para>Order by CPU load.</para></listitem>
119 <term><option>-m</option></term>
121 <listitem><para>Order by memory usage.</para></listitem>
125 <term><option>-i</option></term>
127 <listitem><para>Order by disk I/O load.</para></listitem>
131 <term><option>-b</option></term>
132 <term><option>--batch</option></term>
134 <listitem><para>Run in "batch" mode: do not accept input and
135 run until the iteration limit set with
136 <option>--iterations</option> is exhausted or until killed.
137 This mode could be useful for sending output from
138 <command>systemd-cgtop</command> to other programs or to a
139 file.</para></listitem>
143 <term><option>-n</option></term>
144 <term><option>--iterations=</option></term>
146 <listitem><para>Perform only this many iterations.
151 <term><option>-d</option></term>
152 <term><option>--delay=</option></term>
154 <listitem><para>Specify refresh delay in seconds (or if one of
155 <literal>ms</literal>,
156 <literal>us</literal>,
157 <literal>min</literal> is specified as unit in this time
158 unit).</para></listitem>
162 <term><option>--depth=</option></term>
164 <listitem><para>Maximum control group tree traversal depth.
165 Specifies how deep <command>systemd-cgtop</command> shall
166 traverse the control group hierarchies. If 0 is specified,
167 only the root group is monitored. For 1, only the first level
168 of control groups is monitored, and so on. Defaults to
172 <xi:include href="standard-options.xml" xpointer="help" />
173 <xi:include href="standard-options.xml" xpointer="version" />
182 <para><command>systemd-cgtop</command> is an interactive tool and
183 may be controlled via user input using the following keys:</para>
189 <listitem><para>Shows a short help text.</para></listitem>
195 <listitem><para>Immediately refresh output.</para></listitem>
201 <listitem><para>Terminate the program.</para></listitem>
212 <listitem><para>Sort the control groups by path, number of
213 tasks, CPU load, memory usage, or IO load, respectively.
220 <listitem><para>Toggle between showing CPU time as time or
221 percentage.</para></listitem>
228 <listitem><para>Increase or decrease refresh delay,
229 respectively.</para></listitem>
236 <title>Exit status</title>
238 <para>On success, 0 is returned, a non-zero failure code
243 <title>See Also</title>
245 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
246 <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
247 <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
248 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
249 <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>