Debian Codegraph @

upstream/debian-trixie/man1/systemd-cgtop.1

raw
1 '\" t
2 .TH "SYSTEMD\-CGTOP" "1" "" "systemd 257.13" "systemd-cgtop"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 systemd-cgtop \- Show top control groups by their resource usage
24 .SH "SYNOPSIS"
25 .HP \w'\fBsystemd\-cgtop\fR\ 'u
26 \fBsystemd\-cgtop\fR [OPTIONS...] [GROUP]
27 .SH "DESCRIPTION"
28 .PP
29 \fBsystemd\-cgtop\fR
30 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
31 \fBtop\fR(1)\&. If a control group path is specified, shows only the services of the specified control group\&.
32 .PP
33 If
34 \fBsystemd\-cgtop\fR
35 is not connected to a tty, no column headers are printed and the default is to only run one iteration\&. The
36 \fB\-\-iterations=\fR
37 argument, if given, is honored\&. This mode is suitable for scripting\&.
38 .PP
39 Resource usage is only accounted for control groups with the appropriate controllers turned on:
40 "cpu"
41 controller for CPU usage,
42 "memory"
43 controller for memory usage, and
44 "io"
45 controller for disk I/O consumption\&. If resource monitoring for these resources is required, it is recommended to add the
46 \fICPUAccounting=1\fR,
47 \fIMemoryAccounting=1\fR
48 and
49 \fIIOAccounting=1\fR
50 settings in the unit files in question\&. See
51 \fBsystemd.resource-control\fR(5)
52 for details\&.
53 .PP
54 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
55 "/proc/cpuinfo"\&.
56 .PP
57 To emphasize: unless
58 "CPUAccounting=1",
59 "MemoryAccounting=1", and
60 "IOAccounting=1"
61 are enabled for the services in question, no resource accounting will be available for system services and the data shown by
62 \fBsystemd\-cgtop\fR
63 will be incomplete\&.
64 .SH "OPTIONS"
65 .PP
66 The following options are understood:
67 .PP
68 \fB\-p\fR, \fB\-\-order=path\fR
69 .RS 4
70 Order by control group path name\&.
71 .RE
72 .PP
73 \fB\-t\fR, \fB\-\-order=tasks\fR
74 .RS 4
75 Order by number of tasks/processes in the control group\&.
76 .RE
77 .PP
78 \fB\-c\fR, \fB\-\-order=cpu\fR
79 .RS 4
80 Order by CPU load\&.
81 .RE
82 .PP
83 \fB\-m\fR, \fB\-\-order=memory\fR
84 .RS 4
85 Order by memory usage\&.
86 .RE
87 .PP
88 \fB\-i\fR, \fB\-\-order=io\fR
89 .RS 4
90 Order by disk I/O load\&.
91 .RE
92 .PP
93 \fB\-b\fR, \fB\-\-batch\fR
94 .RS 4
95 Run in "batch" mode: do not accept input and run until the iteration limit set with
96 \fB\-\-iterations=\fR
97 is exhausted or until killed\&. This mode could be useful for sending output from
98 \fBsystemd\-cgtop\fR
99 to other programs or to a file\&.
100 .sp
101 Added in version 188\&.
102 .RE
103 .PP
104 \fB\-r\fR, \fB\-\-raw\fR
105 .RS 4
106 Format byte counts (as in memory usage and I/O metrics) and CPU time with raw numeric values rather than human\-readable numbers\&.
107 .sp
108 Added in version 221\&.
109 .RE
110 .PP
111 \fB\-\-cpu=percentage\fR, \fB\-\-cpu=time\fR
112 .RS 4
113 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
114 %
115 key\&.
116 .sp
117 Added in version 226\&.
118 .RE
119 .PP
120 \fB\-P\fR
121 .RS 4
122 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
123 P
124 key\&. This option may not be combined with
125 \fB\-k\fR\&.
126 .sp
127 Added in version 227\&.
128 .RE
129 .PP
130 \fB\-k\fR
131 .RS 4
132 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
133 k
134 key\&. This option may not be combined with
135 \fB\-P\fR\&.
136 .sp
137 Added in version 226\&.
138 .RE
139 .PP
140 \fB\-\-recursive=\fR
141 .RS 4
142 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
143 "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
144 r
145 key\&. Note that this setting only applies to process counting, i\&.e\&. when the
146 \fB\-P\fR
147 or
148 \fB\-k\fR
149 options are used\&. It has no effect if all tasks are counted, in which case the counting is always recursive\&.
150 .sp
151 Added in version 226\&.
152 .RE
153 .PP
154 \fB\-n\fR, \fB\-\-iterations=\fR
155 .RS 4
156 Perform only this many iterations\&. A value of 0 indicates that the program should run indefinitely\&.
157 .sp
158 Added in version 188\&.
159 .RE
160 .PP
161 \fB\-1\fR
162 .RS 4
163 A shortcut for
164 \fB\-\-iterations=1\fR\&.
165 .sp
166 Added in version 238\&.
167 .RE
168 .PP
169 \fB\-d\fR, \fB\-\-delay=\fR
170 .RS 4
171 Specify refresh delay in seconds (or if one of
172 "ms",
173 "us",
174 "min"
175 is specified as unit in this time unit)\&. This setting may also be increased and decreased at runtime by pressing the
176 +
177 and
178 \-
179 keys\&.
180 .RE
181 .PP
182 \fB\-\-depth=\fR
183 .RS 4
184 Maximum control group tree traversal depth\&. Specifies how deep
185 \fBsystemd\-cgtop\fR
186 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\&.
187 .RE
188 .PP
189 \fB\-M \fR\fB\fIMACHINE\fR\fR, \fB\-\-machine=\fR\fB\fIMACHINE\fR\fR
190 .RS 4
191 Limit control groups shown to the part corresponding to the container
192 \fIMACHINE\fR\&. This option may not be used when a control group path is specified\&.
193 .sp
194 Added in version 227\&.
195 .RE
196 .PP
197 \fB\-h\fR, \fB\-\-help\fR
198 .RS 4
199 Print a short help text and exit\&.
200 .RE
201 .PP
202 \fB\-\-version\fR
203 .RS 4
204 Print a short version string and exit\&.
205 .RE
206 .SH "KEYS"
207 .PP
208 \fBsystemd\-cgtop\fR
209 is an interactive tool and may be controlled via user input using the following keys:
210 .PP
211 h
212 .RS 4
213 Shows a short help text\&.
214 .RE
215 .PP
216 Space
217 .RS 4
218 Immediately refresh output\&.
219 .sp
220 Added in version 226\&.
221 .RE
222 .PP
223 q
224 .RS 4
225 Terminate the program\&.
226 .RE
227 .PP
228 p, t, c, m, i
229 .RS 4
230 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
231 \fB\-\-order=\fR
232 command line switch\&.
233 .RE
234 .PP
235 %
236 .RS 4
237 Toggle between showing CPU time as time or percentage\&. This setting may also be controlled using the
238 \fB\-\-cpu=\fR
239 command line switch\&.
240 .sp
241 Added in version 201\&.
242 .RE
243 .PP
244 +, \-
245 .RS 4
246 Increase or decrease refresh delay, respectively\&. This setting may also be controlled using the
247 \fB\-\-delay=\fR
248 command line switch\&.
249 .RE
250 .PP
251 P
252 .RS 4
253 Toggle between counting all tasks, or only userspace processes\&. This setting may also be controlled using the
254 \fB\-P\fR
255 command line switch (see above)\&.
256 .sp
257 Added in version 227\&.
258 .RE
259 .PP
260 k
261 .RS 4
262 Toggle between counting all tasks, or only userspace processes and kernel threads\&. This setting may also be controlled using the
263 \fB\-k\fR
264 command line switch (see above)\&.
265 .sp
266 Added in version 226\&.
267 .RE
268 .PP
269 r
270 .RS 4
271 Toggle between recursively including or excluding processes in child control groups in control group process counts\&. This setting may also be controlled using the
272 \fB\-\-recursive=\fR
273 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
274 P
275 or
276 k
277 keys\&.
278 .sp
279 Added in version 226\&.
280 .RE
281 .SH "EXIT STATUS"
282 .PP
283 On success, 0 is returned, a non\-zero failure code otherwise\&.
284 .SH "SEE ALSO"
285 .PP
286 \fBsystemd\fR(1), \fBsystemctl\fR(1), \fBsystemd-cgls\fR(1), \fBsystemd.resource-control\fR(5), \fBtop\fR(1)