1PCP-PIDSTAT(1)              General Commands Manual             PCP-PIDSTAT(1)
2
3
4

NAME

6       pcp-pidstat - Report statistics for Linux tasks.
7

SYNOPSIS

9       pcp [pcp options] pidstat [-I] [-l] [-R] [-r] [-k] [-U [username]] [-V]
10       [-G processname] [-p pid1,pid2..]  [-t interval]  [-s  count]  [-a  ar‐
11       chive] [-B state] [-f format] [-Z timezone] [-z] [-?]
12

DESCRIPTION

14       The pcp-pidstat command is used for monitoring individual tasks running
15       on the system.  Using various options  it  helps  user  to  see  useful
16       information  related  to  the processes.  This information includes CPU
17       percentage, memory  and  stack  usage,  scheduling  and  priority.   By
18       default pcp-pidstat reports live data for the local host.
19
20       When  invoked  via  the  pcp(1)  command,  the -h/--host, -a/--archive,
21       -O/--origin, -s/--samples,  -t/--interval,  -Z/--timezone  and  several
22       other  pcp  options  become  indirectly  available, see PCPIntro(1) for
23       their descriptions.
24

OPTIONS

26       -I   In an SMP environment, indicates that tasks CPU  usage  should  be
27            divided by the total number of processors.
28
29       -l   Display the process command name and all its arguments.
30
31       -R   Report  realtime  priority and scheduling policy information.  The
32            following values may be displayed:
33
34            UID
35                   The real user identification number of the task being moni‐
36            tored.
37
38            USER
39                   The name of the real user owning the task being monitored.
40
41            PID
42                   The identification number of the task being monitored.
43
44            prio
45                   The realtime priority of the task being monitored.
46
47            policy
48                   The scheduling policy of the task being monitored.
49
50            Command
51                   The command name of the task.
52
53       -r   Report  page  faults and memory utilization.  The following values
54            may be displayed:
55
56            UID
57                   The real user identification number of the task being moni‐
58            tored.
59
60            USER
61                   The name of the real user owning the task being monitored.
62
63            PID
64                   The identification number of the task being monitored.
65
66            minflt/s
67                   Total  number of minor faults the task has made per second,
68            those which have not required loading a memory page from disk.
69
70            majflt/s
71                   Total number of major faults the task has made per  second,
72            those which have required loading a memory page from disk.
73
74            VSZ
75                   Virtual  Size:  The  virtual memory usage of entire task in
76            kilobytes.
77
78            RSS
79                   Resident Set Size: The non-swapped physical memory used  by
80            the task in kilobytes.
81
82            %MEM
83                   The  tasks  currently used share of available physical mem‐
84            ory.
85
86            Command
87                   The command name of the task.
88
89       -k   Report stack utilization.  The following values may be displayed:
90
91            UID
92                  The real user identification number of the task being  moni‐
93            tored.
94
95            USER
96                  The name of the real user owning the task being monitored.
97
98            PID
99                  The identification number of the task being monitored.
100
101            StkSize
102                  The  amount  of memory in kilobytes reserved for the task as
103            stack, but not necessarily used.
104
105            StkRef
106                  The amount of memory in kilobytes used as stack,  referenced
107            by the task.
108
109            Command
110                  The command name of the task.
111
112       -U [username]", --user-name[=username]
113            Display the real user name of the tasks being monitored instead of
114            the UID.  If username is specified, then only tasks  belonging  to
115            the specified user are displayed.
116
117       -V   Print version number then exit.
118
119       -G processname, --process-name=processname
120            Display only processes whose command name includes the string pro‐
121            cessname.  This string can be a regular expression.
122
123       -p pid1,pid2.., --pid-list=pid1,pid2..
124            Display only processes with the listed PIDs.
125
126       -t interval, --interval=interval
127            Set the interval between two samples.  The default is one second.
128
129       -s count, --samples=count
130            Set the number of samples to be displayed.  Since the first sample
131            is  used for the rate conversion of some of the metrics, the total
132            number of samples reported are one less than count.   The  default
133            is continous.
134
135       -a archive, --archive=archive
136            Causes pcp-pidstat to use the specified archive than connecting to
137            PMCD.  The argument to -a is a comma-separated list of names, each
138            of  which  may  be  the  base  name of an archive or the name of a
139            directory containing one or more archives.
140
141       -B   Report process states.  The argument to -B is one of  the  follow‐
142            ing:
143
144            detail
145                   Show  total time processes have spent in each of the 5 dif‐
146            ferent states
147
148            all
149                   Show total time processes spent in their current state
150
151            [R,S,T,D,Z]
152                   A comma separated list of process states.  For example,  -B
153            R,S  will  report  processes currently in either R or S states and
154            not report processes currently in any other states.
155
156       -f   Use the format string for formatting the  timestamp.   The  format
157            will  be used with the python(1) datetime.strftime method which is
158            similar to that described in strftime(3).  An empty format  string
159            (i.e, "") will remove the timestamps from the output.  The default
160            with stdout is %H:%M:%S.
161
162       -Z timezone, --timezone=timezone
163            By default, pcp-pidstat reports the time of day according  to  the
164            local  timezone  on  the  system where pcp-pidstat is run.  The -Z
165            option changes the timezone to timezone in the format of the envi‐
166            ronment variable TZ as described in environ(7).
167
168       -z , --hostzone
169            Change  the  reporting  timezone to the local timezone at the host
170            that is the source of the performance metrics.  When  replaying  a
171            PCP archive that was captured in a foreign timezone, the -z option
172            would almost always be used (the default reporting timezone is the
173            local  timezone,  which may not be the same as the timezone of the
174            PCP archive).
175
176       -? , --help
177            Display usage message and exit.
178

NOTES

180       pcp-pidstat is inspired by the pidstat(1) command and aims to  be  com‐
181       mand line and output compatible with it.
182

PCP ENVIRONMENT

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

SEE ALSO

193       pcp(1),  pidstat(1),  python(1), PCPIntro(1), pmParseInterval(3), strf‐
194       time(3) and environ(7).
195
196
197
198Performance Co-Pilot                  PCP                       PCP-PIDSTAT(1)
Impressum