diff options
Diffstat (limited to 'upstream/debian-unstable/man1/pidstat.1')
| -rw-r--r-- | upstream/debian-unstable/man1/pidstat.1 | 452 |
1 files changed, 452 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/pidstat.1 b/upstream/debian-unstable/man1/pidstat.1 new file mode 100644 index 00000000..cdcf81d6 --- /dev/null +++ b/upstream/debian-unstable/man1/pidstat.1 @@ -0,0 +1,452 @@ +.\" pidstat manual page - (C) 2007-2020 Sebastien Godard (sysstat <at> orange.fr) +.TH PIDSTAT 1 "AUGUST 2023" Linux "Linux User's Manual" -*- nroff -*- +.SH NAME +pidstat \- Report statistics for Linux tasks. + +.SH SYNOPSIS +.B pidstat [ \-d ] [ \-H ] [ \-h ] [ \-I ] [ \-l ] [ \-R ] [ \-r ] [ \-s ] [ \-t ] [ \-U [ +.IB "username " "] ] [ \-u ] [ \-V ] [ \-v ] [ \-w ] [ \-C " "comm " "] [ \-G " "process_name" +.BI "] [ \-\-dec={ 0 | 1 | 2 } ] [ \-\-human ] [ \-p { " "pid" "[,...]" +.B | SELF | ALL } ] [ \-T { TASK | CHILD | ALL } ] [ +.IB "interval " "[ " "count " "] ] [ \-e " "program" +.IB "args " "]" + +.SH DESCRIPTION +.RB "The " "pidstat" +command is used for monitoring individual tasks currently being managed +by the Linux kernel. +It writes to standard output activities for every task selected with option +.B \-p +or for every task managed by the Linux kernel if option +.B \-p ALL +has been used. Not selecting any tasks is equivalent to specifying +.B \-p ALL +but only active tasks (tasks with non-zero statistics values) +will appear in the report. +.PP +.RB "The " "pidstat" +command can also be used for monitoring the child processes of selected tasks. +Read about option +.BR "\-T " "below." +.PP +.RI "The " "interval" +parameter specifies the amount of time in seconds between each report. +A value of 0 (or no parameters at all) indicates that tasks statistics are +to be reported for the time since system startup (boot). The +.IR "count " "parameter can be specified in conjunction with the" +.IR "interval " "parameter if this one is not set to zero. The value of" +.IR "count " "determines the number of reports generated at" +.IR "interval " "seconds apart. If the " "interval " "parameter is specified without the " "count" +parameter, the +.B pidstat +command generates reports continuously. +.PP +You can select information about specific task activities using flags. +Not specifying any flags selects only CPU activity. + +.SH OPTIONS +.TP +.BI "\-C " "comm" +Display only tasks whose command name includes the string +.IR "comm" ". This string can be a regular expression." +.TP +.B \-d +Report I/O statistics (kernels 2.6.20 and later only). +The following values may be displayed: +.RS +.IP UID +The real user identification number of the task being monitored. +.IP USER +The name of the real user owning the task being monitored. +.IP PID +The identification number of the task being monitored. +.IP kB_rd/s +Number of kilobytes the task has caused to be read from disk per second. +.IP kB_wr/s +Number of kilobytes the task has caused, or shall cause to be +written to disk per second. +.IP kB_ccwr/s +Number of kilobytes whose writing to disk has been cancelled by +the task. This may occur when the task truncates some +dirty pagecache. In this case, some IO which another task has +been accounted for will not be happening. +.IP iodelay +Block I/O delay of the task being monitored, +measured in clock ticks. This metric includes the delays spent +waiting for sync block I/O completion and for swapin block I/O +completion. +.IP Command +The command name of the task. +.RE +.TP +.B \-\-dec={ 0 | 1 | 2 } +Specify the number of decimal places to use (0 to 2, default value is 2). +.TP +.BI "\-e " "program args" +Execute +.I program +with given arguments +.I args +and monitor it with +.BR "pidstat" "." +.BR "pidstat " "stops when" +.IR "program " "terminates." +.TP +.BI "\-G " "process_name" +Display only processes whose command name includes the string +.IR "process_name" "." +This string can be a regular expression. If option +.BR "\-t " "is used together with option " "\-G" +then the threads belonging to that process are also displayed +(even if their command name doesn't include the string +.IR "process_name" ")." +.TP +.B \-H +Display timestamp in seconds since the epoch. +.TP +.B \-h +Display all activities horizontally on a single line, with no +average statistics at the end of the report. This is +intended to make it easier to be parsed by other programs. +.TP +.B \-\-human +Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.) +The units displayed with this option supersede any other default units (e.g. +kilobytes, sectors...) associated with the metrics. +.TP +.B \-I +In an SMP environment, indicate that tasks CPU usage +.RB "(as displayed by option " "\-u" ")" +should be divided by the total number of processors. +.TP +.B \-l +Display the process command name and all its arguments. +.TP +.BI "\-p { " "pid" "[,...] | SELF | ALL }" +Select tasks (processes) for which statistics are to be reported. +.I pid +is the process identification number. The +.B SELF +keyword indicates that statistics are to be reported for the +.BR "pidstat " "process itself, whereas the " "ALL" +keyword indicates that statistics are to be reported for all the +tasks managed by the system. +.TP +.B \-R +Report realtime priority and scheduling policy information. +The following values may be displayed: +.RS +.IP UID +The real user identification number of the task being monitored. +.IP USER +The name of the real user owning the task being monitored. +.IP PID +The identification number of the task being monitored. +.IP prio +The realtime priority of the task being monitored. +.IP policy +The scheduling policy of the task being monitored. +.IP Command +The command name of the task. +.RE +.TP +.B \-r +Report page faults and memory utilization. + +When reporting statistics for individual tasks, +the following values may be displayed: +.RS +.IP UID +The real user identification number of the task being monitored. +.IP USER +The name of the real user owning the task being monitored. +.IP PID +The identification number of the task being monitored. +.IP minflt/s +Total number of minor faults the task has made per second, those +which have not required loading a memory page from disk. +.IP majflt/s +Total number of major faults the task has made per second, those +which have required loading a memory page from disk. +.IP VSZ +Virtual Size: The virtual memory usage of entire task in kilobytes. +.IP RSS +Resident Set Size: The non-swapped physical memory +used by the task in kilobytes. +.IP %MEM +The tasks's currently used share of available physical memory. +.IP Command +The command name of the task. +.RE +.IP +When reporting global statistics for tasks and all their children, +the following values may be displayed: +.RS +.IP UID +The real user identification number of the task which is being monitored +together with its children. +.IP USER +The name of the real user owning the task which is being monitored +together with its children. +.IP PID +The identification number of the task which is being monitored +together with its children. +.IP minflt\-nr +Total number of minor faults made by the task and all its children, +and collected during the interval of time. +.IP majflt\-nr +Total number of major faults made by the task and all its children, +and collected during the interval of time. +.IP Command +The command name of the task which is being monitored +together with its children. +.RE +.TP +.B \-s +Report stack utilization. +The following values may be displayed: +.RS +.IP UID +The real user identification number of the task being monitored. +.IP USER +The name of the real user owning the task being monitored. +.IP PID +The identification number of the task being monitored. +.IP StkSize +The amount of memory in kilobytes reserved for the task as stack, +but not necessarily used. +.IP StkRef +The amount of memory in kilobytes used as stack, referenced by the task. +.IP Command +The command name of the task. +.RE +.TP +.B \-T { TASK | CHILD | ALL } +This option specifies what has to be monitored by the +.BR "pidstat " "command. The " "TASK" +keyword indicates that statistics are to be reported for individual tasks +(this is the default option) whereas the +.B CHILD +keyword indicates that statistics are to be globally reported for the +selected tasks and all their children. The +.B ALL +keyword indicates that statistics are to be reported for +individual tasks and globally for the selected +tasks and their children. + +Note: Global statistics for tasks and all their children are not available +for all options of +.B pidstat. +Also these statistics are not necessarily relevant to current time interval: +The statistics of a child process are collected only when it finishes or +it is killed. +.TP +.B \-t +Also display statistics for threads associated with selected tasks. + +This option adds the following values to the reports: +.RS +.IP TGID +The identification number of the thread group leader. +.IP TID +The identification number of the thread being monitored. +.RE +.TP +.BI "\-U [ " "username " "]" +Display the real user name of the tasks being monitored instead of the UID. +.RI "If " "username" +is specified, then only tasks belonging to the specified user are displayed. +.TP +.B \-u +Report CPU utilization. + +When reporting statistics for individual tasks, +the following values may be displayed: +.RS +.IP UID +The real user identification number of the task being monitored. +.IP USER +The name of the real user owning the task being monitored. +.IP PID +The identification number of the task being monitored. +.IP %usr +Percentage of CPU used by the task while executing at the user level +(application), with or without nice priority. Note that this field +does NOT include time spent running a virtual processor. +.IP %system +Percentage of CPU used by the task while executing at the system level (kernel). +.IP %guest +Percentage of CPU spent by the task in virtual machine (running a virtual processor). +.IP %wait +Percentage of CPU spent by the task while waiting to run. +.IP %CPU +Total percentage of CPU time used by the task. In an SMP environment, +the task's CPU usage will be divided by the total number of CPU's if option +.B \-I +has been entered on the command line. +.IP CPU +Processor number to which the task is attached. +.IP Command +The command name of the task. +.RE +.IP +When reporting global statistics for tasks and all their children, +the following values may be displayed: +.RS +.IP UID +The real user identification number of the task which is being monitored +together with its children. +.IP USER +The name of the real user owning the task which is being monitored +together with its children. +.IP PID +The identification number of the task which is being monitored +together with its children. +.IP usr\-ms +Total number of milliseconds spent +by the task and all its children while executing at the +user level (application), with or without nice priority, and +collected during the interval of time. Note that this field does +NOT include time spent running a virtual processor. +.IP system\-ms +Total number of milliseconds spent +by the task and all its children while executing at the +system level (kernel), and collected during the interval of time. +.IP guest\-ms +Total number of milliseconds spent +by the task and all its children in virtual machine (running a virtual processor). +.IP Command +The command name of the task which is being monitored +together with its children. +.RE +.TP +.B \-V +Print version number then exit. +.TP +.B \-v +Report values of some kernel tables. The following values may be displayed: +.RS +.IP UID +The real user identification number of the task being monitored. +.IP USER +The name of the real user owning the task being monitored. +.IP PID +The identification number of the task being monitored. +.IP threads +Number of threads associated with current task. +.IP fd\-nr +Number of file descriptors associated with current task. +.IP Command +The command name of the task. +.RE +.TP +.B \-w +Report task switching activity (kernels 2.6.23 and later only). +The following values may be displayed: +.RS +.IP UID +The real user identification number of the task being monitored. +.IP USER +The name of the real user owning the task being monitored. +.IP PID +The identification number of the task being monitored. +.IP cswch/s +Total number of voluntary context switches the task made per second. +A voluntary context switch occurs when a task blocks because it +requires a resource that is unavailable. +.IP nvcswch/s +Total number of non voluntary context switches the task made per second. +An involuntary context switch takes place when a task executes +for the duration of its time slice and then is forced to relinquish the +processor. +.IP Command +The command name of the task. +.RE + +.SH ENVIRONMENT +The +.B pidstat +command takes into account the following environment variables: +.TP +.B S_COLORS +By default statistics are displayed in color when the output is connected to a terminal. +Use this variable to change the settings. Possible values for this variable are +.IR "never" ", " "always " "or " "auto" +(the latter is equivalent to the default settings). +.br +Please note that the color (being red, yellow, or some other color) used to display a value +is not indicative of any kind of issue simply because of the color. It only indicates different +ranges of values. +.TP +.B S_COLORS_SGR +Specify the colors and other attributes used to display statistics on the terminal. +Its value is a colon-separated list of capabilities that defaults to +.BR "I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22" "." +Supported capabilities are: +.RS +.TP +.B I= +SGR (Select Graphic Rendition) substring for item values like PID, UID or CPU number. +.TP +.B N= +SGR substring for non-zero statistics values and for tasks names. +.TP +.BR "W=" " (or " "M=" ")" +SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the +metric's meaning). +.TP +.BR "X=" " (or " "H=" ")" +SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the +metric's meaning). +.TP +.B Z= +SGR substring for zero values and for threads names. +.RE +.TP +.B S_TIME_FORMAT +If this variable exists and its value is +.BR ISO +then the current locale will be ignored when printing the date in the report header. The +.B pidstat +command will use the ISO 8601 format (YYYY-MM-DD) instead. +The timestamp will also be compliant with ISO 8601 format. + +.SH EXAMPLES +.TP +.B pidstat 2 5 +Display five reports of CPU statistics for every active task in the system +at two second intervals. +.TP +.B pidstat \-r \-p 1643 2 5 +Display five reports of page faults and memory statistics for +PID 1643 at two second intervals. +.TP +.B pidstat \-C """fox|bird"" \-r \-p ALL +Display global page faults and memory statistics for all the +processes whose command name includes the string "fox" or "bird". +.TP +.B pidstat \-T CHILD \-r 2 5 +Display five reports of page faults statistics at two second intervals +for the child processes of all tasks in the system. Only child processes +with non-zero statistics values are displayed. + +.SH BUGS +.IR "/proc " "filesystem must be mounted for the" +.BR "pidstat " "command to work." +.PP +.RB "Although " "pidstat" +speaks of kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)... +A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes. + +.SH FILES +.IR "/proc " "contains various files with system statistics." + +.SH AUTHOR +Sebastien Godard (sysstat <at> orange.fr) + +.SH SEE ALSO +.BR "sar" "(1), " "top" "(1), " "ps" "(1), " "mpstat" "(1), " "iostat" "(1), " "vmstat" "(8)" +.PP +.I https://github.com/sysstat/sysstat +.br +.I https://sysstat.github.io/ |