chiark / gitweb /
sd-rtnl: log if kernel buffer is overrun as we currently can't handle that case
[elogind.git] / man / systemd-cgtop.xml
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">
4
5 <!--
6   This file is part of systemd.
7
8   Copyright 2012 Lennart Poettering
9
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.
14
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.
19
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/>.
22 -->
23
24 <refentry id="systemd-cgtop"
25           xmlns:xi="http://www.w3.org/2001/XInclude">
26
27         <refentryinfo>
28                 <title>systemd-cgtop</title>
29                 <productname>systemd</productname>
30
31                 <authorgroup>
32                         <author>
33                                 <contrib>Developer</contrib>
34                                 <firstname>Lennart</firstname>
35                                 <surname>Poettering</surname>
36                                 <email>lennart@poettering.net</email>
37                         </author>
38                 </authorgroup>
39         </refentryinfo>
40
41         <refmeta>
42                 <refentrytitle>systemd-cgtop</refentrytitle>
43                 <manvolnum>1</manvolnum>
44         </refmeta>
45
46         <refnamediv>
47                 <refname>systemd-cgtop</refname>
48                 <refpurpose>Show top control groups by their resource usage</refpurpose>
49         </refnamediv>
50
51         <refsynopsisdiv>
52                 <cmdsynopsis>
53                         <command>systemd-cgtop</command>
54                         <arg choice="opt" rep="repeat">OPTIONS</arg>
55                 </cmdsynopsis>
56         </refsynopsisdiv>
57
58         <refsect1>
59                 <title>Description</title>
60
61                 <para><command>systemd-cgtop</command> shows the top
62                 control groups of the local Linux control group
63                 hierarchy, ordered by their CPU, memory, or disk I/O load. The
64                 display is refreshed in regular intervals (by default
65                 every 1s), similar in style to
66                 <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
67                 If <command>systemd-cgtop</command> is not connected
68                 to a tty, only one iteration is performed and no
69                 columns headers are printed. This mode is suitable for
70                 scripting.</para>
71
72                 <para>Resource usage is only accounted for control
73                 groups in the relevant hierarchy, i.e. CPU usage is
74                 only accounted for control groups in the
75                 <literal>cpuacct</literal> hierarchy, memory usage
76                 only for those in <literal>memory</literal> and disk
77                 I/O usage for those in <literal>blkio</literal>. If
78                 resource monitoring for these resources is required,
79                 it is recommended to add the
80                 <varname>CPUAccounting=1</varname>,
81                 <varname>MemoryAccounting=1</varname> and
82                 <varname>BlockIOAccounting=1</varname> settings in the
83                 unit files in question. See
84                 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
85                 for details.</para>
86
87                 <para>To emphasize this: unless
88                 <literal>CPUAccounting=1</literal>,
89                 <literal>MemoryAccounting=1</literal> and
90                 <literal>BlockIOAccounting=1</literal> are enabled for
91                 the services in question, no resource accounting will
92                 be available for system services and the data shown by
93                 <command>systemd-cgtop</command> will be
94                 incomplete.</para>
95         </refsect1>
96
97         <refsect1>
98                 <title>Options</title>
99
100                 <para>The following options are understood:</para>
101
102                 <variablelist>
103                         <varlistentry>
104                                 <term><option>-p</option></term>
105
106                                 <listitem><para>Order by control group
107                                 path name.</para></listitem>
108                         </varlistentry>
109
110                         <varlistentry>
111                                 <term><option>-t</option></term>
112
113                                 <listitem><para>Order by number of
114                                 tasks in control
115                                 group (i.e. threads and processes).</para></listitem>
116                         </varlistentry>
117
118                         <varlistentry>
119                                 <term><option>-c</option></term>
120
121                                 <listitem><para>Order by CPU load.</para></listitem>
122                         </varlistentry>
123
124                         <varlistentry>
125                                 <term><option>-m</option></term>
126
127                                 <listitem><para>Order by memory usage.</para></listitem>
128                         </varlistentry>
129
130                         <varlistentry>
131                                 <term><option>-i</option></term>
132
133                                 <listitem><para>Order by disk I/O load.</para></listitem>
134                         </varlistentry>
135
136                         <varlistentry>
137                                 <term><option>-b</option></term>
138                                 <term><option>--batch</option></term>
139
140                                 <listitem><para>Run in "batch" mode:
141                                 do not accept input and run until the
142                                 iteration limit set with
143                                 <option>--iterations</option> is
144                                 exhausted or until killed. This mode
145                                 could be useful for sending output
146                                 from <command>systemd-cgtop</command>
147                                 to other programs or to a
148                                 file.</para></listitem>
149                         </varlistentry>
150
151                         <varlistentry>
152                                 <term><option>-n</option></term>
153                                 <term><option>--iterations=</option></term>
154
155                                 <listitem><para>Perform only this many
156                                 iterations.</para></listitem>
157                         </varlistentry>
158
159                         <varlistentry>
160                                 <term><option>-d</option></term>
161                                 <term><option>--delay=</option></term>
162
163                                 <listitem><para>Specify refresh delay
164                                 in seconds (or if one of
165                                 <literal>ms</literal>,
166                                 <literal>us</literal>,
167                                 <literal>min</literal> is specified as
168                                 unit in this time
169                                 unit).</para></listitem>
170                         </varlistentry>
171
172                         <varlistentry>
173                                 <term><option>--depth=</option></term>
174
175                                 <listitem><para>Maximum control group
176                                 tree traversal depth. Specifies how
177                                 deep <command>systemd-cgtop</command>
178                                 shall traverse the control group
179                                 hierarchies. If 0 is specified, only
180                                 the root group is monitored. For 1,
181                                 only the first level of control groups
182                                 is monitored, and so on. Defaults to
183                                 3.</para></listitem>
184                         </varlistentry>
185
186                         <xi:include href="standard-options.xml" xpointer="help" />
187                         <xi:include href="standard-options.xml" xpointer="version" />
188                 </variablelist>
189
190         </refsect1>
191
192
193         <refsect1>
194                 <title>Keys</title>
195
196                 <para><command>systemd-cgtop</command> is an
197                 interactive tool and may be controlled via user input
198                 using the following keys:</para>
199
200                 <variablelist>
201                         <varlistentry>
202                                 <term>h</term>
203
204                                 <listitem><para>Shows a short help text.</para></listitem>
205                         </varlistentry>
206
207                         <varlistentry>
208                                 <term>SPACE</term>
209
210                                 <listitem><para>Immediately refresh output.</para></listitem>
211                         </varlistentry>
212
213                         <varlistentry>
214                                 <term>q</term>
215
216                                 <listitem><para>Terminate the program.</para></listitem>
217                         </varlistentry>
218
219
220                         <varlistentry>
221                                 <term>p</term>
222                                 <term>t</term>
223                                 <term>c</term>
224                                 <term>m</term>
225                                 <term>i</term>
226
227                                 <listitem><para>Sort the control groups
228                                 by path, number of tasks, CPU load,
229                                 memory usage, or IO
230                                 load, respectively.</para></listitem>
231                         </varlistentry>
232
233                         <varlistentry>
234                                 <term>%</term>
235
236                                 <listitem><para>Toggle between showing CPU time as
237                                 time or percentage.</para></listitem>
238                         </varlistentry>
239
240                         <varlistentry>
241                                 <term>+</term>
242                                 <term>-</term>
243
244                                 <listitem><para>Increase
245                                 or decrease refresh
246                                 delay, respectively.</para></listitem>
247                         </varlistentry>
248
249                 </variablelist>
250         </refsect1>
251
252         <refsect1>
253                 <title>Exit status</title>
254
255                 <para>On success, 0 is returned, a non-zero failure
256                 code otherwise.</para>
257         </refsect1>
258
259         <refsect1>
260                 <title>See Also</title>
261                 <para>
262                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
263                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
264                         <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
265                         <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
266                         <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
267                 </para>
268         </refsect1>
269
270 </refentry>