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

NAME

6       pmiostat, pcp-iostat - performance metrics i/o statistics tool
7

SYNOPSIS

9       pcp iostat  [-A  align  --align=TIME]  [-a  archive --archive=FILE] [-G
10       method --aggregate=method] [-h  host  --host=HOST]  [-O  offset  --ori‐
11       gin=TIME] [-S starttime --start=TIME] [-s samples --samples=N] [-T end‐
12       time --finish=TIME] [-t interval --interval=DELTA] [-P precision --pre‐
13       cision=N]  [-R pattern --regex=pattern] [-u --no-interpolate] [-Z time‐
14       zone --timezone=TZ] [-z --hostzone] [-? --help] [-x  [dm][,t][,h][,noi‐
15       dle]]
16

DESCRIPTION

18       pcp-iostat  reports  I/O  statistics  for  scsi devices (by default) or
19       device-mapper devices (if the -x dm option is specified).   By  default
20       pcp-iostat reports live data for the local host but can also report for
21       a remote host (-h) or from a previously captured PCP archive (-a).
22
23       The -S, -T, -O and -A options may be used to define a  time  window  to
24       restrict  the  samples retrieved, set an initial origin within the time
25       window, or specify a ``natural'' alignment of the sample  times;  refer
26       to PCPIntro(1) for a complete description of these options.
27
28       The  other  options  which control the source, timing and layout of the
29       information reported by pcp-iostat are as follows:
30
31       -a   Performance metric values are retrieved from the  Performance  Co-
32            Pilot  (PCP) archive log files identified by the argument archive,
33            which is a comma-separated list of names, each of which may be the
34            base  name of an archive or the name of a directory containing one
35            or more archives. See also -u.
36
37       -G   Specifies that statistics for device names  matching  the  regular
38            expression specified with the -R regex option should be aggregated
39            according to method.  Note this is aggregation based  on  matching
40            device  names  (not  temporal  aggregation).  When -G is used, the
41            device name column is reported as method(regex), e.g.  if  -G  sum
42            -R   'sd(a|b)$'   is   specified,   the   device  column  will  be
43            sum(sd(a|b)$) and summed  statistics  for  sda  and  sdb  will  be
44            reported  in  the remaining columns.  If -G is specified but -R is
45            not specified, then the default regex is  .*,  i.e.  matching  all
46            device  names.   If  method is sum then the statistics are summed.
47            This includes the %util column, which may therefore exceed 100% if
48            more than one device name matches.  If method is avg then the sta‐
49            tistics are summed and then averaged by dividing by the number  of
50            matching  device  names.   If method is min or max, the minimum or
51            maximum statistics for matching  devices  are  reported,  respect‐
52            fully.
53
54       -h   Current performance metric values are retrieved from the nominated
55            host machine.
56
57       -s   The argument samples defines the number of samples to be retrieved
58            and  reported.  If samples is 0 or -s is not specified, pcp-iostat
59            will sample and report continuously (in real time mode)  or  until
60            the end of the set of PCP archives (in archive mode).
61
62       -t   The default update interval may be set to something other than the
63            default 1  second.   The  interval  argument  follows  the  syntax
64            described  in  PCPIntro(1),  and  in  the  simplest form may be an
65            unsigned integer (the implied units in  this  case  are  seconds).
66            The  -t option is particularly useful when replaying large sets of
67            archives (-a option) that span several hours  or  even  days.   In
68            this  case  specifying  a large interval (e.g. 1h for 1 hour) will
69            reduce the volume of data reported and the i/o statistics will  be
70            averaged (interpolated) over the reporting interval (unless the -u
71            option is specified, see below).
72
73       -R   This restricts the report to device  names  matching  regex.   The
74            regex  pattern is searched as a perl style regular expression, and
75            will match any portion of a device name.  e.g. '^sd[a-zA-Z]+' will
76            match  all device names starting with 'sd' followed by one or more
77            alphabetic characters.  e.g. '^sd(a|b)$' will only match 'sda' and
78            'sdb'.  e.g. 'sda$' will match 'sda' but not 'sdab'.  See also the
79            -G option for aggregation options.
80
81       -P   This indicates the number of decimals to print. The default preci‐
82            sion  N may be set to something other than the default 2 decimals.
83            Note that the avgrq-sz and avgqu-sz  fields  are  always  reported
84            with  N+1 decimals of precision.  These fields typically have val‐
85            ues less than 1.0.
86
87       -u   When replaying a set of archives, by default values  are  reported
88            according to the selected sample interval (-t option), not accord‐
89            ing to the actual record intervals in the  set  of  archives.   To
90            this  effect  PCP  interpolates the values to be reported based on
91            the records in the set of archives,  and  is  particularly  useful
92            when  the  -t  option  is  used to replay a set of archives with a
93            longer sampling interval than the underlying interval the  set  of
94            archives  was originally recorded with.  With the -u option, unin‐
95            terpolated reporting is enabled - every value is reported  accord‐
96            ing to the native recording interval in the set of archives.  When
97            the -u option is specified, the -t option makes no  sense  and  is
98            incompatible because the replay interval is always the same as the
99            recording interval in the set of archive.  In  addition,  -u  only
100            makes sense when replaying a set of archives, see -a above, and so
101            if -u is specified then -a must also be specified.
102
103       -Z   By default, pcp-iostat reports the time of day  according  to  the
104            local  timezone  on  the  system  where pcp-iostat is run.  The -Z
105            option changes the timezone to timezone in the format of the envi‐
106            ronment variable TZ as described in environ(7).
107
108       -z   Change  the  reporting  timezone to the local timezone at the host
109            that is the source of the performance metrics, as  identified  via
110            either  the  -h  or -a options.  When replaying a PCP archive that
111            was captured in a foreign timezone, the  -z  option  would  almost
112            always  be used (the default reporting timezone is the local time‐
113            zone, which may not be the same as the timezone  of  the  PCP  ar‐
114            chive).
115
116       -x   Specifies a comma separated list of one or more extended reporting
117            options as follows:
118            dm - report statistics for device-mapper logical  devices  instead
119            of scsi devices,
120            t  -  prefix every line in the report with a timestamp in ctime(3)
121            format,
122            h - omit the heading, which is otherwise reported  every  24  sam‐
123            ples,
124            noidle - Do not display statistics for idle devices.
125

