1PIDSTAT(1)                    Linux User's Manual                   PIDSTAT(1)
2
3
4

NAME

6       pidstat - Report statistics for Linux tasks.
7

SYNOPSIS

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

DESCRIPTION

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
22       The pidstat command can also be used for monitoring the child processes
23       of selected tasks.  Read about option -T below.
24
25       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
34       You  can select information about specific task activities using flags.
35       Not specifying any flags selects only CPU activity.
36
37

OPTIONS

39       -C comm
40              Display only tasks whose command name includes the string  comm.
41              This string can be a regular expression.
42
43       -d     Report I/O statistics (kernels 2.6.20 and later only).  The fol‐
44              lowing values may be displayed:
45
46              UID
47                     The real user identification number  of  the  task  being
48                     monitored.
49
50              USER
51                     The  name  of  the  real user owning the task being moni‐
52                     tored.
53
54              PID
55                     The identification number of the task being monitored.
56
57              kB_rd/s
58                     Number of kilobytes the task has caused to be  read  from
59                     disk per second.
60
61              kB_wr/s
62                     Number  of  kilobytes the task has caused, or shall cause
63                     to be written to disk per second.
64
65              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
72              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
78              Command
79                     The command name of the task.
80
81       -e program args
82              Execute  program  with  given arguments args and monitor it with
83              pidstat.  pidstat stops when program terminates.
84
85       -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
92       -H     Display timestamp in seconds since the epoch.
93
94       -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
98       --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
103       -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
107       -l     Display the process command name and all its arguments.
108
109       -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
117       -R     Report realtime priority and scheduling policy information.  The
118              following values may be displayed:
119
120              UID
121                     The real user identification number  of  the  task  being
122                     monitored.
123
124              USER
125                     The  name  of  the  real user owning the task being moni‐
126                     tored.
127
128              PID
129                     The identification number of the task being monitored.
130
131              prio
132                     The realtime priority of the task being monitored.
133
134              policy
135                     The scheduling policy of the task being monitored.
136
137              Command
138                     The command name of the task.
139
140       -r     Report page faults and memory utilization.
141
142              When reporting statistics for individual  tasks,  the  following
143              values may be displayed:
144
145              UID
146                     The  real  user  identification  number of the task being
147                     monitored.
148
149              USER
150                     The name of the real user owning  the  task  being  moni‐
151                     tored.
152
153              PID
154                     The identification number of the task being monitored.
155
156              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
161              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
166              VSZ
167                     Virtual  Size: The virtual memory usage of entire task in
168                     kilobytes.
169
170              RSS
171                     Resident Set Size: The non-swapped physical  memory  used
172                     by the task in kilobytes.
173
174              %MEM
175                     The  tasks's  currently  used share of available physical
176                     memory.
177
178              Command
179                     The command name of the task.
180
181              When reporting global statistics for tasks and all  their  chil‐
182              dren, the following values may be displayed:
183
184              UID
185                     The  real user identification number of the task which is
186                     being monitored together with its children.
187
188              USER
189                     The name of the real user owning the task which is  being
190                     monitored together with its children.
191
192              PID
193                     The identification number of the task which is being mon‐
194                     itored together with its children.
195
196              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
200              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
204              Command
205                     The command name of the task  which  is  being  monitored
206                     together with its children.
207
208       -s     Report  stack  utilization.   The  following  values may be dis‐
209              played:
210
211              UID
212                     The real user identification number  of  the  task  being
213                     monitored.
214
215              USER
216                     The  name  of  the  real user owning the task being moni‐
217                     tored.
218
219              PID
220                     The identification number of the task being monitored.
221
222              StkSize
223                     The amount of memory in kilobytes reserved for  the  task
224                     as stack, but not necessarily used.
225
226              StkRef
227                     The  amount  of memory in kilobytes used as stack, refer‐
228                     enced by the task.
229
230              Command
231                     The command name of the task.
232
233       -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
243              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
249       -t     Also  display  statistics  for  threads associated with selected
250              tasks.
251
252              This option adds the following values to the reports:
253
254              TGID
255                     The identification number of the thread group leader.
256
257              TID
258                     The identification number of the thread being monitored.
259
260       -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
265       -u     Report CPU utilization.
266
267              When reporting statistics for individual  tasks,  the  following
268              values may be displayed:
269
270              UID
271                     The  real  user  identification  number of the task being
272                     monitored.
273
274              USER
275                     The name of the real user owning  the  task  being  moni‐
276                     tored.
277
278              PID
279                     The identification number of the task being monitored.
280
281              %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
287              %system
288                     Percentage of CPU used by the task while executing at the
289                     system level (kernel).
290
291              %guest
292                     Percentage  of  CPU  spent by the task in virtual machine
293                     (running a virtual processor).
294
295              %wait
296                     Percentage of CPU spent by the task while waiting to run.
297
298              %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
304              CPU
305                     Processor number to which the task is attached.
306
307              Command
308                     The command name of the task.
309
310              When  reporting  global statistics for tasks and all their chil‐
311              dren, the following values may be displayed:
312
313              UID
314                     The real user identification number of the task which  is
315                     being monitored together with its children.
316
317              USER
318                     The  name of the real user owning the task which is being
319                     monitored together with its children.
320
321              PID
322                     The identification number of the task which is being mon‐
323                     itored together with its children.
324
325              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
332              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
337              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
342              Command
343                     The  command  name  of  the task which is being monitored
344                     together with its children.
345
346       -V     Print version number then exit.
347
348       -v     Report values of some kernel tables. The following values may be
349              displayed:
350
351              UID
352                     The  real  user  identification  number of the task being
353                     monitored.
354
355              USER
356                     The name of the real user owning  the  task  being  moni‐
357                     tored.
358
359              PID
360                     The identification number of the task being monitored.
361
362              threads
363                     Number of threads associated with current task.
364
365              fd-nr
366                     Number of file descriptors associated with current task.
367
368              Command
369                     The command name of the task.
370
371       -w     Report  task switching activity (kernels 2.6.23 and later only).
372              The following values may be displayed:
373
374              UID
375                     The real user identification number  of  the  task  being
376                     monitored.
377
378              USER
379                     The  name  of  the  real user owning the task being moni‐
380                     tored.
381
382              PID
383                     The identification number of the task being monitored.
384
385              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
391              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
397              Command
398                     The command name of the task.
399

ENVIRONMENT

401       The pidstat command takes into account the following environment  vari‐
402       ables:
403
404
405       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
410              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
415
416       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
423
424              H=     SGR (Select Graphic Rendition) substring  for  percentage
425                     values greater than or equal to 75%.
426
427
428              I=     SGR  substring  for item values like PID, UID or CPU num‐
429                     ber.
430
431
432              M=     SGR substring for percentage values in the range from 50%
433                     to 75%.
434
435
436              N=     SGR  substring  for  non-zero  statistics  values and for
437                     tasks names.
438
439
440              Z=     SGR substring for zero values and for threads names.
441
442
443       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
450

EXAMPLES

452       pidstat 2 5
453              Display five reports of CPU statistics for every active task  in
454              the system at two second intervals.
455
456       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
460       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
465       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

BUGS

472       /proc filesystem must be mounted for the pidstat command to work.
473
474

FILES

476       /proc contains various files with system statistics.
477
478

AUTHOR

480       Sebastien Godard (sysstat <at> orange.fr)
481

SEE ALSO

483       sar(1), top(1), ps(1), mpstat(1), iostat(1), vmstat(8)
484
485       http://pagesperso-orange.fr/sebastien.godard/
486
487
488
489Linux                            JANUARY 2018                       PIDSTAT(1)
Impressum