PCP-TAPESTAT(1)

💖 PCP-TAPESTAT — the tea on your tape drive's I/O 💖

okay bestie, this is the manual page for pcp-tapestat from the General Commands Manual set, and no cap, it's giving "let's spy on your tape devices" energy. pull up a chair 🎀

---

✨ NAME ✨

pcp-tapestat — report tape I/O statistics 🎞️✨

---

🌸 SYNOPSIS 🌸

pcp [pcp options] tapestat [-u?]  [-G method] [-P precision] [-R
pattern] [-x [t][,h][,noidle]]

---

🦋 DESCRIPTION 🦋

pcp-tapestat reports I/O statistics for tape devices. that's it, that's the whole vibe 💅

---

👑 OPTIONS 👑

when you invoke it via the pcp(1) command, a whole lil squad of pcp options becomes indirectly available to you, bestie: -A/--align, -a/--archive, -h/--host, -O/--origin, -S/--start, -s/--samples, -t/--interval, -T/--finish, -V/--version, -Z/--timezone and -z/--hostzone. for the full description of all of those, go read PCPIntro(1) — it's the main character of this whole situation 🌈

and here's the extra lineup that's actually specific to pcp-tapestat:

• -G method, --aggregate=method — says "hey, aggregate the stats for the device names that match the regular expression you gave with the -R regex option, and do it according to method". heads up though: this is aggregation based on matching device names, not temporal aggregation, okay? don't get it twisted 🙈

when -G is used, the device name column gets reported as method(regex). so like, if you run -G sum -R 'st(0|1)$', the device column becomes sum(st(0|1)$) and the summed statistics for st0 and st1 show up in the remaining columns. slay ✨

if -G is specified but -R is not, then the default regex is .*, i.e. it matches all device names. if method is sum then the statistics are summed. if method is avg then the statistics are summed and then averaged by dividing by the number of matching device names. and if method is min or max, then the minimum or maximum statistics for matching devices are reported, respectively. math girlies stay winning 📊

• -P N, --precision=N — this sets the precision, aka the number of decimal places to report. the default precision N can be set to something other than the default (2). note that the avgrq-sz and avgqu-sz fields are always reported with N+1 decimals of precision — those fields typically have values less than 1, so they need the extra room 🥺
• -R pattern, --regex=pattern — restricts the report to device names matching a regular expression pattern. the pattern is searched as a perl style regular expression, and it'll match any portion of a device name. examples, because we love examples:
  • '^st[0-9]+' will match all device names starting with 'st' followed by one or more numbers.
  • '^st(0|1)$' will only match 'st0' and 'st1'.
  • 'st0$' will match 'st0' but not 'st1'.

also go peek at the -G option for the aggregation options, they're besties 🫶

• -u, --no-interpolation — okay so when you're replaying a set of archives, by default values are reported according to the requested sample interval (the -t option), not according to the actual interval recorded in the archive(s). without this option, PCP interpolates the values to be reported based on the records in the set of archives — which is super useful when you use the -t option to replay a set of archives with a longer sampling interval than the one the archive(s) was originally recorded with. with the -u option, uninterpolated reporting is enabled: every value is reported according to the native recording interval in the set of archives 🎯

and now the fine print, bestie, read it: when -u is specified, the -t option makes no sense and is incompatible, because the replay interval is always the same as the recording interval in the set of archive. plus, -u only makes sense when replaying archives (see the -a option on PCPIntro(1)), and so if -u is specified then -a must also be specified. periodt 💀

• -V, --version — display the version number and exit. bye 👋
• -x comma-separated-options — specifies a comma-separated list of one or more extended reporting options, as follows:
  • t — prefix every line in the report with a timestamp in ctime(3) format,
  • h — omit the heading, which is otherwise reported every 24 samples,
  • noidle — Do not display statistics for idle devices.
• -?, --help — display the usage message and exit 🥰

---

📊 REPORT 📊

the columns in the pcp-tapestat report mean the following, and yes we're going through all of them:

• Timestamp — when the -x t option is specified, this column is the timestamp in ctime(3) format ⏰
• Device — specifies the tape device name. when -G is specified, this is replaced by the aggregation method and regular expression — see the -G and -R options above 👆
• r/s — the number of reads issued, expressed as the number per second averaged over the interval.
• w/s — the number of writes issued, expressed as the number per second averaged over the interval.
• kb_r/s — the amount of data read, expressed in kilobytes per second averaged over the interval.
• kb_w/s — the amount of data written, expressed in kilobytes per second averaged over the interval.
• r_pct — read percentage wait: the percentage of time over the interval spent waiting for read requests to complete. the time is measured from when the request is dispatched to the SCSI mid-layer until it signals that it completed 🌀
• w_pct — write percentage wait: the percentage of time over the interval spent waiting for write requests to complete. the time is measured from when the request is dispatched to the SCSI mid-layer until it signals that it completed 🌀
• o_pct — overall percentage wait: the percentage of time over the interval spent waiting for any I/O request to complete (read, write, and other).
• Rs/s — the number of I/Os, expressed as the number per second averaged over the interval, where a non-zero residual value was encountered.
• o_cnt — the number of I/Os, expressed as the number per second averaged over the interval, that were included as "other". Other I/O includes ioctl calls made to the tape driver and implicit operations performed by the tape driver such as rewind on close (for tape devices that implement rewind on close). it does not include any I/O performed using methods outside of the tape driver (e.g. via sg ioctls) 🚫

---

🌱 PCP ENVIRONMENT 🌱

environment variables with the prefix PCP_ are used to parameterize the file and directory names used by PCP. on each installation, the file /etc/pcp.conf contains the local values for these variables. the $PCP_CONF variable may be used to specify an alternative configuration file, as described in pcp.conf(5) 💚

for environment variables affecting PCP tools, see pmGetOptions(3).

---

🐛 DEBUGGING OPTIONS 🐛

the -D or --debug pcp option enables the output of additional diagnostics on stderr to help triage problems — although ngl, the information is sometimes cryptic and primarily intended to provide guidance for developers rather than for end-users, so don't stress if it reads like a riddle 🙈

debug is a comma separated list of debugging options; use pmdbg(1) with the -l option to obtain a list of the available debugging options and their meaning 🔍

---

🫶 SEE ALSO 🫶

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

---

and that's the whole page, bestie!! this lil masterpiece comes to you from Performance Co-Pilot — PCP, the one and only 👑 — and it's filed under PCP-TAPESTAT(1) in the General Commands Manual. go forth and tape-stat, you've got this 💖✨🎀