[thirdparty/systemd.git] / man / systemd-cgtop.xml

<?xml version='1.0'?> <!--*-nxml-*-->
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
        "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">

<!--
  This file is part of systemd.

  Copyright 2012 Lennart Poettering

  systemd is free software; you can redistribute it and/or modify it
  under the terms of the GNU Lesser General Public License as published by
  the Free Software Foundation; either version 2.1 of the License, or
  (at your option) any later version.

  systemd is distributed in the hope that it will be useful, but
  WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public License
  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->

<refentry id="systemd-cgtop">

        <refentryinfo>
                <title>systemd-cgtop</title>
                <productname>systemd</productname>

                <authorgroup>
                        <author>
                                <contrib>Developer</contrib>
                                <firstname>Lennart</firstname>
                                <surname>Poettering</surname>
                                <email>lennart@poettering.net</email>
                        </author>
                </authorgroup>
        </refentryinfo>

        <refmeta>
                <refentrytitle>systemd-cgtop</refentrytitle>
                <manvolnum>1</manvolnum>
        </refmeta>

        <refnamediv>
                <refname>systemd-cgtop</refname>
                <refpurpose>Show top control groups by their resource usage</refpurpose>
        </refnamediv>

        <refsynopsisdiv>
                <cmdsynopsis>
                        <command>systemd-cgtop</command>
                        <arg choice="opt" rep="repeat">OPTIONS</arg>
                </cmdsynopsis>
        </refsynopsisdiv>

        <refsect1>
                <title>Description</title>

                <para><command>systemd-cgtop</command> shows the top
                control groups of the local Linux control group
                hierarchy, ordered by their CPU, memory, or disk I/O load. The
                display is refreshed in regular intervals (by default
                every 1s), similar in style to
                <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
                If <command>systemd-cgtop</command> is not connected
                to a tty, only one iteration is performed and no
                columns headers are printed. This mode is suitable for
                scripting.</para>

                <para>Resource usage is only accounted for control
                groups in the relevant hierarchy, i.e. CPU usage is
                only accounted for control groups in the
                <literal>cpuacct</literal> hierarchy, memory usage
                only for those in <literal>memory</literal> and disk
                I/O usage for those in <literal>blkio</literal>. If
                resource monitoring for these resources is required,
                it is recommended to add the
                <varname>CPUAccounting=1</varname>,
                <varname>MemoryAccounting=1</varname> and
                <varname>BlockIOAccounting=1</varname> settings in the
                unit files in question. See
                <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                for details.</para>

                <para>To emphasize this: unless
                <literal>CPUAccounting=1</literal>,
                <literal>MemoryAccounting=1</literal> and
                <literal>BlockIOAccounting=1</literal> are enabled for
                the services in question, no resource accounting will
                be available for system services and the data shown by
                <command>systemd-cgtop</command> will be
                incomplete.</para>
        </refsect1>

        <refsect1>
                <title>Options</title>

                <para>The following options are understood:</para>

                <variablelist>
                        <varlistentry>
                                <term><option>-h</option></term>
                                <term><option>--help</option></term>

                                <listitem><para>Prints a short help
                                text and exits.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--version</option></term>

                                <listitem><para>Prints a version string and
                                exits.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-p</option></term>

                                <listitem><para>Order by control group
                                path name.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-t</option></term>

                                <listitem><para>Order by number of
                                tasks in control
                                group (i.e. threads and processes).</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-c</option></term>

                                <listitem><para>Order by CPU load.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-m</option></term>

                                <listitem><para>Order by memory usage.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-i</option></term>

                                <listitem><para>Order by disk I/O load.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-b</option></term>
                                <term><option>--batch</option></term>

                                <listitem><para>Run in "batch" mode:
                                do not accept input and run until the
                                iteration limit set with
                                <option>--iterations</option> is
                                exhausted or until killed. This mode
                                could be useful for sending output
                                from <command>systemd-cgtop</command>
                                to other programs or to a
                                file.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-n</option></term>
                                <term><option>--iterations=</option></term>

                                <listitem><para>Perform only this many
                                iterations.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>-d</option></term>
                                <term><option>--delay=</option></term>

                                <listitem><para>Specify refresh delay
                                in seconds (or if one of
                                <literal>ms</literal>,
                                <literal>us</literal>,
                                <literal>min</literal> is specified as
                                unit in this time
                                unit).</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term><option>--depth=</option></term>

                                <listitem><para>Maximum control group
                                tree traversal depth. Specifies how
                                deep <command>systemd-cgtop</command>
                                shall traverse the control group
                                hierarchies. If 0 is specified, only
                                the root group is monitored. For 1,
                                only the first level of control groups
                                is monitored, and so on. Defaults to
                                3.</para></listitem>
                        </varlistentry>

                </variablelist>

        </refsect1>


        <refsect1>
                <title>Keys</title>

                <para><command>systemd-cgtop</command> is an
                interactive tool and may be controlled via user input
                using the following keys:</para>

                <variablelist>
                        <varlistentry>
                                <term>h</term>

                                <listitem><para>Shows a short help text.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term>SPACE</term>

                                <listitem><para>Immediately refresh output.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term>q</term>

                                <listitem><para>Terminate the program.</para></listitem>
                        </varlistentry>


                        <varlistentry>
                                <term>p</term>
                                <term>t</term>
                                <term>c</term>
                                <term>m</term>
                                <term>i</term>

                                <listitem><para>Sort the control groups
                                by path, number of tasks, CPU load,
                                memory usage, or IO
                                load, respectively.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term>%</term>

                                <listitem><para>Toggle between showing CPU time as
                                time or percentage.</para></listitem>
                        </varlistentry>

                        <varlistentry>
                                <term>+</term>
                                <term>-</term>

                                <listitem><para>Increase
                                or decrease refresh
                                delay, respectively.</para></listitem>
                        </varlistentry>

                </variablelist>
        </refsect1>

        <refsect1>
                <title>Exit status</title>

                <para>On success, 0 is returned, a non-zero failure
                code otherwise.</para>
        </refsect1>

        <refsect1>
                <title>See Also</title>
                <para>
                        <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
                        <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                </para>
        </refsect1>

