systemd-cgtop.xml revision 96a6426f30dc9bf3c4dd1f61548c334fa12034df
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx<?xml version='1.0'?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx This file is part of systemd.
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx Copyright 2012 Lennart Poettering
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx systemd is free software; you can redistribute it and/or modify it
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx under the terms of the GNU Lesser General Public License as published by
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx the Free Software Foundation; either version 2.1 of the License, or
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx (at your option) any later version.
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx systemd is distributed in the hope that it will be useful, but
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx WITHOUT ANY WARRANTY; without even the implied warranty of
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx Lesser General Public License for more details.
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx You should have received a copy of the GNU Lesser General Public License
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx along with systemd; If not, see <http://www.gnu.org/licenses/>.
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <refentryinfo>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <authorgroup>
d745ba0f110b40026922ac40599ec47c511eafefdirkx </authorgroup>
d745ba0f110b40026922ac40599ec47c511eafefdirkx </refentryinfo>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <refnamediv>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <refpurpose>Show top control groups by their resource usage</refpurpose>
cf3b56dc9c3033d7b20a3198b11865c1b311b6b4dirkx </refnamediv>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <refsynopsisdiv>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <cmdsynopsis>
1fb799609e09dd1df20777bef567d27059d90202dirkx </cmdsynopsis>
1fb799609e09dd1df20777bef567d27059d90202dirkx </refsynopsisdiv>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <para><command>systemd-cgtop</command> shows the top control
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx groups of the local Linux control group hierarchy, ordered by
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx their CPU, memory, or disk I/O load. The display is refreshed in
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx regular intervals (by default every 1s), similar in style to
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>.</para>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <para>If <command>systemd-cgtop</command> is not connected to a
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx tty, no column headers are printed and the default is to only run
1fb799609e09dd1df20777bef567d27059d90202dirkx one iteration. The <varname>--iterations=</varname> argument, if
1fb799609e09dd1df20777bef567d27059d90202dirkx given, is honored. This mode is suitable for scripting.</para>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <para>Resource usage is only accounted for control groups in the
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx relevant hierarchy, i.e. CPU usage is only accounted for control
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx groups in the <literal>cpuacct</literal> hierarchy, memory usage
d745ba0f110b40026922ac40599ec47c511eafefdirkx only for those in <literal>memory</literal> and disk I/O usage for
d745ba0f110b40026922ac40599ec47c511eafefdirkx those in <literal>blkio</literal>. If resource monitoring for
d745ba0f110b40026922ac40599ec47c511eafefdirkx these resources is required, it is recommended to add the
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varname>BlockIOAccounting=1</varname> settings in the unit files
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx in question. See
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx for details.</para>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <para>The CPU load value can be between 0 and 100 times the number of
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx processors the system has. For example, if the system has 8 processors,
cf3b56dc9c3033d7b20a3198b11865c1b311b6b4dirkx the CPU load value is going to be between 0% and 800%. The number of
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx processors can be found in <literal>/proc/cpuinfo</literal>.</para>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <para>To emphasize this: unless
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <literal>BlockIOAccounting=1</literal> are enabled for the
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx services in question, no resource accounting will be available for
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx system services and the data shown by
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <command>systemd-cgtop</command> will be incomplete.</para>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </refsect1>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <variablelist>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <listitem><para>Order by number of tasks/processes in the control group.</para></listitem>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
b39725d4d5fd6bc177cd55adbde927ea7a80af80dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <listitem><para>Order by memory usage.</para></listitem>
d745ba0f110b40026922ac40599ec47c511eafefdirkx </varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <varlistentry>
b39725d4d5fd6bc177cd55adbde927ea7a80af80dirkx <listitem><para>Order by disk I/O load.</para></listitem>
d745ba0f110b40026922ac40599ec47c511eafefdirkx </varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <listitem><para>Run in "batch" mode: do not accept input and
d745ba0f110b40026922ac40599ec47c511eafefdirkx run until the iteration limit set with
d745ba0f110b40026922ac40599ec47c511eafefdirkx <option>--iterations=</option> is exhausted or until killed.
d745ba0f110b40026922ac40599ec47c511eafefdirkx This mode could be useful for sending output from
d745ba0f110b40026922ac40599ec47c511eafefdirkx <command>systemd-cgtop</command> to other programs or to a
d745ba0f110b40026922ac40599ec47c511eafefdirkx </varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <listitem><para>Format byte counts (as in memory usage and IO metrics)
d745ba0f110b40026922ac40599ec47c511eafefdirkx with raw numeric values rather than human-readable
d745ba0f110b40026922ac40599ec47c511eafefdirkx </varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <listitem><para>Controls whether the CPU usage is shown as
d745ba0f110b40026922ac40599ec47c511eafefdirkx percentage or time. By default the CPU usage is shown as
d745ba0f110b40026922ac40599ec47c511eafefdirkx percentage. This setting may also be toggled at runtime by
d745ba0f110b40026922ac40599ec47c511eafefdirkx pressing the <keycap>%</keycap> key.</para></listitem>
d745ba0f110b40026922ac40599ec47c511eafefdirkx </varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <listitem><para>Count only userspace processes instead of all
d745ba0f110b40026922ac40599ec47c511eafefdirkx tasks. By default all tasks are counted: each kernel thread
d745ba0f110b40026922ac40599ec47c511eafefdirkx and each userspace thread individually. With this setting
d745ba0f110b40026922ac40599ec47c511eafefdirkx kernel threads are excluded from the counting and each
d745ba0f110b40026922ac40599ec47c511eafefdirkx userspace process only counts as one, regardless how many
d745ba0f110b40026922ac40599ec47c511eafefdirkx threads it consists of. This setting may also be toggled at
d745ba0f110b40026922ac40599ec47c511eafefdirkx runtime by pressing the <keycap>P</keycap> key. This option
d745ba0f110b40026922ac40599ec47c511eafefdirkx may not be combined with
d745ba0f110b40026922ac40599ec47c511eafefdirkx </varlistentry>
1fb799609e09dd1df20777bef567d27059d90202dirkx <varlistentry>
1fb799609e09dd1df20777bef567d27059d90202dirkx <listitem><para>Count only userspace processes and kernel
1fb799609e09dd1df20777bef567d27059d90202dirkx threads instead of all tasks. By default all tasks are
1fb799609e09dd1df20777bef567d27059d90202dirkx counted: each kernel thread and each userspace thread
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx individually. With this setting kernel threads are included in
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx the counting and each userspace process only counts as on one,
1fb799609e09dd1df20777bef567d27059d90202dirkx regardless how many threads it consists of. This setting may
1fb799609e09dd1df20777bef567d27059d90202dirkx also be toggled at runtime by pressing the <keycap>k</keycap>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx key. This option may not be combined with
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <listitem><para>Controls whether the number of processes shown
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx for a control group shall include all processes that are
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx contained in any of the child control groups as well. Takes a
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx boolean argument, defaults to <literal>yes</literal>. If
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx enabled the processes in child control groups are included, if
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx disabled only the processes in the control group itself are
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx counted. This setting may also be toggled at runtime by
1fb799609e09dd1df20777bef567d27059d90202dirkx pressing the <keycap>r</keycap> key. Note that this setting
1fb799609e09dd1df20777bef567d27059d90202dirkx only applies to process counting, i.e. when the
1fb799609e09dd1df20777bef567d27059d90202dirkx <option>-P</option> or <option>-k</option> options are
1fb799609e09dd1df20777bef567d27059d90202dirkx used. It has not effect if all tasks are counted, in which
1fb799609e09dd1df20777bef567d27059d90202dirkx case the counting is always recursive.</para></listitem>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <listitem><para>Perform only this many iterations. A value of
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx 0 indicates that the program should run
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <listitem><para>Specify refresh delay in seconds (or if one of
1fb799609e09dd1df20777bef567d27059d90202dirkx <literal>min</literal> is specified as unit in this time
1fb799609e09dd1df20777bef567d27059d90202dirkx unit). This setting may also be increased and decreased at
1fb799609e09dd1df20777bef567d27059d90202dirkx </varlistentry>
1fb799609e09dd1df20777bef567d27059d90202dirkx <varlistentry>
1fb799609e09dd1df20777bef567d27059d90202dirkx <listitem><para>Maximum control group tree traversal depth.
1fb799609e09dd1df20777bef567d27059d90202dirkx Specifies how deep <command>systemd-cgtop</command> shall
1fb799609e09dd1df20777bef567d27059d90202dirkx traverse the control group hierarchies. If 0 is specified,
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx only the root group is monitored. For 1, only the first level
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx of control groups is monitored, and so on. Defaults to
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <term><option>-M <replaceable>MACHINE</replaceable></option></term>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <term><option>--machine=<replaceable>MACHINE</replaceable></option></term>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <listitem><para>Limit control groups shown to the part
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx corresponding to the container
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <xi:include href="standard-options.xml" xpointer="help" />
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <xi:include href="standard-options.xml" xpointer="version" />
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </variablelist>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </refsect1>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <para><command>systemd-cgtop</command> is an interactive tool and
1fb799609e09dd1df20777bef567d27059d90202dirkx may be controlled via user input using the following keys:</para>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <variablelist>
1fb799609e09dd1df20777bef567d27059d90202dirkx <varlistentry>
1fb799609e09dd1df20777bef567d27059d90202dirkx <listitem><para>Shows a short help text.</para></listitem>
1fb799609e09dd1df20777bef567d27059d90202dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <listitem><para>Immediately refresh output.</para></listitem>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <listitem><para>Terminate the program.</para></listitem>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <listitem><para>Sort the control groups by path, number of
d745ba0f110b40026922ac40599ec47c511eafefdirkx tasks, CPU load, memory usage, or IO load, respectively. This
d745ba0f110b40026922ac40599ec47c511eafefdirkx setting may also be controlled using the
d745ba0f110b40026922ac40599ec47c511eafefdirkx </varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <listitem><para>Toggle between showing CPU time as time or
d745ba0f110b40026922ac40599ec47c511eafefdirkx percentage. This setting may also be controlled using the
d745ba0f110b40026922ac40599ec47c511eafefdirkx <option>--cpu=</option> command line switch.</para></listitem>
d745ba0f110b40026922ac40599ec47c511eafefdirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx respectively. This setting may also be controlled using the
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <listitem><para>Toggle between counting all tasks, or only
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx userspace processes. This setting may also be controlled using
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <varlistentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <listitem><para>Toggle between counting all tasks, or only
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx userspace processes and kernel threads. This setting may also
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx be controlled using the <option>-k</option> command line
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx <listitem><para>Toggle between recursively including or
d745ba0f110b40026922ac40599ec47c511eafefdirkx excluding processes in child control groups in control group
d745ba0f110b40026922ac40599ec47c511eafefdirkx process counts. This setting may also be controlled using the
d745ba0f110b40026922ac40599ec47c511eafefdirkx <option>--recursive=</option> command line switch. This key is
d745ba0f110b40026922ac40599ec47c511eafefdirkx not available of all tasks are counted, it is only available
d745ba0f110b40026922ac40599ec47c511eafefdirkx if processes are counted, as enabled with the
d745ba0f110b40026922ac40599ec47c511eafefdirkx </varlistentry>
d745ba0f110b40026922ac40599ec47c511eafefdirkx </variablelist>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </refsect1>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <para>On success, 0 is returned, a non-zero failure code
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx otherwise.</para>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </refsect1>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
cf3b56dc9c3033d7b20a3198b11865c1b311b6b4dirkx <citerefentry><refentrytitle>systemd-cgls</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
cf3b56dc9c3033d7b20a3198b11865c1b311b6b4dirkx <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
c002c44ee5c7e7258f4ba5c162461c24a0c179c2dirkx </refsect1>