systemd-cgtop.xml revision 5f9cfd4c3877fdc68618faf9ae5efb5948e002b6
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 <command>systemd-cgtop <arg choice="opt" rep="repeat">OPTIONS</arg></command>
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
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering hierarchy, ordered by their CPU, memory and disk I/O load. The
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering display is refreshed in regular intervals (by default
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering every 1s), similar in style to
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</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
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering I/O usage for those in
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <literal>blkio</literal>. <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering by default places all services in their own control
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering group in the <literal>cpuacct</literal> hierarchy, but
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <literal>blkio</literal>. If resource monitoring for
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering these resources is required it is recommended to add
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <literal>blkio</literal> and <literal>memory</literal>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering to the <varname>DefaultControllers=</varname> setting
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering in <filename>/etc/systemd/system.conf</filename> (see
5f9cfd4c3877fdc68618faf9ae5efb5948e002b6Zbigniew Jędrzejewski-Szmek <citerefentry><refentrytitle>systemd-system.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering for details). Alternatively, it is possible to enable
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering resource accounting individually for services, by
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering making use of the <varname>ControlGroup=</varname>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering option in the unit files (See
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering for details).</para>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <para>To emphasize this: unless
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <literal>blkio</literal> and <literal>memory</literal>
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering are enabled for the services in question with either
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering of the options suggested above no resource accounting
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering will be available for system services and the data shown
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering by <command>systemd-cgtop</command> will be
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
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering hierarchies. If 0 is specified only
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering 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>
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>,
caa94887002de8596c69f578dbdb684dfb368240Lennart Poettering <citerefentry><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>