</refentry>
Commit	Line	Data
caa94887 LP	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
5430f7f2 LP	11	under the terms of the GNU Lesser General Public License as published by
5430f7f2 LP	12	the Free Software Foundation; either version 2.1 of the License, or
caa94887 LP	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
5430f7f2	18	Lesser General Public License for more details.
caa94887	19
5430f7f2	20	You should have received a copy of the GNU Lesser General Public License
caa94887 LP	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>
1e913bcb UTL	52	<command>systemd-cgtop</command>
1e913bcb UTL	53	<arg choice="opt" rep="repeat">OPTIONS</arg>
caa94887 LP	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
1e913bcb	62	hierarchy, ordered by their CPU, memory, or disk I/O load. The
caa94887 LP	63	display is refreshed in regular intervals (by default
caa94887 LP	64	every 1s), similar in style to
1e913bcb UTL	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>
caa94887 LP	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
7ac80732 LP	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
72f4d966	82	unit files in question. See
3fde5f30	83	<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
72f4d966	84	for details.</para>
caa94887 LP	85
caa94887 LP	86	<para>To emphasize this: unless
7ac80732 LP	87	<literal>CPUAccounting=1</literal>,
	88	<literal>MemoryAccounting=1</literal> and
	89	<literal>BlockIOAccounting=1</literal> are enabled for
72f4d966	90	the services in question, no resource accounting will
7ac80732 LP	91	be available for system services and the data shown by
7ac80732 LP	92	<command>systemd-cgtop</command> will be
caa94887 LP	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
871b876e ZJS	110	<varlistentry>
	111	<term><option>--version</option></term>
	112
	113	<listitem><para>Prints a version string and
	114	exits.</para></listitem>
	115	</varlistentry>
	116
caa94887 LP	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
871b876e ZJS	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
caa94887 LP	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
79640424 JE	193	hierarchies. If 0 is specified, only
79640424 JE	194	the root group is monitored. For 1,
caa94887 LP	195	only the first level of control groups
caa94887 LP	196	is monitored, and so on. Defaults to
30edf116	197	3.</para></listitem>
caa94887 LP	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
16dad32e	239	<listitem><para>Sort the control groups
caa94887	240	by path, number of tasks, CPU load,
16dad32e AE	241	memory usage, or IO
16dad32e AE	242	load, respectively.</para></listitem>
caa94887 LP	243	</varlistentry>
caa94887 LP	244
2bfc1eda ZJS	245	<varlistentry>
	246	<term>%</term>
	247
	248	<listitem><para>Toggle between showing CPU time as
	249	time or percentage.</para></listitem>
	250	</varlistentry>
	251
caa94887 LP	252	<varlistentry>
	253	<term>+</term>
	254	<term>-</term>
	255
16dad32e AE	256	<listitem><para>Increase
	257	or decrease refresh
	258	delay, respectively.</para></listitem>
caa94887 LP	259	</varlistentry>
	260
	261	</variablelist>
	262	</refsect1>
	263
	264	<refsect1>
	265	<title>Exit status</title>
	266
b040723e	267	<para>On success, 0 is returned, a non-zero failure
caa94887 LP	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>,
3fde5f30	277	<citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
caa94887 LP	278	<citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
	279	</para>
	280	</refsect1>
	281
	282	</refentry>