1PIDSTAT(1) Linux User's Manual PIDSTAT(1)
2
6 pidstat - Report statistics for Linux tasks.
7
10 pidstat [ -d ] [ -H ] [ -h ] [ -I ] [ -l ] [ -R ] [ -r ] [ -s ] [ -t ]
11 [ -U [ username ] ] [ -u ] [ -V ] [ -v ] [ -w ] [ -C comm ] [ -G
12 process_name ] [ --dec={ 0 | 1 | 2 } ] [ --human ] [ -p { pid[,...] |
13 SELF | ALL } ] [ -T { TASK | CHILD | ALL } ] [ interval [ count ] ] [
14 -e program args ]
15
18 The pidstat command is used for monitoring individual tasks currently
19 being managed by the Linux kernel. It writes to standard output activ‐
20 ities for every task selected with option -p or for every task managed
21 by the Linux kernel if option -p ALL has been used. Not selecting any
22 tasks is equivalent to specifying -p ALL but only active tasks (tasks
23 with non-zero statistics values) will appear in the report.
24 The pidstat command can also be used for monitoring the child processes
26 of selected tasks. Read about option -T below.
27 The interval parameter specifies the amount of time in seconds between
29 each report. A value of 0 (or no parameters at all) indicates that
30 tasks statistics are to be reported for the time since system startup
31 (boot). The count parameter can be specified in conjunction with the
32 interval parameter if this one is not set to zero. The value of count
33 determines the number of reports generated at interval seconds apart.
34 If the interval parameter is specified without the count parameter, the
35 pidstat command generates reports continuously.
36 You can select information about specific task activities using flags.
38 Not specifying any flags selects only CPU activity.
39
42 -C comm
43 Display only tasks whose command name includes the string comm.
44 This string can be a regular expression.
45 -d Report I/O statistics (kernels 2.6.20 and later only). The fol‐
47 lowing values may be displayed:
48 UID The real user identification number of the task being
50 monitored.
51 USER The name of the real user owning the task being moni‐
53 tored.
54 PID The identification number of the task being monitored.
56 kB_rd/s
58 Number of kilobytes the task has caused to be read from
59 disk per second.
60 kB_wr/s
62 Number of kilobytes the task has caused, or shall cause
63 to be written to disk per second.
64 kB_ccwr/s
66 Number of kilobytes whose writing to disk has been can‐
67 celled by the task. This may occur when the task trun‐
68 cates some dirty pagecache. In this case, some IO which
69 another task has been accounted for will not be happen‐
70 ing.
71 iodelay
73 Block I/O delay of the task being monitored, measured in
74 clock ticks. This metric includes the delays spent wait‐
75 ing for sync block I/O completion and for swapin block
76 I/O completion.
77 Command
79 The command name of the task.
80 --dec={ 0 | 1 | 2 }
82 Specify the number of decimal places to use (0 to 2, default
83 value is 2).
84 -e program args
86 Execute program with given arguments args and monitor it with
87 pidstat. pidstat stops when program terminates.
88 -G process_name
90 Display only processes whose command name includes the string
91 process_name. This string can be a regular expression. If op‐
92 tion -t is used together with option -G then the threads belong‐
93 ing to that process are also displayed (even if their command
94 name doesn't include the string process_name).
95 -H Display timestamp in seconds since the epoch.
97 -h Display all activities horizontally on a single line, with no
99 average statistics at the end of the report. This is intended to
100 make it easier to be parsed by other programs.
101 --human
103 Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.)
104 The units displayed with this option supersede any other default
105 units (e.g. kilobytes, sectors...) associated with the metrics.
106 -I In an SMP environment, indicate that tasks CPU usage (as dis‐
108 played by option -u) should be divided by the total number of
109 processors.
110 -l Display the process command name and all its arguments.
112 -p { pid[,...] | SELF | ALL }
114 Select tasks (processes) for which statistics are to be re‐
115 ported. pid is the process identification number. The SELF key‐
116 word indicates that statistics are to be reported for the pid‐
117 stat process itself, whereas the ALL keyword indicates that sta‐
118 tistics are to be reported for all the tasks managed by the sys‐
119 tem.
120 -R Report realtime priority and scheduling policy information. The
122 following values may be displayed:
123 UID The real user identification number of the task being
125 monitored.
126 USER The name of the real user owning the task being moni‐
128 tored.
129 PID The identification number of the task being monitored.
131 prio The realtime priority of the task being monitored.
133 policy The scheduling policy of the task being monitored.
135 Command
137 The command name of the task.
138 -r Report page faults and memory utilization.
140 When reporting statistics for individual tasks, the following
142 values may be displayed:
143 UID The real user identification number of the task being
145 monitored.
146 USER The name of the real user owning the task being moni‐
148 tored.
149 PID The identification number of the task being monitored.
151 minflt/s
153 Total number of minor faults the task has made per sec‐
154 ond, those which have not required loading a memory page
155 from disk.
156 majflt/s
158 Total number of major faults the task has made per sec‐
159 ond, those which have required loading a memory page from
160 disk.
161 VSZ Virtual Size: The virtual memory usage of entire task in
163 kilobytes.
164 RSS Resident Set Size: The non-swapped physical memory used
166 by the task in kilobytes.
167 %MEM The tasks's currently used share of available physical
169 memory.
170 Command
172 The command name of the task.
173 When reporting global statistics for tasks and all their chil‐
175 dren, the following values may be displayed:
176 UID The real user identification number of the task which is
178 being monitored together with its children.
179 USER The name of the real user owning the task which is being
181 monitored together with its children.
182 PID The identification number of the task which is being mon‐
184 itored together with its children.
185 minflt-nr
187 Total number of minor faults made by the task and all its
188 children, and collected during the interval of time.
189 majflt-nr
191 Total number of major faults made by the task and all its
192 children, and collected during the interval of time.
193 Command
195 The command name of the task which is being monitored to‐
196 gether with its children.
197 -s Report stack utilization. The following values may be dis‐
199 played:
200 UID The real user identification number of the task being
202 monitored.
203 USER The name of the real user owning the task being moni‐
205 tored.
206 PID The identification number of the task being monitored.
208 StkSize
210 The amount of memory in kilobytes reserved for the task
211 as stack, but not necessarily used.
212 StkRef The amount of memory in kilobytes used as stack, refer‐
214 enced by the task.
215 Command
217 The command name of the task.
218 -T { TASK | CHILD | ALL }
220 This option specifies what has to be monitored by the pidstat
221 command. The TASK keyword indicates that statistics are to be
222 reported for individual tasks (this is the default option)
223 whereas the CHILD keyword indicates that statistics are to be
224 globally reported for the selected tasks and all their children.
225 The ALL keyword indicates that statistics are to be reported for
226 individual tasks and globally for the selected tasks and their
227 children.
228 Note: Global statistics for tasks and all their children are not
230 available for all options of pidstat. Also these statistics are
231 not necessarily relevant to current time interval: The statis‐
232 tics of a child process are collected only when it finishes or
233 it is killed.
234 -t Also display statistics for threads associated with selected
236 tasks.
237 This option adds the following values to the reports:
239 TGID The identification number of the thread group leader.
241 TID The identification number of the thread being monitored.
243 -U [ username ]
245 Display the real user name of the tasks being monitored instead
246 of the UID. If username is specified, then only tasks belonging
247 to the specified user are displayed.
248 -u Report CPU utilization.
250 When reporting statistics for individual tasks, the following
252 values may be displayed:
253 UID The real user identification number of the task being
255 monitored.
256 USER The name of the real user owning the task being moni‐
258 tored.
259 PID The identification number of the task being monitored.
261 %usr Percentage of CPU used by the task while executing at the
263 user level (application), with or without nice priority.
264 Note that this field does NOT include time spent running
265 a virtual processor.
266 %system
268 Percentage of CPU used by the task while executing at the
269 system level (kernel).
270 %guest Percentage of CPU spent by the task in virtual machine
272 (running a virtual processor).
273 %wait Percentage of CPU spent by the task while waiting to run.
275 %CPU Total percentage of CPU time used by the task. In an SMP
277 environment, the task's CPU usage will be divided by the
278 total number of CPU's if option -I has been entered on
279 the command line.
280 CPU Processor number to which the task is attached.
282 Command
284 The command name of the task.
285 When reporting global statistics for tasks and all their chil‐
287 dren, the following values may be displayed:
288 UID The real user identification number of the task which is
290 being monitored together with its children.
291 USER The name of the real user owning the task which is being
293 monitored together with its children.
294 PID The identification number of the task which is being mon‐
296 itored together with its children.
297 usr-ms Total number of milliseconds spent by the task and all
299 its children while executing at the user level (applica‐
300 tion), with or without nice priority, and collected dur‐
301 ing the interval of time. Note that this field does NOT
302 include time spent running a virtual processor.
303 system-ms
305 Total number of milliseconds spent by the task and all
306 its children while executing at the system level (ker‐
307 nel), and collected during the interval of time.
308 guest-ms
310 Total number of milliseconds spent by the task and all
311 its children in virtual machine (running a virtual pro‐
312 cessor).
313 Command
315 The command name of the task which is being monitored to‐
316 gether with its children.
317 -V Print version number then exit.
319 -v Report values of some kernel tables. The following values may be
321 displayed:
322 UID The real user identification number of the task being
324 monitored.
325 USER The name of the real user owning the task being moni‐
327 tored.
328 PID The identification number of the task being monitored.
330 threads
332 Number of threads associated with current task.
333 fd-nr Number of file descriptors associated with current task.
335 Command
337 The command name of the task.
338 -w Report task switching activity (kernels 2.6.23 and later only).
340 The following values may be displayed:
341 UID The real user identification number of the task being
343 monitored.
344 USER The name of the real user owning the task being moni‐
346 tored.
347 PID The identification number of the task being monitored.
349 cswch/s
351 Total number of voluntary context switches the task made
352 per second. A voluntary context switch occurs when a
353 task blocks because it requires a resource that is un‐
354 available.
355 nvcswch/s
357 Total number of non voluntary context switches the task
358 made per second. An involuntary context switch takes
359 place when a task executes for the duration of its time
360 slice and then is forced to relinquish the processor.
361 Command
363 The command name of the task.
364
367 The pidstat command takes into account the following environment vari‐
368 ables:
369 S_COLORS
371 By default statistics are displayed in color when the output is
372 connected to a terminal. Use this variable to change the set‐
373 tings. Possible values for this variable are never, always or
374 auto (the latter is equivalent to the default settings).
375 Please note that the color (being red, yellow, or some other
376 color) used to display a value is not indicative of any kind of
377 issue simply because of the color. It only indicates different
378 ranges of values.
379 S_COLORS_SGR
381 Specify the colors and other attributes used to display statis‐
382 tics on the terminal. Its value is a colon-separated list of
383 capabilities that defaults to
384 I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22. Supported capabilities
385 are:
386 I= SGR (Select Graphic Rendition) substring for item values
388 like PID, UID or CPU number.
389 N= SGR substring for non-zero statistics values and for
391 tasks names.
392 W= (or M=)
394 SGR substring for percentage values in the range from 75%
395 to 90% (or in the range 10% to 25% depending on the met‐
396 ric's meaning).
397 X= (or H=)
399 SGR substring for percentage values greater than or equal
400 to 90% (or lower than or equal to 10% depending on the
401 metric's meaning).
402 Z= SGR substring for zero values and for threads names.
404 S_TIME_FORMAT
406 If this variable exists and its value is ISO then the current
407 locale will be ignored when printing the date in the report
408 header. The pidstat command will use the ISO 8601 format (YYYY-
409 MM-DD) instead. The timestamp will also be compliant with ISO
410 8601 format.
411
414 pidstat 2 5
415 Display five reports of CPU statistics for every active task in
416 the system at two second intervals.
417 pidstat -r -p 1643 2 5
419 Display five reports of page faults and memory statistics for
420 PID 1643 at two second intervals.
421 pidstat -C "fox|bird" -r -p ALL
423 Display global page faults and memory statistics for all the
424 processes whose command name includes the string "fox" or
425 "bird".
426 pidstat -T CHILD -r 2 5
428 Display five reports of page faults statistics at two second in‐
429 tervals for the child processes of all tasks in the system. Only
430 child processes with non-zero statistics values are displayed.
431
434 /proc filesystem must be mounted for the pidstat command to work.
435 Although pidstat speaks of kilobytes (kB), megabytes (MB)..., it actu‐
437 ally uses kibibytes (kiB), mebibytes (MiB)... A kibibyte is equal to
438 1024 bytes, and a mebibyte is equal to 1024 kibibytes.
439
442 /proc contains various files with system statistics.
443
446 Sebastien Godard (sysstat <at> orange.fr)
447
450 sar(1), top(1), ps(1), mpstat(1), iostat(1), vmstat(8)
451 https://github.com/sysstat/sysstat
453Linux MAY 2023 PIDSTAT(1)