1SYSTEMD-CGTOP(1) systemd-cgtop SYSTEMD-CGTOP(1)
2
6 systemd-cgtop - Show top control groups by their resource usage
7
9 systemd-cgtop [OPTIONS...] [GROUP]
10
12 systemd-cgtop shows the top control groups of the local Linux control
13 group hierarchy, ordered by their CPU, memory, or disk I/O load. The
14 display is refreshed in regular intervals (by default every 1s),
15 similar in style to top(1). If a control group path is specified, shows
16 only the services of the specified control group.
17 If systemd-cgtop is not connected to a tty, no column headers are
19 printed and the default is to only run one iteration. The --iterations=
20 argument, if given, is honored. This mode is suitable for scripting.
21 Resource usage is only accounted for control groups with the
23 appropriate controllers turned on: "cpu" controller for CPU usage,
24 "memory" controller for memory usage, and "io" controller for disk I/O
25 consumption. If resource monitoring for these resources is required, it
26 is recommended to add the CPUAccounting=1, MemoryAccounting=1 and
27 IOAccounting=1 settings in the unit files in question. See
28 systemd.resource-control(5) for details.
29 The CPU load value can be between 0 and 100 times the number of
31 processors the system has. For example, if the system has 8 processors,
32 the CPU load value is going to be between 0% and 800%. The number of
33 processors can be found in "/proc/cpuinfo".
34 To emphasize: unless "CPUAccounting=1", "MemoryAccounting=1", and
36 "IOAccounting=1" are enabled for the services in question, no resource
37 accounting will be available for system services and the data shown by
38 systemd-cgtop will be incomplete.
39
41 The following options are understood:
42 -p, --order=path
44 Order by control group path name.
45 -t, --order=tasks
47 Order by number of tasks/processes in the control group.
48 -c, --order=cpu
50 Order by CPU load.
51 -m, --order=memory
53 Order by memory usage.
54 -i, --order=io
56 Order by disk I/O load.
57 -b, --batch
59 Run in "batch" mode: do not accept input and run until the
60 iteration limit set with --iterations= is exhausted or until
61 killed. This mode could be useful for sending output from
62 systemd-cgtop to other programs or to a file.
63 -r, --raw
65 Format byte counts (as in memory usage and I/O metrics) and CPU
66 time with raw numeric values rather than human-readable numbers.
67 --cpu=percentage, --cpu=time
69 Controls whether the CPU usage is shown as percentage or time. By
70 default, the CPU usage is shown as percentage. This setting may
71 also be toggled at runtime by pressing the % key.
72 -P
74 Count only userspace processes instead of all tasks. By default,
75 all tasks are counted: each kernel thread and each userspace thread
76 individually. With this setting, kernel threads are excluded from
77 the count and each userspace process only counts as one task,
78 regardless of how many threads it consists of. This setting may
79 also be toggled at runtime by pressing the P key. This option may
80 not be combined with -k.
81 -k
83 Count only userspace processes and kernel threads instead of all
84 tasks. By default, all tasks are counted: each kernel thread and
85 each userspace thread individually. With this setting, kernel
86 threads are included in the count and each userspace process only
87 counts as one task, regardless of how many threads it consists of.
88 This setting may also be toggled at runtime by pressing the k key.
89 This option may not be combined with -P.
90 --recursive=
92 Controls whether the number of processes shown for a control group
93 shall include all processes that are contained in any of the child
94 control groups as well. Takes a boolean argument, which defaults to
95 "yes". If enabled, the processes in child control groups are
96 included, if disabled, only the processes in the control group
97 itself are counted. This setting may also be toggled at runtime by
98 pressing the r key. Note that this setting only applies to process
99 counting, i.e. when the -P or -k options are used. It has not
100 effect if all tasks are counted, in which case the counting is
101 always recursive.
102 -n, --iterations=
104 Perform only this many iterations. A value of 0 indicates that the
105 program should run indefinitely.
106 -1
108 A shortcut for --iterations=1.
109 -d, --delay=
111 Specify refresh delay in seconds (or if one of "ms", "us", "min" is
112 specified as unit in this time unit). This setting may also be
113 increased and decreased at runtime by pressing the + and - keys.
114 --depth=
116 Maximum control group tree traversal depth. Specifies how deep
117 systemd-cgtop shall traverse the control group hierarchies. If 0 is
118 specified, only the root group is monitored. For 1, only the first
119 level of control groups is monitored, and so on. Defaults to 3.
120 -M MACHINE, --machine=MACHINE
122 Limit control groups shown to the part corresponding to the
123 container MACHINE. This option may not be used when a control group
124 path is specified.
125 -h, --help
127 Print a short help text and exit.
128 --version
130 Print a short version string and exit.
131
133 systemd-cgtop is an interactive tool and may be controlled via user
134 input using the following keys:
135 h
137 Shows a short help text.
138 Space
140 Immediately refresh output.
141 q
143 Terminate the program.
144 p, t, c, m, i
146 Sort the control groups by path, number of tasks, CPU load, memory
147 usage, or I/O load, respectively. This setting may also be
148 controlled using the --order= command line switch.
149 %
151 Toggle between showing CPU time as time or percentage. This setting
152 may also be controlled using the --cpu= command line switch.
153 +, -
155 Increase or decrease refresh delay, respectively. This setting may
156 also be controlled using the --delay= command line switch.
157 P
159 Toggle between counting all tasks, or only userspace processes.
160 This setting may also be controlled using the -P command line
161 switch (see above).
162 k
164 Toggle between counting all tasks, or only userspace processes and
165 kernel threads. This setting may also be controlled using the -k
166 command line switch (see above).
167 r
169 Toggle between recursively including or excluding processes in
170 child control groups in control group process counts. This setting
171 may also be controlled using the --recursive= command line switch.
172 This key is not available if all tasks are counted, it is only
173 available if processes are counted, as enabled with the P or k
174 keys.
175
177 On success, 0 is returned, a non-zero failure code otherwise.
178
180 systemd(1), systemctl(1), systemd-cgls(1), systemd.resource-control(5),
181 top(1)
182systemd 254 SYSTEMD-CGTOP(1)