along with systemd; If not, see <http://www.gnu.org/licenses/>.
-->
-<refentry id="systemd-cgtop">
+<refentry id="systemd-cgtop"
+ xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>systemd-cgtop</title>
<refsynopsisdiv>
<cmdsynopsis>
- <command>systemd-cgtop <arg choice="opt" rep="repeat">OPTIONS</arg></command>
+ <command>systemd-cgtop</command>
+ <arg choice="opt" rep="repeat">OPTIONS</arg>
</cmdsynopsis>
</refsynopsisdiv>
<para><command>systemd-cgtop</command> shows the top
control groups of the local Linux control group
- hierarchy, ordered by their CPU, memory and disk I/O load. The
+ 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>.</para>
+ <citerefentry project='man-pages'><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.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>
+ 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>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
+ <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>
<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>-p</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>
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
+ 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>
+ <xi:include href="standard-options.xml" xpointer="help" />
+ <xi:include href="standard-options.xml" xpointer="version" />
</variablelist>
</refsect1>
<term>m</term>
<term>i</term>
- <listitem><para>Change ordering of control groups
+ <listitem><para>Sort the control groups
by path, number of tasks, CPU load,
- memory usage resp. IO
- load.</para></listitem>
+ 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,
- resp. decrease refresh
- delay.</para></listitem>
+ <listitem><para>Increase
+ or decrease refresh
+ delay, respectively.</para></listitem>
</varlistentry>
</variablelist>
<refsect1>
<title>Exit status</title>
- <para>On success 0 is returned, a non-zero failure
+ <para>On success, 0 is returned, a non-zero failure
code otherwise.</para>
</refsect1>
<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>
+ <citerefentry><refentrytitle>systemd.resource-control</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
+ <citerefentry project='man-pages'><refentrytitle>top</refentrytitle><manvolnum>1</manvolnum></citerefentry>
</para>
</refsect1>