REPORT

127       The  columns in the pcp-iostat report have the following interpretation
128       :
129
130       Timestamp
131              When the -x t option is specified, this column is the  timestamp
132              in ctime(3) format.
133
134       Device Specifies  the  scsi  device name, or if -x dm is specified, the
135              device-mapper logical device name.  When -G is  specified,  this
136              is  replaced  by the aggregation method and regular expression -
137              see the -G and -R options above.
138
139       rrqm/s The number of read requests expressed as a rate per-second  that
140              were merged during the reporting interval by the I/O scheduler.
141
142       wrqm/s The number of write requests expressed as a rate per-second that
143              were merged during the reporting interval by the I/O scheduler.
144
145       r/s    The number of read  requests  completed  by  the  device  (after
146              merges),  expressed  as  a  rate per second during the reporting
147              interval.
148
149       w/s    The number of write requests  completed  by  the  device  (after
150              merges),  expressed  as  a  rate per second during the reporting
151              interval.
152
153       rkB/s  The average volume of data read from  the  device  expressed  as
154              KBytes/second during the reporting interval.
155
156       wkB/s  The  average  volume  of data written to the device expressed as
157              KBytes/second during the reporting interval.
158
159       avgrq-sz
160              The average I/O request size for both reads and  writes  to  the
161              device expressed as Kbytes during the reporting interval.
162
163       avgqu-sz
164              The  average  queue  length  of  read  and write requests to the
165              device during the reporting interval.
166
167       await  The average time in milliseconds that read  and  write  requests
168              were  queued  (and  serviced) to the device during the reporting
169              interval.
170
171       r_await
172              The average time in milliseconds that read requests were  queued
173              (and serviced) to the device during the reporting interval.
174
175       w_await
176              The average time in milliseconds that write requests were queued
177              (and serviced) to the device during the reporting interval.
178
179       %util  The percentage of time during the reporting  interval  that  the
180              device  was busy processing requests.  A value of 100% indicates
181              device saturation.
182

FILES

184       $PCP_VAR_DIR/pmns/*
185                 default PMNS specification files
186

PCP ENVIRONMENT

188       Environment variables with the prefix PCP_ are used to parameterize the
189       file  and  directory names used by PCP.  On each installation, the file
190       /etc/pcp.conf contains the  local  values  for  these  variables.   The
191       $PCP_CONF  variable may be used to specify an alternative configuration
192       file, as described in pcp.conf(5).
193

SEE ALSO

195       pcp(1), PCPIntro(1), iostat2pcp(1), pmcd(1),  pmchart(1),  pmlogger(1),
196       pcp.conf(5) and pcp.env(5).
197

DIAGNOSTICS

199       All  are  generated  on  standard  error  and  are intended to be self-
200       explanatory.
201
202
203
204Performance Co-Pilot                  PCP                        PCP-IOSTAT(1)
Impressum