chiark / gitweb /
zsh_completion: Split out zsh _systemd-analyze
[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
26         <refentryinfo>
27                 <title>systemd-cgtop</title>
28                 <productname>systemd</productname>
29
30                 <authorgroup>
31                         <author>
32                                 <contrib>Developer</contrib>
33                                 <firstname>Lennart</firstname>
34                                 <surname>Poettering</surname>
35                                 <email>lennart@poettering.net</email>
36                         </author>
37                 </authorgroup>
38         </refentryinfo>
39
40         <refmeta>
41                 <refentrytitle>systemd-cgtop</refentrytitle>
42                 <manvolnum>1</manvolnum>
43         </refmeta>
44
45         <refnamediv>
46                 <refname>systemd-cgtop</refname>
47                 <refpurpose>Show top control groups by their resource usage</refpurpose>
48         </refnamediv>
49
50         <refsynopsisdiv>
51                 <cmdsynopsis>
52                         <command>systemd-cgtop</command>
53                         <arg choice="opt" rep="repeat">OPTIONS</arg>
54                 </cmdsynopsis>
55         </refsynopsisdiv>
56
57         <refsect1>
58                 <title>Description</title>
59
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
69                 scripting.</para>
70
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>
92                 for details).</para>
93
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
100                 incomplete.</para>
101         </refsect1>
102
103         <refsect1>
104                 <title>Options</title>
105
106                 <para>The following options are understood:</para>
107
108                 <variablelist>
109                         <varlistentry>
110                                 <term><option>-h</option></term>
111                                 <term><option>--help</option></term>
112
113                                 <listitem><para>Prints a short help
114                                 text and exits.</para></listitem>
115                         </varlistentry>
116
117                         <varlistentry>
118                                 <term><option>--version</option></term>
119
120                                 <listitem><para>Prints a version string and
121                                 exits.</para></listitem>
122                         </varlistentry>
123
124                         <varlistentry>
125                                 <term><option>-p</option></term>
126
127                                 <listitem><para>Order by control group
128                                 path name.</para></listitem>
129                         </varlistentry>
130
131                         <varlistentry>
132                                 <term><option>-t</option></term>
133
134                                 <listitem><para>Order by number of
135                                 tasks in control
136                                 group (i.e. threads and processes).</para></listitem>
137                         </varlistentry>
138
139                         <varlistentry>
140                                 <term><option>-c</option></term>
141
142                                 <listitem><para>Order by CPU load.</para></listitem>
143                         </varlistentry>
144
145                         <varlistentry>
146                                 <term><option>-m</option></term>
147
148                                 <listitem><para>Order by memory usage.</para></listitem>
149                         </varlistentry>
150
151                         <varlistentry>
152                                 <term><option>-i</option></term>
153
154                                 <listitem><para>Order by disk I/O load.</para></listitem>
155                         </varlistentry>
156
157                         <varlistentry>
158                                 <term><option>-b</option></term>
159                                 <term><option>--batch</option></term>
160
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>
170                         </varlistentry>
171
172                         <varlistentry>
173                                 <term><option>-n</option></term>
174                                 <term><option>--iterations=</option></term>
175
176                                 <listitem><para>Perform only this many
177                                 iterations.</para></listitem>
178                         </varlistentry>
179
180                         <varlistentry>
181                                 <term><option>-d</option></term>
182                                 <term><option>--delay=</option></term>
183
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
189                                 unit in this time
190                                 unit).</para></listitem>
191                         </varlistentry>
192
193                         <varlistentry>
194                                 <term><option>--depth=</option></term>
195
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
204                                 3.</para></listitem>
205                         </varlistentry>
206
207                 </variablelist>
208
209         </refsect1>
210
211
212         <refsect1>
213                 <title>Keys</title>
214
215                 <para><command>systemd-cgtop</command> is an
216                 interactive tool and may be controlled via user input
217                 using the following keys:</para>
218
219                 <variablelist>
220                         <varlistentry>
221                                 <term>h</term>
222
223                                 <listitem><para>Shows a short help text.</para></listitem>
224                         </varlistentry>
225
226                         <varlistentry>
227                                 <term>SPACE</term>
228
229                                 <listitem><para>Immediately refresh output.</para></listitem>
230                         </varlistentry>
231
232                         <varlistentry>
233                                 <term>q</term>
234
235                                 <listitem><para>Terminate the program.</para></listitem>
236                         </varlistentry>
237
238
239                         <varlistentry>
240                                 <term>p</term>
241                                 <term>t</term>
242                                 <term>c</term>
243                                 <term>m</term>
244                                 <term>i</term>
245
246                                 <listitem><para>Sort the control groups
247                                 by path, number of tasks, CPU load,
248                                 memory usage, or IO
249                                 load, respectively.</para></listitem>
250                         </varlistentry>
251
252                         <varlistentry>
253                                 <term>%</term>
254
255                                 <listitem><para>Toggle between showing CPU time as
256                                 time or percentage.</para></listitem>
257                         </varlistentry>
258
259                         <varlistentry>
260                                 <term>+</term>
261                                 <term>-</term>
262
263                                 <listitem><para>Increase
264                                 or decrease refresh
265                                 delay, respectively.</para></listitem>
266                         </varlistentry>
267
268                 </variablelist>
269         </refsect1>
270
271         <refsect1>
272                 <title>Exit status</title>
273
274                 <para>On success 0 is returned, a non-zero failure
275                 code otherwise.</para>
276         </refsect1>
277
278         <refsect1>
279                 <title>See Also</title>
280                 <para>
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>
285                 </para>
286         </refsect1>
287
288 </refentry>