[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>. <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
                by default places all services in their own control
                group in the <literal>cpuacct</literal> hierarchy, but
                not in <literal>memory</literal> nor
                <literal>blkio</literal>. If resource monitoring for
                these resources is required, it is recommended to add
                <literal>blkio</literal> and <literal>memory</literal>
                to the <varname>DefaultControllers=</varname> setting
                in <filename>/etc/systemd/system.conf</filename> (see
                <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                for details). Alternatively, it is possible to enable
                resource accounting individually for services, by
                making use of the <varname>ControlGroup=</varname>
                option in the unit files (See
                <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
                for details).</para>

                <para>To emphasize this: unless
                <literal>blkio</literal> and <literal>memory</literal>
                are enabled for the services in question with either
                of the options suggested above 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>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
	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
79640424	82	these resources is required, it is recommended to add
caa94887 LP	83	<literal>blkio</literal> and <literal>memory</literal>
	84	to the <varname>DefaultControllers=</varname> setting
	85	in <filename>/etc/systemd/system.conf</filename> (see
5f9cfd4c	86	<citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
caa94887 LP	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
871b876e ZJS	117	<varlistentry>
	118	<term><option>--version</option></term>
	119
	120	<listitem><para>Prints a version string and
	121	exits.</para></listitem>
	122	</varlistentry>
	123
caa94887 LP	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
871b876e ZJS	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
caa94887 LP	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
79640424 JE	200	hierarchies. If 0 is specified, only
79640424 JE	201	the root group is monitored. For 1,
caa94887 LP	202	only the first level of control groups
caa94887 LP	203	is monitored, and so on. Defaults to
30edf116	204	3.</para></listitem>
caa94887 LP	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
16dad32e	246	<listitem><para>Sort the control groups
caa94887	247	by path, number of tasks, CPU load,
16dad32e AE	248	memory usage, or IO
16dad32e AE	249	load, respectively.</para></listitem>
caa94887 LP	250	</varlistentry>
caa94887 LP	251
2bfc1eda ZJS	252	<varlistentry>
	253	<term>%</term>
	254
	255	<listitem><para>Toggle between showing CPU time as
	256	time or percentage.</para></listitem>
	257	</varlistentry>
	258
caa94887 LP	259	<varlistentry>
	260	<term>+</term>
	261	<term>-</term>
	262
16dad32e AE	263	<listitem><para>Increase
	264	or decrease refresh
	265	delay, respectively.</para></listitem>
caa94887 LP	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>