systemd-cgtop.xml revision 7ac807320a7416463d7ff3ef6ede574863a601c5
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering This file is part of systemd.
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering Copyright 2012 Lennart Poettering
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering systemd is free software; you can redistribute it and/or modify it
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering under the terms of the GNU Lesser General Public License as published by
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering the Free Software Foundation; either version 2.1 of the License, or
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering (at your option) any later version.
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering systemd is distributed in the hope that it will be useful, but
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering WITHOUT ANY WARRANTY; without even the implied warranty of
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering Lesser General Public License for more details.
5430f7f2bc7330f3088b894166bf3524a067e3d8Lennart Poettering You should have received a copy of the GNU Lesser General Public License
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering along with systemd; If not, see <http://www.gnu.org/licenses/>.
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <refentryinfo>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </authorgroup>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </refentryinfo>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <refentrytitle>systemd-cgtop</refentrytitle>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <refpurpose>Show top control groups by their resource usage</refpurpose>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <refsynopsisdiv>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </cmdsynopsis>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </refsynopsisdiv>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <para><command>systemd-cgtop</command> shows the top
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering control groups of the local Linux control group
1e913bcba3b7361d5090e3cb55098c8cdac0748aUmut Tezduyar hierarchy, ordered by their CPU, memory, or disk I/O load. The
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering display is refreshed in regular intervals (by default
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering every 1s), similar in style to
1e913bcba3b7361d5090e3cb55098c8cdac0748aUmut Tezduyar <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
1e913bcba3b7361d5090e3cb55098c8cdac0748aUmut Tezduyar If <command>systemd-cgtop</command> is not connected
1e913bcba3b7361d5090e3cb55098c8cdac0748aUmut Tezduyar to a tty, only one iteration is performed and no
1e913bcba3b7361d5090e3cb55098c8cdac0748aUmut Tezduyar columns headers are printed. This mode is suitable for
1e913bcba3b7361d5090e3cb55098c8cdac0748aUmut Tezduyar scripting.</para>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <para>Resource usage is only accounted for control
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering groups in the relevant hierarchy, i.e. CPU usage is
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering only accounted for control groups in the
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <literal>cpuacct</literal> hierarchy, memory usage
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering only for those in <literal>memory</literal> and disk
7ac807320a7416463d7ff3ef6ede574863a601c5Lennart Poettering I/O usage for those in <literal>blkio</literal>. If
7ac807320a7416463d7ff3ef6ede574863a601c5Lennart Poettering resource monitoring for these resources is required,
7ac807320a7416463d7ff3ef6ede574863a601c5Lennart Poettering it is recommended to add the
7ac807320a7416463d7ff3ef6ede574863a601c5Lennart Poettering <varname>MemoryAccounting=1</varname> and
7ac807320a7416463d7ff3ef6ede574863a601c5Lennart Poettering <varname>BlockIOAccounting=1</varname> settings in the
7ac807320a7416463d7ff3ef6ede574863a601c5Lennart Poettering unit files in question (See
7ac807320a7416463d7ff3ef6ede574863a601c5Lennart Poettering <citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>5</manvolnum></citerefentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering for details).</para>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <para>To emphasize this: unless
7ac807320a7416463d7ff3ef6ede574863a601c5Lennart Poettering <literal>MemoryAccounting=1</literal> and
7ac807320a7416463d7ff3ef6ede574863a601c5Lennart Poettering <literal>BlockIOAccounting=1</literal> are enabled for
7ac807320a7416463d7ff3ef6ede574863a601c5Lennart Poettering the services in question no resource accounting will
7ac807320a7416463d7ff3ef6ede574863a601c5Lennart Poettering be available for system services and the data shown by
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering incomplete.</para>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <para>The following options are understood:</para>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <variablelist>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek <term><option>--version</option></term>
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek <listitem><para>Prints a version string and
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering tasks in control
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering group (i.e. threads and processes).</para></listitem>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <listitem><para>Order by CPU load.</para></listitem>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <listitem><para>Order by memory usage.</para></listitem>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <listitem><para>Order by disk I/O load.</para></listitem>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek <term><option>-b</option></term>
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek <term><option>--batch</option></term>
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek <listitem><para>Run in "batch" mode:
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek do not accept input and run until the
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek iteration limit set with
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek <option>--iterations</option> is
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek exhausted or until killed. This mode
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek could be useful for sending output
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek from <command>systemd-cgtop</command>
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek to other programs or to a
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek <term><option>-n</option></term>
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek <term><option>--iterations=</option></term>
871b876ecc6921a70b5f5e15cb9f85e0b6f2d1a5Zbigniew Jędrzejewski-Szmek <listitem><para>Perform only this many
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering in seconds (or if one of
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering unit in this time
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering tree traversal depth. Specifies how
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering shall traverse the control group
79640424059328268b9fb6c5fa8eb777b27a177eJan Engelhardt hierarchies. If 0 is specified, only
79640424059328268b9fb6c5fa8eb777b27a177eJan Engelhardt the root group is monitored. For 1,
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering only the first level of control groups
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering is monitored, and so on. Defaults to
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </variablelist>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <para><command>systemd-cgtop</command> is an
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering interactive tool and may be controlled via user input
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering using the following keys:</para>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <variablelist>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <listitem><para>Shows a short help text.</para></listitem>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <listitem><para>Immediately refresh output.</para></listitem>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <listitem><para>Terminate the program.</para></listitem>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering by path, number of tasks, CPU load,
16dad32e437fdf2ffca03cc60a083d84bd31886fAndrew Eikum memory usage, or IO
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
2bfc1edad87fbad005f79f9040af8efbbe1ca6a0Zbigniew Jędrzejewski-Szmek <listitem><para>Toggle between showing CPU time as
2bfc1edad87fbad005f79f9040af8efbbe1ca6a0Zbigniew Jędrzejewski-Szmek time or percentage.</para></listitem>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <varlistentry>
16dad32e437fdf2ffca03cc60a083d84bd31886fAndrew Eikum or decrease refresh
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </varlistentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering </variablelist>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <para>On success 0 is returned, a non-zero failure
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering code otherwise.</para>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
7ac807320a7416463d7ff3ef6ede574863a601c5Lennart Poettering <citerefentry><refentrytitle>systemd.cgroup</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>