# pcp-pidstat

## NAME



           **pcp-pidstat** - Report statistics for Linux tasks.
    


## SYNOPSIS



           **pcp**[_pcp options_] **pidstat**[**-I**] [**-l**] [**-R**] [**-r**] [**-k**] [**-U**[_username_]]
           [**-V**] [**-G** _processname_] [**-p** _pid1,pid2.._]  [**-t** _interval_] [**-s** _count_]
           [**-a** _archive_] [**-B** _state_] [**-f** _format_] [**-Z** _timezone_] [**-z**] [**-?**]
    


## DESCRIPTION



           The **pcp-pidstat** command is used for monitoring individual tasks
           running on the system.  Using various options it helps a user to
           see useful information related to the processes.  This information
           includes CPU percentage, memory and stack usage, scheduling and
           priority.  By default **pcp-pidstat** reports live data for the local
           host.
    


## OPTIONS



           When invoked via the pcp(1) command, the **-h** /**--host** , **-a** /**--archive** ,
           **-O** /**--origin** , **-s** /**--samples** , **-t** /**--interval** , **-Z** /**--timezone** and
           several other _pcp options_ become indirectly available; refer to
           PCPIntro(1) for a complete description of these options.
    
           The additional command line options available for **pcp-pidstat** are:
    
           **-I** In an SMP environment, indicates that tasks CPU usage should
                be divided by the total number of processors.
    
           **-l** Display the process command name and all its arguments.
    
           **-R** Report real-time 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 real-time 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 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.
    
           **-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.
    
           **-V, --version**
                Print version number then exit.
    
           **-G** _processname_**, --process-name=**_processname_
                Display only processes whose command name includes the string
                _processname_.  This string can be a regular expression.
    
           **-p** _pid1,pid2.._**, --pid-list=**_pid1,pid2.._
                Display only processes with the listed PIDs.
    
           **-t** _interval_**, --interval=**_interval_
                Set the interval between two samples.  The default is one
                second.
    
           **-s** _count_**, --samples=**_count_
                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
                than _count_.  The default is continuous.
    
           **-a** _archive_**, --archive=**_archive_
                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.
    
           **-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 process states.  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 the **python**(1) datetime.strftime
                method which is similar to 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.
    
           **-Z** _timezone_**, --timezone=**_timezone_
                By default, **pcp-pidstat** reports the time of day according to
                the local timezone on the system where **pcp-pidstat** is run.
                The **-Z** option changes the timezone to _timezone_ in the format
                of the environment variable **TZ** as described in environ(7).
    
           **-z** , **--hostzone**
                Change the reporting timezone to the local timezone at the
                host that is the source of the performance metrics.  When
                replaying a PCP archive that was captured in a foreign
                timezone, the **-z** option would almost always be used (the
                default reporting timezone is the local timezone, which may
                not be the same as the timezone of the PCP archive).
    
           **-?** , **--help**
                Display usage message and exit.
    


## NOTES



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


## PCP ENVIRONMENT



           Environment variables with the prefix **PCP_** are used to
           parameterize the file and directory names used by PCP.  On each
           installation, the file _/etc/pcp.conf_ contains the local values for
           these variables.  The **$PCP_CONF** variable may be used to specify an
           alternative configuration file, as described in pcp.conf(5).
    
           For environment variables affecting PCP tools, see
           pmGetOptions(3).
    


* * *