Debian Codegraph @

upstream/opensuse-tumbleweed/man1/pidstat.1

raw
1 .\" pidstat manual page - (C) 2007-2025 Sebastien Godard (sysstat <at> orange.fr)
2 .TH PIDSTAT 1 "JANUARY 2025" Linux "Linux User's Manual" -*- nroff -*-
3 .SH NAME
4 pidstat \- Report statistics for Linux tasks.
5
6 .SH SYNOPSIS
7 .B pidstat [ \-d ] [ \-H ] [ \-h ] [ \-I ] [ \-l ] [ \-R ] [ \-r ] [ \-s ] [ \-t ] [ \-U [
8 .IB "username " "] ] [ \-u ] [ \-V ] [ \-v ] [ \-w ] [ \-C " "comm " "] [ \-G " "process_name"
9 .BI "] [ \-\-dec={ 0 | 1 | 2 } ] [ \-\-human ] [ \-o JSON ] [ \-p { " "pid" "[,...]"
10 .B | SELF | ALL } ] [ \-T { TASK | CHILD | ALL } ] [
11 .IB "interval " "[ " "count " "] ] [ \-e " "program"
12 .IB "args " "]"
13
14 .SH DESCRIPTION
15 .RB "The " "pidstat"
16 command is used for monitoring individual tasks currently being managed
17 by the Linux kernel.
18 It writes to standard output activities for every task selected with option
19 .B \-p
20 or for every task managed by the Linux kernel if option
21 .B \-p ALL
22 has been used. Not selecting any tasks is equivalent to specifying
23 .B \-p ALL
24 but only active tasks (tasks with non-zero statistics values)
25 will appear in the report.
26 .PP
27 .RB "The " "pidstat"
28 command can also be used for monitoring the child processes of selected tasks.
29 Read about option
30 .BR "\-T " "below."
31 .PP
32 .RI "The " "interval"
33 parameter specifies the amount of time in seconds between each report.
34 A value of 0 (or no parameters at all) indicates that tasks statistics are
35 to be reported for the time since system startup (boot). The
36 .IR "count " "parameter can be specified in conjunction with the"
37 .IR "interval " "parameter if this one is not set to zero. The value of"
38 .IR "count " "determines the number of reports generated at"
39 .IR "interval " "seconds apart. If the " "interval " "parameter is specified without the " "count"
40 parameter, the
41 .B pidstat
42 command generates reports continuously.
43 .PP
44 You can select information about specific task activities using flags.
45 Not specifying any flags selects only CPU activity.
46
47 .SH OPTIONS
48 .TP
49 .BI "\-C " "comm"
50 Display only tasks whose command name includes the string
51 .IR "comm" ". This string can be a regular expression."
52 .TP
53 .B \-d
54 Report I/O statistics (kernels 2.6.20 and later only).
55 The following values may be displayed:
56 .RS
57 .IP UID
58 The real user identification number of the task being monitored.
59 .IP USER
60 The name of the real user owning the task being monitored.
61 .IP PID
62 The identification number of the task being monitored.
63 .IP kB_rd/s
64 Number of kibibytes the task has caused to be read from disk per second.
65 .IP kB_wr/s
66 Number of kibibytes the task has caused, or shall cause to be
67 written to disk per second.
68 .IP kB_ccwr/s
69 Number of kibibytes whose writing to disk has been cancelled by
70 the task. This may occur when the task truncates some
71 dirty pagecache. In this case, some IO which another task has
72 been accounted for will not be happening.
73 .IP iodelay
74 Block I/O delay of the task being monitored,
75 measured in clock ticks. This metric includes the delays spent
76 waiting for sync block I/O completion and for swapin block I/O
77 completion.
78 .IP Command
79 The command name of the task.
80 .RE
81 .TP
82 .B \-\-dec={ 0 | 1 | 2 }
83 Specify the number of decimal places to use (0 to 2, default value is 2).
84 .TP
85 .BI "\-e " "program args"
86 Execute
87 .I program
88 with given arguments
89 .I args
90 and monitor it with
91 .BR "pidstat" "."
92 .BR "pidstat " "stops when"
93 .IR "program " "terminates."
94 A non-zero value must be specified for the
95 .IR "interval " "parameter."
96 .TP
97 .BI "\-G " "process_name"
98 Display only processes whose command name includes the string
99 .IR "process_name" "."
100 This string can be a regular expression. If option
101 .BR "\-t " "is used together with option " "\-G"
102 then the threads belonging to that process are also displayed
103 (even if their command name doesn't include the string
104 .IR "process_name" ")."
105 .TP
106 .B \-H
107 Display timestamp in seconds since the epoch.
108 .TP
109 .B \-h
110 Display all activities horizontally on a single line, with no
111 average statistics at the end of the report. This is
112 intended to make it easier to be parsed by other programs.
113 .TP
114 .B \-\-human
115 Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.)
116 The units displayed with this option supersede any other default units (e.g.
117 kibibytes, sectors...) associated with the metrics.
118 .TP
119 .B \-I
120 In an SMP environment, indicate that tasks CPU usage
121 .RB "(as displayed by option " "\-u" ")"
122 should be divided by the total number of processors.
123 .TP
124 .B \-l
125 Display the process command name and all its arguments.
126 .TP
127 .B \-o JSON
128 Display the statistics in JSON (JavaScript Object Notation) format.
129 JSON output field order is undefined, and new fields may be added
130 in the future.
131 .TP
132 .BI "\-p { " "pid" "[,...] | SELF | ALL }"
133 Select tasks (processes) for which statistics are to be reported.
134 .I pid
135 is the process identification number. The
136 .B SELF
137 keyword indicates that statistics are to be reported for the
138 .BR "pidstat " "process itself, whereas the " "ALL"
139 keyword indicates that statistics are to be reported for all the
140 tasks managed by the system.
141 .TP
142 .B \-R
143 Report realtime priority and scheduling policy information.
144 The following values may be displayed:
145 .RS
146 .IP UID
147 The real user identification number of the task being monitored.
148 .IP USER
149 The name of the real user owning the task being monitored.
150 .IP PID
151 The identification number of the task being monitored.
152 .IP prio
153 The realtime priority of the task being monitored.
154 .IP policy
155 The scheduling policy of the task being monitored.
156 .IP Command
157 The command name of the task.
158 .RE
159 .TP
160 .B \-r
161 Report page faults and memory utilization.
162
163 When reporting statistics for individual tasks,
164 the following values may be displayed:
165 .RS
166 .IP UID
167 The real user identification number of the task being monitored.
168 .IP USER
169 The name of the real user owning the task being monitored.
170 .IP PID
171 The identification number of the task being monitored.
172 .IP minflt/s
173 Total number of minor faults the task has made per second, those
174 which have not required loading a memory page from disk.
175 .IP majflt/s
176 Total number of major faults the task has made per second, those
177 which have required loading a memory page from disk.
178 .IP VSZ
179 Virtual Size: The virtual memory usage of entire task in kibibytes.
180 .IP RSS
181 Resident Set Size: The non-swapped physical memory
182 used by the task in kibibytes.
183 .IP %MEM
184 The tasks's currently used share of available physical memory.
185 .IP Command
186 The command name of the task.
187 .RE
188 .IP
189 When reporting global statistics for tasks and all their children,
190 the following values may be displayed:
191 .RS
192 .IP UID
193 The real user identification number of the task which is being monitored
194 together with its children.
195 .IP USER
196 The name of the real user owning the task which is being monitored
197 together with its children.
198 .IP PID
199 The identification number of the task which is being monitored
200 together with its children.
201 .IP minflt\-nr
202 Total number of minor faults made by the task and all its children,
203 and collected during the interval of time.
204 .IP majflt\-nr
205 Total number of major faults made by the task and all its children,
206 and collected during the interval of time.
207 .IP Command
208 The command name of the task which is being monitored
209 together with its children.
210 .RE
211 .TP
212 .B \-s
213 Report stack utilization.
214 The following values may be displayed:
215 .RS
216 .IP UID
217 The real user identification number of the task being monitored.
218 .IP USER
219 The name of the real user owning the task being monitored.
220 .IP PID
221 The identification number of the task being monitored.
222 .IP StkSize
223 The amount of memory in kibibytes reserved for the task as stack,
224 but not necessarily used.
225 .IP StkRef
226 The amount of memory in kibibytes used as stack, referenced by the task.
227 .IP Command
228 The command name of the task.
229 .RE
230 .TP
231 .B \-T { TASK | CHILD | ALL }
232 This option specifies what has to be monitored by the
233 .BR "pidstat " "command. The " "TASK"
234 keyword indicates that statistics are to be reported for individual tasks
235 (this is the default option) whereas the
236 .B CHILD
237 keyword indicates that statistics are to be globally reported for the
238 selected tasks and all their children. The
239 .B ALL
240 keyword indicates that statistics are to be reported for
241 individual tasks and globally for the selected
242 tasks and their children.
243
244 Note: Global statistics for tasks and all their children are not available
245 for all options of
246 .B pidstat.
247 Also these statistics are not necessarily relevant to current time interval:
248 The statistics of a child process are collected only when it finishes or
249 it is killed.
250 .TP
251 .B \-t
252 Also display statistics for threads associated with selected tasks.
253
254 This option adds the following values to the reports:
255 .RS
256 .IP TGID
257 The identification number of the thread group leader.
258 .IP TID
259 The identification number of the thread being monitored.
260 .RE
261 .TP
262 .BI "\-U [ " "username " "]"
263 Display the real user name of the tasks being monitored instead of the UID.
264 .RI "If " "username"
265 is specified, then only tasks belonging to the specified user are displayed.
266 .TP
267 .B \-u
268 Report CPU utilization.
269
270 When reporting statistics for individual tasks,
271 the following values may be displayed:
272 .RS
273 .IP UID
274 The real user identification number of the task being monitored.
275 .IP USER
276 The name of the real user owning the task being monitored.
277 .IP PID
278 The identification number of the task being monitored.
279 .IP %usr
280 Percentage of CPU used by the task while executing at the user level
281 (application), with or without nice priority. Note that this field
282 does NOT include time spent running a virtual processor.
283 .IP %system
284 Percentage of CPU used by the task while executing at the system level (kernel).
285 .IP %guest
286 Percentage of CPU spent by the task in virtual machine (running a virtual processor).
287 .IP %wait
288 Percentage of CPU spent by the task while waiting to run.
289 .IP %CPU
290 Total percentage of CPU time used by the task. In an SMP environment,
291 the task's CPU usage will be divided by the total number of CPU's if option
292 .B \-I
293 has been entered on the command line.
294 .IP CPU
295 Processor number to which the task is attached.
296 .IP Command
297 The command name of the task.
298 .RE
299 .IP
300 When reporting global statistics for tasks and all their children,
301 the following values may be displayed:
302 .RS
303 .IP UID
304 The real user identification number of the task which is being monitored
305 together with its children.
306 .IP USER
307 The name of the real user owning the task which is being monitored
308 together with its children.
309 .IP PID
310 The identification number of the task which is being monitored
311 together with its children.
312 .IP usr\-ms
313 Total number of milliseconds spent
314 by the task and all its children while executing at the
315 user level (application), with or without nice priority, and
316 collected during the interval of time. Note that this field does
317 NOT include time spent running a virtual processor.
318 .IP system\-ms
319 Total number of milliseconds spent
320 by the task and all its children while executing at the
321 system level (kernel), and collected during the interval of time.
322 .IP guest\-ms
323 Total number of milliseconds spent
324 by the task and all its children in virtual machine (running a virtual processor).
325 .IP Command
326 The command name of the task which is being monitored
327 together with its children.
328 .RE
329 .TP
330 .B \-V
331 Print version number then exit.
332 .TP
333 .B \-v
334 Report values of some kernel tables. The following values may be displayed:
335 .RS
336 .IP UID
337 The real user identification number of the task being monitored.
338 .IP USER
339 The name of the real user owning the task being monitored.
340 .IP PID
341 The identification number of the task being monitored.
342 .IP threads
343 Number of threads associated with current task.
344 .IP fd\-nr
345 Number of file descriptors associated with current task.
346 .IP Command
347 The command name of the task.
348 .RE
349 .TP
350 .B \-w
351 Report task switching activity (kernels 2.6.23 and later only).
352 The following values may be displayed:
353 .RS
354 .IP UID
355 The real user identification number of the task being monitored.
356 .IP USER
357 The name of the real user owning the task being monitored.
358 .IP PID
359 The identification number of the task being monitored.
360 .IP cswch/s
361 Total number of voluntary context switches the task made per second.
362 A voluntary context switch occurs when a task blocks because it
363 requires a resource that is unavailable.
364 .IP nvcswch/s
365 Total number of non voluntary context switches the task made per second.
366 An involuntary context switch takes place when a task executes
367 for the duration of its time slice and then is forced to relinquish the
368 processor.
369 .IP Command
370 The command name of the task.
371 .RE
372
373 .SH ENVIRONMENT
374 The
375 .B pidstat
376 command takes into account the following environment variables:
377 .TP
378 .B S_COLORS
379 By default statistics are displayed in color when the output is connected to a terminal.
380 Use this variable to change the settings. Possible values for this variable are
381 .IR "never" ", " "always " "or " "auto"
382 (the latter is equivalent to the default settings).
383 .br
384 Please note that the color (being red, yellow, or some other color) used to display a value
385 is not indicative of any kind of issue simply because of the color. It only indicates different
386 ranges of values.
387 .TP
388 .B S_COLORS_SGR
389 Specify the colors and other attributes used to display statistics on the terminal.
390 Its value is a colon-separated list of capabilities that defaults to
391 .BR "I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22" "."
392 Supported capabilities are:
393 .RS
394 .TP
395 .B I=
396 SGR (Select Graphic Rendition) substring for item values like PID, UID or CPU number.
397 .TP
398 .B N=
399 SGR substring for non-zero statistics values and for tasks names.
400 .TP
401 .BR "W=" " (or " "M=" ")"
402 SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the
403 metric's meaning).
404 .TP
405 .BR "X=" " (or " "H=" ")"
406 SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the
407 metric's meaning).
408 .TP
409 .B Z=
410 SGR substring for zero values and for threads names.
411 .RE
412 .TP
413 .B S_TIME_FORMAT
414 If this variable exists and its value is
415 .BR ISO
416 then the current locale will be ignored when printing the date in the report header. The
417 .B pidstat
418 command will use the ISO 8601 format (YYYY-MM-DD) instead.
419 The timestamp will also be compliant with ISO 8601 format.
420
421 .SH EXAMPLES
422 .TP
423 .B pidstat 2 5
424 Display five reports of CPU statistics for every active task in the system
425 at two second intervals.
426 .TP
427 .B pidstat \-r \-p 1643 2 5
428 Display five reports of page faults and memory statistics for
429 PID 1643 at two second intervals.
430 .TP
431 .B pidstat \-C """fox|bird"" \-r \-p ALL
432 Display global page faults and memory statistics for all the
433 processes whose command name includes the string "fox" or "bird".
434 .TP
435 .B pidstat \-T CHILD \-r 2 5
436 Display five reports of page faults statistics at two second intervals
437 for the child processes of all tasks in the system. Only child processes
438 with non-zero statistics values are displayed.
439
440 .SH BUGS
441 .IR "/proc " "filesystem must be mounted for the"
442 .BR "pidstat " "command to work."
443 .PP
444 .RB "Although " "pidstat"
445 displays units corresponding to kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)...
446 A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes.
447
448 .SH FILES
449 .IR "/proc " "contains various files with system statistics."
450
451 .SH AUTHOR
452 Sebastien Godard (sysstat <at> orange.fr)
453
454 .SH SEE ALSO
455 .BR "sar" "(1), " "top" "(1), " "ps" "(1), " "mpstat" "(1), " "iostat" "(1), " "vmstat" "(8)"
456 .PP
457 .I https://github.com/sysstat/sysstat
458 .br
459 .I https://sysstat.github.io/