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  pidstat  [-s  N]  [-t  DELTA] [-I] [-a FILE] [-f FORMAT] [-G NAME]
10       [-U[USERNAME]] [-p PID1,PID2..]  [-R/-r/-k] [-V] [-Z  timezone  --time‐
11       zone=TZ] [-z --hostzone] [-l] [-?]
12

DESCRIPTION

14       pcp-pidstat  command  is used for monitoring individual tasks currently
15       being managed by the Linux kernel.  Using various options it helps user
16       to  see  useful information related to the processes.  This information
17       includes percentage CPU, memory and stack usage, scheduling and  prior‐
18       ity.  By 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.
23

OPTIONS

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

NOTES

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

SEE ALSO

186       pcp(1),  pidstat(1),  python(1), PCPIntro(1), pmParseInterval(3), strf‐
187       time(3) and environ(7).
188
189
190
191Performance Co-Pilot                  PCP                       PCP-PIDSTAT(1)
Impressum