PCP-PIDSTAT(1)

NAME
pcp-pidstat - Report statistics for Linux tasks.

SYNOPSIS
pcp pidstat [-s N] [-t DELTA] [-I] [-a FILE] [-f FORMAT] [-G NAME] [-U[USERNAME]] [-p PID1,PID2..] [-R/-r/-k] [-V] [-?]

DESCRIPTION
pcp-pidstat command is used for monitoring individual tasks currently being managed by the Linux kernel. Using various options it helps user to see useful information related with the processes. This information can include percentage CPU, memory and stack usages, scheduling and priority information. By default pcp-pidstat reports live data for the local host but can also report for a remote host (--host) or from a previously captured PCP archive (-a). pcp-pidstat fetches the data to be analysed from PMCD unless provided -a option. (See below)

OPTIONS
Output control options:

-s N, --samples=N
    Set the number of samples to be displayed. Since the first sample is used for the rate conversion of some of the metrics, the total number of samples reported are one less that N. Default is continous.

-t DELTA, --interval=DELTA
    Set the interval between two samples. Default is one second.

General Options:

-I  In an SMP environment, indicates that tasks CPU usage should be divided by the total number of processors.

-a FILE, --archive=FILE
    Causes pcp-pidstat to use the specified archive than connecting to PMCD. The argument to -a is a comma-separated list of names, each of which may be the base name of an archive or the name of a directory containing one or more archives. Archives can be created using pmlogger(1).

--host
    Current performance metric values are retrieved from the nominated host machine.

-B  Report process states. The argument to -B is one of the following: detail
           Show total time processes have spent in each of the 5 different states all
           Show total time processes spent in their current state [R,S,T,D,Z]
           A comma separated list of states which can be any or all of [R,S,T,Z,D]. For example, -B R,S will report processes currently in either R or S states and not report processes currently in any other states.

-f  Use the format string for formatting the timestamp. The format will be used with Python's datetime.strftime method which is mostly the same as that described in strftime(3). An empty format string(i.e,"") will remove the timestamps from the output. The default with stdout is %H:%M:%S.

-R  Report realtime priority and scheduling policy information. The following values may be displayed: UID
           The real user identification number of the task being monitored. USER
           The name of the real user owning the task being monitored. PID
           The identification number of the task being monitored. prio
           The realtime priority of the task being monitored. policy
           The scheduling policy of the task being monitored. Command
           The command name of the task.

-r  Report page faults and memory utilization. The following values may be displayed: UID
           The real user identification number of the task being monitored. USER
           The name of the real user owning the task being monitored. PID
           The identification number of the task being monitored. minflt/s
           Total number of minor faults the task has made per second, those which have not required loading a memory page from disk. majflt/s
           Total number of major faults the task has made per second, those which have required loading a memory page from disk. VSZ
           Virtual Size: The virtual memory usage of entire task in kilobytes. RSS
           Resident Set Size: The non-swapped physical memory used by the task in kilobytes. %MEM
           The tasks's currently used share of available physical memory. Command
           The command name of the task.

-k  Report stack utilization. The following values may be displayed: UID
          The real user identification number of the task being monitored. USER
          The name of the real user owning the task being monitored. PID
          The identification number of the task being monitored. StkSize
          The amount of memory in kilobytes reserved for the task as stack, but not necessarily used. StkRef
          The amount of memory in kilobytes used as stack, referenced by the task. Command
          The command name of the task.

-V  Display version and exit

-? , --help
    Display help and exit

Ouput Filter Options

-G NAME, --process-name=NAME
    Display only processes whose command name includes the string NAME. This string can be a regular expression.

-U[USERNAME], --user-name=[USERNAME]
    Display the real user name of the tasks being monitored instead of the UID. If username is specified, then only tasks belonging to the specified user are displayed.

-p PID1,PID2.. , --pid-list=PID1,PID2..
    Display only processes whose PID belongs to the given Pid List.

NOTES
pcp-pidstat is inspired by the pidstat(1) command and aims to be command line and output compatible with it.

SEE ALSO
pcp(1), pidstat(1), PCPIntro(1), pmParseInterval(3) and environ(7).