'\" t .TH "SYSTEMD\-CGTOP" "1" "" "systemd 256.7" "systemd-cgtop" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" systemd-cgtop \- Show top control groups by their resource usage .SH "SYNOPSIS" .HP \w'\fBsystemd\-cgtop\fR\ 'u \fBsystemd\-cgtop\fR [OPTIONS...] [GROUP] .SH "DESCRIPTION" .PP \fBsystemd\-cgtop\fR 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 \fBtop\fR(1)\&. If a control group path is specified, shows only the services of the specified control group\&. .PP If \fBsystemd\-cgtop\fR is not connected to a tty, no column headers are printed and the default is to only run one iteration\&. The \fB\-\-iterations=\fR argument, if given, is honored\&. This mode is suitable for scripting\&. .PP Resource usage is only accounted for control groups with the appropriate controllers turned on: "cpu" controller for CPU usage, "memory" controller for memory usage, and "io" controller for disk I/O consumption\&. If resource monitoring for these resources is required, it is recommended to add the \fICPUAccounting=1\fR, \fIMemoryAccounting=1\fR and \fIIOAccounting=1\fR settings in the unit files in question\&. See \fBsystemd.resource-control\fR(5) for details\&. .PP The CPU load value can be between 0 and 100 times the number of processors the system has\&. For example, if the system has 8 processors, the CPU load value is going to be between 0% and 800%\&. The number of processors can be found in "/proc/cpuinfo"\&. .PP To emphasize: unless "CPUAccounting=1", "MemoryAccounting=1", and "IOAccounting=1" are enabled for the services in question, no resource accounting will be available for system services and the data shown by \fBsystemd\-cgtop\fR will be incomplete\&. .SH "OPTIONS" .PP The following options are understood: .PP \fB\-p\fR, \fB\-\-order=path\fR .RS 4 Order by control group path name\&. .RE .PP \fB\-t\fR, \fB\-\-order=tasks\fR .RS 4 Order by number of tasks/processes in the control group\&. .RE .PP \fB\-c\fR, \fB\-\-order=cpu\fR .RS 4 Order by CPU load\&. .RE .PP \fB\-m\fR, \fB\-\-order=memory\fR .RS 4 Order by memory usage\&. .RE .PP \fB\-i\fR, \fB\-\-order=io\fR .RS 4 Order by disk I/O load\&. .RE .PP \fB\-b\fR, \fB\-\-batch\fR .RS 4 Run in "batch" mode: do not accept input and run until the iteration limit set with \fB\-\-iterations=\fR is exhausted or until killed\&. This mode could be useful for sending output from \fBsystemd\-cgtop\fR to other programs or to a file\&. .sp Added in version 188\&. .RE .PP \fB\-r\fR, \fB\-\-raw\fR .RS 4 Format byte counts (as in memory usage and I/O metrics) and CPU time with raw numeric values rather than human\-readable numbers\&. .sp Added in version 221\&. .RE .PP \fB\-\-cpu=percentage\fR, \fB\-\-cpu=time\fR .RS 4 Controls whether the CPU usage is shown as percentage or time\&. By default, the CPU usage is shown as percentage\&. This setting may also be toggled at runtime by pressing the % key\&. .sp Added in version 226\&. .RE .PP \fB\-P\fR .RS 4 Count only userspace processes instead of all tasks\&. By default, all tasks are counted: each kernel thread and each userspace thread individually\&. With this setting, kernel threads are excluded from the count and each userspace process only counts as one task, regardless of how many threads it consists of\&. This setting may also be toggled at runtime by pressing the P key\&. This option may not be combined with \fB\-k\fR\&. .sp Added in version 227\&. .RE .PP \fB\-k\fR .RS 4 Count only userspace processes and kernel threads instead of all tasks\&. By default, all tasks are counted: each kernel thread and each userspace thread individually\&. With this setting, kernel threads are included in the count and each userspace process only counts as one task, regardless of how many threads it consists of\&. This setting may also be toggled at runtime by pressing the k key\&. This option may not be combined with \fB\-P\fR\&. .sp Added in version 226\&. .RE .PP \fB\-\-recursive=\fR .RS 4 Controls whether the number of processes shown for a control group shall include all processes that are contained in any of the child control groups as well\&. Takes a boolean argument, which defaults to "yes"\&. If enabled, the processes in child control groups are included, if disabled, only the processes in the control group itself are counted\&. This setting may also be toggled at runtime by pressing the r key\&. Note that this setting only applies to process counting, i\&.e\&. when the \fB\-P\fR or \fB\-k\fR options are used\&. It has not effect if all tasks are counted, in which case the counting is always recursive\&. .sp Added in version 226\&. .RE .PP \fB\-n\fR, \fB\-\-iterations=\fR .RS 4 Perform only this many iterations\&. A value of 0 indicates that the program should run indefinitely\&. .sp Added in version 188\&. .RE .PP \fB\-1\fR .RS 4 A shortcut for \fB\-\-iterations=1\fR\&. .sp Added in version 238\&. .RE .PP \fB\-d\fR, \fB\-\-delay=\fR .RS 4 Specify refresh delay in seconds (or if one of "ms", "us", "min" is specified as unit in this time unit)\&. This setting may also be increased and decreased at runtime by pressing the + and \- keys\&. .RE .PP \fB\-\-depth=\fR .RS 4 Maximum control group tree traversal depth\&. Specifies how deep \fBsystemd\-cgtop\fR 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\&. .RE .PP \fB\-M \fR\fB\fIMACHINE\fR\fR, \fB\-\-machine=\fR\fB\fIMACHINE\fR\fR .RS 4 Limit control groups shown to the part corresponding to the container \fIMACHINE\fR\&. This option may not be used when a control group path is specified\&. .sp Added in version 227\&. .RE .PP \fB\-h\fR, \fB\-\-help\fR .RS 4 Print a short help text and exit\&. .RE .PP \fB\-\-version\fR .RS 4 Print a short version string and exit\&. .RE .SH "KEYS" .PP \fBsystemd\-cgtop\fR is an interactive tool and may be controlled via user input using the following keys: .PP h .RS 4 Shows a short help text\&. .RE .PP Space .RS 4 Immediately refresh output\&. .sp Added in version 226\&. .RE .PP q .RS 4 Terminate the program\&. .RE .PP p, t, c, m, i .RS 4 Sort the control groups by path, number of tasks, CPU load, memory usage, or I/O load, respectively\&. This setting may also be controlled using the \fB\-\-order=\fR command line switch\&. .RE .PP % .RS 4 Toggle between showing CPU time as time or percentage\&. This setting may also be controlled using the \fB\-\-cpu=\fR command line switch\&. .sp Added in version 201\&. .RE .PP +, \- .RS 4 Increase or decrease refresh delay, respectively\&. This setting may also be controlled using the \fB\-\-delay=\fR command line switch\&. .RE .PP P .RS 4 Toggle between counting all tasks, or only userspace processes\&. This setting may also be controlled using the \fB\-P\fR command line switch (see above)\&. .sp Added in version 227\&. .RE .PP k .RS 4 Toggle between counting all tasks, or only userspace processes and kernel threads\&. This setting may also be controlled using the \fB\-k\fR command line switch (see above)\&. .sp Added in version 226\&. .RE .PP r .RS 4 Toggle between recursively including or excluding processes in child control groups in control group process counts\&. This setting may also be controlled using the \fB\-\-recursive=\fR command line switch\&. This key is not available if all tasks are counted, it is only available if processes are counted, as enabled with the P or k keys\&. .sp Added in version 226\&. .RE .SH "EXIT STATUS" .PP On success, 0 is returned, a non\-zero failure code otherwise\&. .SH "SEE ALSO" .PP \fBsystemd\fR(1), \fBsystemctl\fR(1), \fBsystemd-cgls\fR(1), \fBsystemd.resource-control\fR(5), \fBtop\fR(1)