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

NAME

6       pcp-tapestat - performance metrics i/o tape statistics tool
7

SYNOPSIS

9       pcp-tapestat  [-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 [t][,h][,noidle]]
15

DESCRIPTION

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

REPORT

121       The columns in the pcp-tapestat report have the  following  interpreta‐
122       tion :
123
124       Timestamp
125              When  the -x t option is specified, this column is the timestamp
126              in ctime(3) format.
127
128       Device Specifies the tape device name When -G  is  specified,  this  is
129              replaced  by the aggregation method and regular expression - see
130              the -G and -R options above.
131
132       r/s    The number of reads issued expressed as the  number  per  second
133              averaged over the interval.
134
135       w/s    The  number  of writes issued expressed as the number per second
136              averaged over the interval.
137
138       kb_r/s The amount of data read expressed in kilobytes per second  aver‐
139              aged over the interval.
140
141       kb_w/s The  amount  of  data  written expressed in kilobytes per second
142              averaged over the interval.
143
144       r_pct  Read percentage wait - The percentage of time over the  interval
145              spent  waiting  for read requests to complete.  The time is mea‐
146              sured from when the request is dispatched to the SCSI  mid-layer
147              until it signals that it completed.
148
149       w_pct  Write percentage wait - The percentage of time over the interval
150              spent waiting for write requests to complete.  The time is  mea‐
151              sured  from when the request is dispatched to the SCSI mid-layer
152              until it signals that it completed.
153
154       o_pct  Overall percentage wait  -  The  percentage  of  time  over  the
155              interval  spent  waiting  for any I/O request to complete (read,
156              write, and other).
157
158       Rs/s   The number of I/Os, expressed as the number per second  averaged
159              over  the  interval, where a non-zero residual value was encoun‐
160              tered.
161
162       o_cnt  The  number of I/Os, expressed as the number per second averaged
163              over  the  interval,  that  were included as "other".  Other I/O
164              includes ioctl calls made to the tape driver and implicit opera‐
165              tions  performed by the tape driver such as rewind on close (for
166              tape devices that implement  rewind  on  close).   It  does  not
167              include  any  I/O  performed  using  methods outside of the tape
168              driver (e.g. via sg ioctls).
169

FILES

171       $PCP_VAR_DIR/pmns/*
172                 default PMNS specification files
173

PCP ENVIRONMENT

175       Environment variables with the prefix PCP_ are used to parameterize the
176       file  and  directory names used by PCP.  On each installation, the file
177       /etc/pcp.conf contains the  local  values  for  these  variables.   The
178       $PCP_CONF  variable may be used to specify an alternative configuration
179       file, as described in pcp.conf(5).
180

SEE ALSO

182       pcp(1), PCPIntro(1), pmcd(1), pmchart(1), pmlogger(1), pcp.conf(5)  and
183       pcp.env(5).
184

DIAGNOSTICS

186       All  are  generated  on  standard  error  and  are intended to be self-
187       explanatory.
188
189
190
191Performance Co-Pilot                  PCP                      PCP-TAPESTAT(1)
Impressum