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