1PIDSTAT(1) Linux User's Manual PIDSTAT(1)
2
6 pidstat - Report statistics for Linux tasks.
7
9 pidstat [ -d ] [ -H ] [ -h ] [ -I ] [ -l ] [ -R ] [ -r ] [ -s ] [ -t ]
10 [ -U [ username ] ] [ -u ] [ -V ] [ -v ] [ -w ] [ -C comm ] [ -G
11 process_name ] [ --human ] [ -p { pid [,...] | SELF | ALL } ] [ -T {
12 TASK | CHILD | ALL } ] [ interval [ count ] ] [ -e program args ]
13
15 The pidstat command is used for monitoring individual tasks currently
16 being managed by the Linux kernel. It writes to standard output activ‐
17 ities for every task selected with option -p or for every task managed
18 by the Linux kernel if option -p ALL has been used. Not selecting any
19 tasks is equivalent to specifying -p ALL but only active tasks (tasks
20 with non-zero statistics values) will appear in the report.
21 The pidstat command can also be used for monitoring the child processes
23 of selected tasks. Read about option -T below.
24 The interval parameter specifies the amount of time in seconds between
26 each report. A value of 0 (or no parameters at all) indicates that
27 tasks statistics are to be reported for the time since system startup
28 (boot). The count parameter can be specified in conjunction with the
29 interval parameter if this one is not set to zero. The value of count
30 determines the number of reports generated at interval seconds apart.
31 If the interval parameter is specified without the count parameter, the
32 pidstat command generates reports continuously.
33 You can select information about specific task activities using flags.
35 Not specifying any flags selects only CPU activity.
36
39 -C comm
40 Display only tasks whose command name includes the string comm.
41 This string can be a regular expression.
42 -d Report I/O statistics (kernels 2.6.20 and later only). The fol‐
44 lowing values may be displayed:
45 UID
47 The real user identification number of the task being
48 monitored.
49 USER
51 The name of the real user owning the task being moni‐
52 tored.
53 PID
55 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 -e program args
82 Execute program with given arguments args and monitor it with
83 pidstat. pidstat stops when program terminates.
84 -G process_name
86 Display only processes whose command name includes the string
87 process_name. This string can be a regular expression. If
88 option -t is used together with option -G then the threads
89 belonging to that process are also displayed (even if their com‐
90 mand name doesn't include the string process_name).
91 -H Display timestamp in seconds since the epoch.
93 -h Display all activities horizontally on a single line, with no
95 average statistics at the end of the report. This is intended to
96 make it easier to be parsed by other programs.
97 --human
99 Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.)
100 The units displayed with this option supersede any other default
101 units (e.g. kilobytes, sectors...) associated with the metrics.
102 -I In an SMP environment, indicate that tasks CPU usage (as dis‐
104 played by option -u ) should be divided by the total number of
105 processors.
106 -l Display the process command name and all its arguments.
108 -p { pid [,...] | SELF | ALL }
110 Select tasks (processes) for which statistics are to be
111 reported. pid is the process identification number. The SELF
112 keyword indicates that statistics are to be reported for the
113 pidstat process itself, whereas the ALL keyword indicates that
114 statistics are to be reported for all the tasks managed by the
115 system.
116 -R Report realtime priority and scheduling policy information. The
118 following values may be displayed:
119 UID
121 The real user identification number of the task being
122 monitored.
123 USER
125 The name of the real user owning the task being moni‐
126 tored.
127 PID
129 The identification number of the task being monitored.
130 prio
132 The realtime priority of the task being monitored.
133 policy
135 The scheduling policy of the task being monitored.
136 Command
138 The command name of the task.
139 -r Report page faults and memory utilization.
141 When reporting statistics for individual tasks, the following
143 values may be displayed:
144 UID
146 The real user identification number of the task being
147 monitored.
148 USER
150 The name of the real user owning the task being moni‐
151 tored.
152 PID
154 The identification number of the task being monitored.
155 minflt/s
157 Total number of minor faults the task has made per sec‐
158 ond, those which have not required loading a memory page
159 from disk.
160 majflt/s
162 Total number of major faults the task has made per sec‐
163 ond, those which have required loading a memory page from
164 disk.
165 VSZ
167 Virtual Size: The virtual memory usage of entire task in
168 kilobytes.
169 RSS
171 Resident Set Size: The non-swapped physical memory used
172 by the task in kilobytes.
173 %MEM
175 The tasks's currently used share of available physical
176 memory.
177 Command
179 The command name of the task.
180 When reporting global statistics for tasks and all their chil‐
182 dren, the following values may be displayed:
183 UID
185 The real user identification number of the task which is
186 being monitored together with its children.
187 USER
189 The name of the real user owning the task which is being
190 monitored together with its children.
191 PID
193 The identification number of the task which is being mon‐
194 itored together with its children.
195 minflt-nr
197 Total number of minor faults made by the task and all its
198 children, and collected during the interval of time.
199 majflt-nr
201 Total number of major faults made by the task and all its
202 children, and collected during the interval of time.
203 Command
205 The command name of the task which is being monitored
206 together with its children.
207 -s Report stack utilization. The following values may be dis‐
209 played:
210 UID
212 The real user identification number of the task being
213 monitored.
214 USER
216 The name of the real user owning the task being moni‐
217 tored.
218 PID
220 The identification number of the task being monitored.
221 StkSize
223 The amount of memory in kilobytes reserved for the task
224 as stack, but not necessarily used.
225 StkRef
227 The amount of memory in kilobytes used as stack, refer‐
228 enced by the task.
229 Command
231 The command name of the task.
232 -T { TASK | CHILD | ALL }
234 This option specifies what has to be monitored by the pidstat
235 command. The TASK keyword indicates that statistics are to be
236 reported for individual tasks (this is the default option)
237 whereas the CHILD keyword indicates that statistics are to be
238 globally reported for the selected tasks and all their children.
239 The ALL keyword indicates that statistics are to be reported for
240 individual tasks and globally for the selected tasks and their
241 children.
242 Note: Global statistics for tasks and all their children are not
244 available for all options of pidstat. Also these statistics are
245 not necessarily relevant to current time interval: The statis‐
246 tics of a child process are collected only when it finishes or
247 it is killed.
248 -t Also display statistics for threads associated with selected
250 tasks.
251 This option adds the following values to the reports:
253 TGID
255 The identification number of the thread group leader.
256 TID
258 The identification number of the thread being monitored.
259 -U [ username ]
261 Display the real user name of the tasks being monitored instead
262 of the UID. If username is specified, then only tasks belonging
263 to the specified user are displayed.
264 -u Report CPU utilization.
266 When reporting statistics for individual tasks, the following
268 values may be displayed:
269 UID
271 The real user identification number of the task being
272 monitored.
273 USER
275 The name of the real user owning the task being moni‐
276 tored.
277 PID
279 The identification number of the task being monitored.
280 %usr
282 Percentage of CPU used by the task while executing at the
283 user level (application), with or without nice priority.
284 Note that this field does NOT include time spent running
285 a virtual processor.
286 %system
288 Percentage of CPU used by the task while executing at the
289 system level (kernel).
290 %guest
292 Percentage of CPU spent by the task in virtual machine
293 (running a virtual processor).
294 %wait
296 Percentage of CPU spent by the task while waiting to run.
297 %CPU
299 Total percentage of CPU time used by the task. In an SMP
300 environment, the task's CPU usage will be divided by the
301 total number of CPU's if option -I has been entered on
302 the command line.
303 CPU
305 Processor number to which the task is attached.
306 Command
308 The command name of the task.
309 When reporting global statistics for tasks and all their chil‐
311 dren, the following values may be displayed:
312 UID
314 The real user identification number of the task which is
315 being monitored together with its children.
316 USER
318 The name of the real user owning the task which is being
319 monitored together with its children.
320 PID
322 The identification number of the task which is being mon‐
323 itored together with its children.
324 usr-ms
326 Total number of milliseconds spent by the task and all
327 its children while executing at the user level (applica‐
328 tion), with or without nice priority, and collected dur‐
329 ing the interval of time. Note that this field does NOT
330 include time spent running a virtual processor.
331 system-ms
333 Total number of milliseconds spent by the task and all
334 its children while executing at the system level (ker‐
335 nel), and collected during the interval of time.
336 guest-ms
338 Total number of milliseconds spent by the task and all
339 its children in virtual machine (running a virtual pro‐
340 cessor).
341 Command
343 The command name of the task which is being monitored
344 together with its children.
345 -V Print version number then exit.
347 -v Report values of some kernel tables. The following values may be
349 displayed:
350 UID
352 The real user identification number of the task being
353 monitored.
354 USER
356 The name of the real user owning the task being moni‐
357 tored.
358 PID
360 The identification number of the task being monitored.
361 threads
363 Number of threads associated with current task.
364 fd-nr
366 Number of file descriptors associated with current task.
367 Command
369 The command name of the task.
370 -w Report task switching activity (kernels 2.6.23 and later only).
372 The following values may be displayed:
373 UID
375 The real user identification number of the task being
376 monitored.
377 USER
379 The name of the real user owning the task being moni‐
380 tored.
381 PID
383 The identification number of the task being monitored.
384 cswch/s
386 Total number of voluntary context switches the task made
387 per second. A voluntary context switch occurs when a
388 task blocks because it requires a resource that is
389 unavailable.
390 nvcswch/s
392 Total number of non voluntary context switches the task
393 made per second. A involuntary context switch takes
394 place when a task executes for the duration of its time
395 slice and then is forced to relinquish the processor.
396 Command
398 The command name of the task.
399
401 The pidstat command takes into account the following environment vari‐
402 ables:
403 S_COLORS
406 When this variable is set, display statistics in color on the
407 terminal. Possible values for this variable are never, always
408 or auto (the latter is the default).
409 Please note that the color (being red, yellow, or some other
411 color) used to display a value is not indicative of any kind of
412 issue simply because of the color. It only indicates different
413 ranges of values.
414 S_COLORS_SGR
417 Specify the colors and other attributes used to display statis‐
418 tics on the terminal. Its value is a colon-separated list of
419 capabilities that defaults to
420 H=31;1:I=32;22:M=35;1:N=34;1:Z=34;22. Supported capabilities
421 are:
422 H= SGR (Select Graphic Rendition) substring for percentage
425 values greater than or equal to 75%.
426 I= SGR substring for item values like PID, UID or CPU num‐
429 ber.
430 M= SGR substring for percentage values in the range from 50%
433 to 75%.
434 N= SGR substring for non-zero statistics values and for
437 tasks names.
438 Z= SGR substring for zero values and for threads names.
441 S_TIME_FORMAT
444 If this variable exists and its value is ISO then the current
445 locale will be ignored when printing the date in the report
446 header. The pidstat command will use the ISO 8601 format (YYYY-
447 MM-DD) instead. The timestamp will also be compliant with ISO
448 8601 format.
449
452 pidstat 2 5
453 Display five reports of CPU statistics for every active task in
454 the system at two second intervals.
455 pidstat -r -p 1643 2 5
457 Display five reports of page faults and memory statistics for
458 PID 1643 at two second intervals.
459 pidstat -C "fox|bird" -r -p ALL
461 Display global page faults and memory statistics for all the
462 processes whose command name includes the string "fox" or
463 "bird".
464 pidstat -T CHILD -r 2 5
466 Display five reports of page faults statistics at two second
467 intervals for the child processes of all tasks in the system.
468 Only child processes with non-zero statistics values are dis‐
469 played.
470
472 /proc filesystem must be mounted for the pidstat command to work.
473
476 /proc contains various files with system statistics.
477
480 Sebastien Godard (sysstat <at> orange.fr)
481
483 sar(1), top(1), ps(1), mpstat(1), iostat(1), vmstat(8)
484 http://pagesperso-orange.fr/sebastien.godard/
486Linux JANUARY 2018 PIDSTAT(1)