chiark / gitweb /
man: get rid of shell script example in systemd-socket-proxyd man page
[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 <literal>blkio</literal>. If
77                 resource monitoring for these resources is required,
78                 it is recommended to add the
79                 <varname>CPUAccounting=1</varname>,
80                 <varname>MemoryAccounting=1</varname> and
81                 <varname>BlockIOAccounting=1</varname> settings in the
82                 unit files in question. See
83                 <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
84                 for details.</para>
85
86                 <para>To emphasize this: unless
87                 <literal>CPUAccounting=1</literal>,
88                 <literal>MemoryAccounting=1</literal> and
89                 <literal>BlockIOAccounting=1</literal> are enabled for
90                 the services in question, no resource accounting will
91                 be available for system services and the data shown by
92                 <command>systemd-cgtop</command> will be
93                 incomplete.</para>
94         </refsect1>
95
96         <refsect1>
97                 <title>Options</title>
98
99                 <para>The following options are understood:</para>
100
101                 <variablelist>
102                         <varlistentry>
103                                 <term><option>-h</option></term>
104                                 <term><option>--help</option></term>
105
106                                 <listitem><para>Prints a short help
107                                 text and exits.</para></listitem>
108                         </varlistentry>
109
110                         <varlistentry>
111                                 <term><option>--version</option></term>
112
113                                 <listitem><para>Prints a version string and
114                                 exits.</para></listitem>
115                         </varlistentry>
116
117                         <varlistentry>
118                                 <term><option>-p</option></term>
119
120                                 <listitem><para>Order by control group
121                                 path name.</para></listitem>
122                         </varlistentry>
123
124                         <varlistentry>
125                                 <term><option>-t</option></term>
126
127                                 <listitem><para>Order by number of
128                                 tasks in control
129                                 group (i.e. threads and processes).</para></listitem>
130                         </varlistentry>
131
132                         <varlistentry>
133                                 <term><option>-c</option></term>
134
135                                 <listitem><para>Order by CPU load.</para></listitem>
136                         </varlistentry>
137
138                         <varlistentry>
139                                 <term><option>-m</option></term>
140
141                                 <listitem><para>Order by memory usage.</para></listitem>
142                         </varlistentry>
143
144                         <varlistentry>
145                                 <term><option>-i</option></term>
146
147                                 <listitem><para>Order by disk I/O load.</para></listitem>
148                         </varlistentry>
149
150                         <varlistentry>
151                                 <term><option>-b</option></term>
152                                 <term><option>--batch</option></term>
153
154                                 <listitem><para>Run in "batch" mode:
155                                 do not accept input and run until the
156                                 iteration limit set with
157                                 <option>--iterations</option> is
158                                 exhausted or until killed. This mode
159                                 could be useful for sending output
160                                 from <command>systemd-cgtop</command>
161                                 to other programs or to a
162                                 file.</para></listitem>
163                         </varlistentry>
164
165                         <varlistentry>
166                                 <term><option>-n</option></term>
167                                 <term><option>--iterations=</option></term>
168
169                                 <listitem><para>Perform only this many
170                                 iterations.</para></listitem>
171                         </varlistentry>
172
173                         <varlistentry>
174                                 <term><option>-d</option></term>
175                                 <term><option>--delay=</option></term>
176
177                                 <listitem><para>Specify refresh delay
178                                 in seconds (or if one of
179                                 <literal>ms</literal>,
180                                 <literal>us</literal>,
181                                 <literal>min</literal> is specified as
182                                 unit in this time
183                                 unit).</para></listitem>
184                         </varlistentry>
185
186                         <varlistentry>
187                                 <term><option>--depth=</option></term>
188
189                                 <listitem><para>Maximum control group
190                                 tree traversal depth. Specifies how
191                                 deep <command>systemd-cgtop</command>
192                                 shall traverse the control group
193                                 hierarchies. If 0 is specified, only
194                                 the root group is monitored. For 1,
195                                 only the first level of control groups
196                                 is monitored, and so on. Defaults to
197                                 3.</para></listitem>
198                         </varlistentry>
199
200                 </variablelist>
201
202         </refsect1>
203
204
205         <refsect1>
206                 <title>Keys</title>
207
208                 <para><command>systemd-cgtop</command> is an
209                 interactive tool and may be controlled via user input
210                 using the following keys:</para>
211
212                 <variablelist>
213                         <varlistentry>
214                                 <term>h</term>
215
216                                 <listitem><para>Shows a short help text.</para></listitem>
217                         </varlistentry>
218
219                         <varlistentry>
220                                 <term>SPACE</term>
221
222                                 <listitem><para>Immediately refresh output.</para></listitem>
223                         </varlistentry>
224
225                         <varlistentry>
226                                 <term>q</term>
227
228                                 <listitem><para>Terminate the program.</para></listitem>
229                         </varlistentry>
230
231
232                         <varlistentry>
233                                 <term>p</term>
234                                 <term>t</term>
235                                 <term>c</term>
236                                 <term>m</term>
237                                 <term>i</term>
238
239                                 <listitem><para>Sort the control groups
240                                 by path, number of tasks, CPU load,
241                                 memory usage, or IO
242                                 load, respectively.</para></listitem>
243                         </varlistentry>
244
245                         <varlistentry>
246                                 <term>%</term>
247
248                                 <listitem><para>Toggle between showing CPU time as
249                                 time or percentage.</para></listitem>
250                         </varlistentry>
251
252                         <varlistentry>
253                                 <term>+</term>
254                                 <term>-</term>
255
256                                 <listitem><para>Increase
257                                 or decrease refresh
258                                 delay, respectively.</para></listitem>
259                         </varlistentry>
260
261                 </variablelist>
262         </refsect1>
263
264         <refsect1>
265                 <title>Exit status</title>
266
267                 <para>On success 0 is returned, a non-zero failure
268                 code otherwise.</para>
269         </refsect1>
270
271         <refsect1>
272                 <title>See Also</title>
273                 <para>
274                         <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
275                         <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
276                         <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
277                         <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
278                         <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
279                 </para>
280         </refsect1>
281
282 </refentry>