2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6 <refentry id=
"systemd-cgtop"
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
10 <title>systemd-cgtop
</title>
11 <productname>systemd
</productname>
15 <refentrytitle>systemd-cgtop
</refentrytitle>
16 <manvolnum>1</manvolnum>
20 <refname>systemd-cgtop
</refname>
21 <refpurpose>Show top control groups by their resource usage
</refpurpose>
26 <command>systemd-cgtop
</command>
27 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
28 <arg choice=
"opt">GROUP
</arg>
33 <title>Description
</title>
35 <para><command>systemd-cgtop
</command> shows the top control
36 groups of the local Linux control group hierarchy, ordered by
37 their CPU, memory, or disk I/O load. The display is refreshed in
38 regular intervals (by default every
1s), similar in style to
39 <citerefentry project='man-pages'
><refentrytitle>top
</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
40 If a control group path is specified, shows only the services of
41 the specified control group.
</para>
43 <para>If
<command>systemd-cgtop
</command> is not connected to a
44 tty, no column headers are printed and the default is to only run
45 one iteration. The
<option>--iterations=
</option> argument, if
46 given, is honored. This mode is suitable for scripting.
</para>
48 <para>Resource usage is only accounted for control groups with the appropriate controllers turned on:
49 <literal>cpu
</literal> controller for CPU usage,
<literal>memory
</literal> controller for memory usage,
50 and
<literal>io
</literal> controller for disk I/O consumption. If resource monitoring for these resources
51 is required, it is recommended to add the
<varname>CPUAccounting=
1</varname>,
52 <varname>MemoryAccounting=
1</varname> and
<varname>IOAccounting=
1</varname> settings in the unit files in
54 <citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry>
57 <para>The CPU load value can be between
0 and
100 times the number of
58 processors the system has. For example, if the system has
8 processors,
59 the CPU load value is going to be between
0% and
800%. The number of
60 processors can be found in
<literal>/proc/cpuinfo
</literal>.
</para>
62 <para>To emphasize: unless
<literal>CPUAccounting=
1</literal>,
<literal>MemoryAccounting=
1</literal>, and
63 <literal>IOAccounting=
1</literal> are enabled for the services in question, no resource accounting will
64 be available for system services and the data shown by
<command>systemd-cgtop
</command> will be
69 <title>Options
</title>
71 <para>The following options are understood:
</para>
75 <term><option>-p
</option></term>
76 <term><option>--order=path
</option></term>
78 <listitem><para>Order by control group
79 path name.
</para></listitem>
83 <term><option>-t
</option></term>
84 <term><option>--order=tasks
</option></term>
86 <listitem><para>Order by number of tasks/processes in the control group.
</para></listitem>
90 <term><option>-c
</option></term>
91 <term><option>--order=cpu
</option></term>
93 <listitem><para>Order by CPU load.
</para></listitem>
97 <term><option>-m
</option></term>
98 <term><option>--order=memory
</option></term>
100 <listitem><para>Order by memory usage.
</para></listitem>
104 <term><option>-i
</option></term>
105 <term><option>--order=io
</option></term>
107 <listitem><para>Order by disk I/O load.
</para></listitem>
111 <term><option>-b
</option></term>
112 <term><option>--batch
</option></term>
114 <listitem><para>Run in
"batch" mode: do not accept input and
115 run until the iteration limit set with
116 <option>--iterations=
</option> is exhausted or until killed.
117 This mode could be useful for sending output from
118 <command>systemd-cgtop
</command> to other programs or to a
121 <xi:include href=
"version-info.xml" xpointer=
"v188"/></listitem>
125 <term><option>-r
</option></term>
126 <term><option>--raw
</option></term>
128 <listitem><para>Format byte counts (as in memory usage and I/O metrics) and CPU time
129 with raw numeric values rather than human-readable
132 <xi:include href=
"version-info.xml" xpointer=
"v221"/></listitem>
136 <term><option>--cpu=percentage
</option></term>
137 <term><option>--cpu=time
</option></term>
139 <listitem><para>Controls whether the CPU usage is shown as
140 percentage or time. By default, the CPU usage is shown as
141 percentage. This setting may also be toggled at runtime by
142 pressing the
<keycap>%
</keycap> key.
</para>
144 <xi:include href=
"version-info.xml" xpointer=
"v226"/></listitem>
148 <term><option>-P
</option></term>
150 <listitem><para>Count only userspace processes instead of all
151 tasks. By default, all tasks are counted: each kernel thread
152 and each userspace thread individually. With this setting,
153 kernel threads are excluded from the count and each userspace
154 process only counts as one task, regardless of how many
155 threads it consists of. This setting may also be toggled at
156 runtime by pressing the
<keycap>P
</keycap> key. This option
157 may not be combined with
158 <option>-k
</option>.
</para>
160 <xi:include href=
"version-info.xml" xpointer=
"v227"/></listitem>
164 <term><option>-k
</option></term>
166 <listitem><para>Count only userspace processes and kernel
167 threads instead of all tasks. By default, all tasks are
168 counted: each kernel thread and each userspace thread
169 individually. With this setting, kernel threads are included in
170 the count and each userspace process only counts as one task,
171 regardless of how many threads it consists of. This setting may
172 also be toggled at runtime by pressing the
<keycap>k
</keycap>
173 key. This option may not be combined with
174 <option>-P
</option>.
</para>
176 <xi:include href=
"version-info.xml" xpointer=
"v226"/></listitem>
180 <term><option>--recursive=
</option></term>
182 <listitem><para>Controls whether the number of processes shown
183 for a control group shall include all processes that are
184 contained in any of the child control groups as well. Takes a
185 boolean argument, which defaults to
<literal>yes
</literal>. If
186 enabled, the processes in child control groups are included, if
187 disabled, only the processes in the control group itself are
188 counted. This setting may also be toggled at runtime by
189 pressing the
<keycap>r
</keycap> key. Note that this setting
190 only applies to process counting, i.e. when the
191 <option>-P
</option> or
<option>-k
</option> options are
192 used. It has not effect if all tasks are counted, in which
193 case the counting is always recursive.
</para>
195 <xi:include href=
"version-info.xml" xpointer=
"v226"/></listitem>
199 <term><option>-n
</option></term>
200 <term><option>--iterations=
</option></term>
202 <listitem><para>Perform only this many iterations. A value of
203 0 indicates that the program should run
206 <xi:include href=
"version-info.xml" xpointer=
"v188"/></listitem>
210 <term><option>-
1</option></term>
212 <listitem><para>A shortcut for
<option>--iterations=
1</option>.
</para>
214 <xi:include href=
"version-info.xml" xpointer=
"v238"/></listitem>
218 <term><option>-d
</option></term>
219 <term><option>--delay=
</option></term>
221 <listitem><para>Specify refresh delay in seconds (or if one of
222 <literal>ms
</literal>,
<literal>us
</literal>,
223 <literal>min
</literal> is specified as unit in this time
224 unit). This setting may also be increased and decreased at
225 runtime by pressing the
<keycap>+
</keycap> and
226 <keycap>-
</keycap> keys.
</para></listitem>
230 <term><option>--depth=
</option></term>
232 <listitem><para>Maximum control group tree traversal depth.
233 Specifies how deep
<command>systemd-cgtop
</command> shall
234 traverse the control group hierarchies. If
0 is specified,
235 only the root group is monitored. For
1, only the first level
236 of control groups is monitored, and so on. Defaults to
241 <term><option>-M
<replaceable>MACHINE
</replaceable></option></term>
242 <term><option>--machine=
<replaceable>MACHINE
</replaceable></option></term>
244 <listitem><para>Limit control groups shown to the part
245 corresponding to the container
246 <replaceable>MACHINE
</replaceable>.
247 This option may not be used when a control group path is specified.
</para>
249 <xi:include href=
"version-info.xml" xpointer=
"v227"/></listitem>
252 <xi:include href=
"standard-options.xml" xpointer=
"help" />
253 <xi:include href=
"standard-options.xml" xpointer=
"version" />
261 <para><command>systemd-cgtop
</command> is an interactive tool and
262 may be controlled via user input using the following keys:
</para>
266 <term><keycap>h
</keycap></term>
268 <listitem><para>Shows a short help text.
</para></listitem>
272 <term><keycap function=
"space"/></term>
274 <listitem><para>Immediately refresh output.
</para>
276 <xi:include href=
"version-info.xml" xpointer=
"v226"/></listitem>
280 <term><keycap>q
</keycap></term>
282 <listitem><para>Terminate the program.
</para></listitem>
286 <term><keycap>p
</keycap></term>
287 <term><keycap>t
</keycap></term>
288 <term><keycap>c
</keycap></term>
289 <term><keycap>m
</keycap></term>
290 <term><keycap>i
</keycap></term>
292 <listitem><para>Sort the control groups by path, number of
293 tasks, CPU load, memory usage, or I/O load, respectively. This
294 setting may also be controlled using the
295 <option>--order=
</option> command line
296 switch.
</para></listitem>
300 <term><keycap>%
</keycap></term>
302 <listitem><para>Toggle between showing CPU time as time or
303 percentage. This setting may also be controlled using the
304 <option>--cpu=
</option> command line switch.
</para>
306 <xi:include href=
"version-info.xml" xpointer=
"v201"/></listitem>
310 <term><keycap>+
</keycap></term>
311 <term><keycap>-
</keycap></term>
313 <listitem><para>Increase or decrease refresh delay,
314 respectively. This setting may also be controlled using the
315 <option>--delay=
</option> command line
316 switch.
</para></listitem>
320 <term><keycap>P
</keycap></term>
322 <listitem><para>Toggle between counting all tasks, or only
323 userspace processes. This setting may also be controlled using
324 the
<option>-P
</option> command line switch (see
327 <xi:include href=
"version-info.xml" xpointer=
"v227"/></listitem>
331 <term><keycap>k
</keycap></term>
333 <listitem><para>Toggle between counting all tasks, or only
334 userspace processes and kernel threads. This setting may also
335 be controlled using the
<option>-k
</option> command line
336 switch (see above).
</para>
338 <xi:include href=
"version-info.xml" xpointer=
"v226"/></listitem>
342 <term><keycap>r
</keycap></term>
344 <listitem><para>Toggle between recursively including or
345 excluding processes in child control groups in control group
346 process counts. This setting may also be controlled using the
347 <option>--recursive=
</option> command line switch. This key is
348 not available if all tasks are counted, it is only available
349 if processes are counted, as enabled with the
350 <keycap>P
</keycap> or
<keycap>k
</keycap>
353 <xi:include href=
"version-info.xml" xpointer=
"v226"/></listitem>
360 <title>Exit status
</title>
362 <para>On success,
0 is returned, a non-zero failure code
367 <title>See Also
</title>
368 <para><simplelist type=
"inline">
369 <member><citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
370 <member><citerefentry><refentrytitle>systemctl
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
371 <member><citerefentry><refentrytitle>systemd-cgls
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
372 <member><citerefentry><refentrytitle>systemd.resource-control
</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
373 <member><citerefentry project='man-pages'
><refentrytitle>top
</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>