Debian Codegraph @

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

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