1PCP-TAPESTAT(1) General Commands Manual PCP-TAPESTAT(1)
2
6 pcp-tapestat - performance metrics i/o tape statistics tool
7
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
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 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 The other options which control the source, timing and layout of the
27 information reported by pcp-tapestat are as follows:
28 -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 -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 -h Current performance metric values are retrieved from the nominated
51 host machine.
52 -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 -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 -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 -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 -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 -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 -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 -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
121 The columns in the pcp-tapestat report have the following interpreta‐
122 tion :
123 Timestamp
125 When the -x t option is specified, this column is the timestamp
126 in ctime(3) format.
127 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 r/s The number of reads issued expressed as the number per second
133 averaged over the interval.
134 w/s The number of writes issued expressed as the number per second
136 averaged over the interval.
137 kb_r/s The amount of data read expressed in kilobytes per second aver‐
139 aged over the interval.
140 kb_w/s The amount of data written expressed in kilobytes per second
142 averaged over the interval.
143 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 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 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 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 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
171 $PCP_VAR_DIR/pmns/*
172 default PMNS specification files
173
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
182 pcp(1), PCPIntro(1), pmcd(1), pmchart(1), pmlogger(1), pcp.conf(5) and
183 pcp.env(5).
184
186 All are generated on standard error and are intended to be self-
187 explanatory.
188Performance Co-Pilot PCP PCP-TAPESTAT(1)