| 1 |
.\" tapestat manual page - (C) 2015 Hewlett-Packard Development Company, L.P. |
| 2 |
.\" Maintained by Sebastien Godard (sysstat <at> orange.fr) |
| 3 |
.TH TAPESTAT 1 "AUGUST 2023" Linux "Linux User's Manual" -*- nroff -*- |
| 4 |
.SH NAME |
| 5 |
tapestat \- Report tape statistics. |
| 6 |
|
| 7 |
.SH SYNOPSIS |
| 8 |
.B tapestat [ \-k | \-m ] [ \-t ] [ \-V ] [ \-y ] [ \-z ] [ \-\-human ] [ |
| 9 |
.IB "interval " "[ " "count " "] ]" |
| 10 |
|
| 11 |
.SH DESCRIPTION |
| 12 |
.RB "The " "tapestat" |
| 13 |
command is used for monitoring the activity of tape drives connected to a system. |
| 14 |
.PP |
| 15 |
The first report generated by the |
| 16 |
.BR "tapestat " "command provides statistics" |
| 17 |
concerning the time since the system was booted, unless the |
| 18 |
.B \-y |
| 19 |
option is used, when this first report is omitted. |
| 20 |
Each subsequent report covers the time since the previous report. |
| 21 |
.PP |
| 22 |
.RI "The " "interval" |
| 23 |
parameter specifies the amount of time in seconds between each report. The |
| 24 |
.I count |
| 25 |
parameter can be specified in conjunction with the |
| 26 |
.IR "interval " "parameter. If the " "count " "parameter is specified, the value of " "count" |
| 27 |
determines the number of reports generated at |
| 28 |
.IR "interval " "seconds apart. If the " "interval " "parameter is specified without the " "count" |
| 29 |
.RB "parameter, the " "tapestat" |
| 30 |
command generates reports continuously. |
| 31 |
|
| 32 |
.SH REPORT |
| 33 |
The |
| 34 |
.B tapestat |
| 35 |
report provides statistics for each tape drive connected to the system. |
| 36 |
The following data are displayed: |
| 37 |
.IP r/s |
| 38 |
The number of reads issued expressed as the number per second averaged over the interval. |
| 39 |
.IP w/s |
| 40 |
The number of writes issued expressed as the number per second averaged over the interval. |
| 41 |
.IP "kB_read/s | MB_read/s" |
| 42 |
The amount of data read expressed in kilobytes (by default or if option |
| 43 |
.BR "\-k " "used) or megabytes (if option " "\-m" |
| 44 |
used) per second averaged over the interval. |
| 45 |
.IP "kB_wrtn/s | MB_wrtn/s" |
| 46 |
The amount of data written expressed in kilobytes (by default or if option |
| 47 |
.BR "\-k " "used) or megabytes (if option " "\-m" |
| 48 |
used) per second averaged over the interval. |
| 49 |
.IP %Rd |
| 50 |
Read percentage wait - The percentage of time over the interval spent waiting for read requests |
| 51 |
to complete. |
| 52 |
The time is measured from when the request is dispatched to the SCSI mid-layer until it signals |
| 53 |
that it completed. |
| 54 |
.IP %Wr |
| 55 |
Write percentage wait - The percentage of time over the interval spent waiting for write requests |
| 56 |
to complete. The time is measured from when the request is dispatched to the SCSI mid-layer until |
| 57 |
it signals that it completed. |
| 58 |
.IP %Oa |
| 59 |
Overall percentage wait - The percentage of time over the interval spent waiting for any |
| 60 |
I/O request to complete (read, write, and other). |
| 61 |
.IP Rs/s |
| 62 |
The number of I/Os, expressed as the number per second averaged over the interval, where |
| 63 |
a non-zero residual value was encountered. |
| 64 |
.IP Ot/s |
| 65 |
The number of I/Os, expressed as the number per second averaged over the interval, that |
| 66 |
were included as "other". Other I/O includes ioctl calls made to the tape driver and |
| 67 |
implicit operations performed by the tape driver such as rewind on close |
| 68 |
(for tape devices that implement rewind on close). It does not include any I/O performed |
| 69 |
using methods outside of the tape driver (e.g. via sg ioctls). |
| 70 |
|
| 71 |
.SH OPTIONS |
| 72 |
.TP |
| 73 |
.B \-\-human |
| 74 |
Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.) |
| 75 |
The units displayed with this option supersede any other default units (e.g. |
| 76 |
kilobytes, sectors...) associated with the metrics. |
| 77 |
.TP |
| 78 |
.B \-k |
| 79 |
Show the amount of data written or read in kilobytes per second instead of megabytes. |
| 80 |
This option is mutually exclusive with |
| 81 |
.BR "\-m" "." |
| 82 |
.TP |
| 83 |
.B \-m |
| 84 |
Show the amount of data written or read in megabytes per second instead of kilobytes. |
| 85 |
This option is mutually exclusive with |
| 86 |
.BR "\-k" "." |
| 87 |
.TP |
| 88 |
.B \-t |
| 89 |
Display time stamps. The time stamp format may depend |
| 90 |
on the value of the |
| 91 |
.BR "S_TIME_FORMAT " "environment variable (see below)." |
| 92 |
.TP |
| 93 |
.B \-V |
| 94 |
Print version and exit. |
| 95 |
.TP |
| 96 |
.B \-y |
| 97 |
Omit the initial statistic showing values since boot. |
| 98 |
.TP |
| 99 |
.B \-z |
| 100 |
.RB "Tell " "tapestat" |
| 101 |
to omit output for any tapes for which there was no activity |
| 102 |
during the sample period. |
| 103 |
|
| 104 |
.SH CONSIDERATIONS |
| 105 |
It is possible for a percentage value (read, write, or other) to be greater than 100 percent (the |
| 106 |
.B tapestat |
| 107 |
command will never show a percentage value more than 999). |
| 108 |
If rewinding a tape takes 40 seconds where the interval time is 5 seconds the %Oa value |
| 109 |
would show as 0 in the intervals before the rewind completed and then show as approximately |
| 110 |
800 percent when the rewind completes. |
| 111 |
|
| 112 |
Similar values will be observed for %Rd and %Wr if a tape drive stops reading or writing |
| 113 |
and then restarts (that is it stopped streaming). In such a case you may see the r/s or w/s drop to zero and the %Rd/%Wr value could be higher than 100 when reading or writing continues |
| 114 |
(depending on how long it takes to restart writing or reading). |
| 115 |
This is only an issue if it happens a lot as it may cause tape wear and will impact |
| 116 |
on the backup times. |
| 117 |
|
| 118 |
For fast tape drives you may see low percentage wait times. |
| 119 |
This does not indicate an issue with the tape drive. For a slower tape drive (e.g. an older |
| 120 |
generation DDS drive) the speed of the tape (and tape drive) is much slower than filesystem I/O, |
| 121 |
percent wait times are likely to be higher. For faster tape drives (e.g. LTO) the percentage |
| 122 |
wait times are likely to be lower as program writing to or reading from tape is going |
| 123 |
to be doing a lot more filesystem I/O because of the higher throughput. |
| 124 |
|
| 125 |
Although tape statistics are implemented in the kernel using atomic variables they cannot be |
| 126 |
read atomically as a group. All of the statistics values are read from different files under |
| 127 |
.IR "/sys" "," |
| 128 |
because of this there may be I/O completions while reading the different files for the |
| 129 |
one tape drive. This may result in a set of statistics for a device that contain some values |
| 130 |
before an I/O completed and some after. |
| 131 |
|
| 132 |
This command uses rounding down as the rounding method when calculating per second statistics. |
| 133 |
If, for example, you are using |
| 134 |
.BR "dd " "to copy one tape to another and running " "tapestat" |
| 135 |
with an interval of 5 seconds and over the interval there were 3210 writes and 3209 reads |
| 136 |
then w/s would show 642 and r/s 641 (641.8 rounded down to 641). In such a case if it was |
| 137 |
a tar archive being copied (with a 10k block size) you would also see a difference between |
| 138 |
the kB_read/s and kB_wrtn/s of 2 (one I/O 10k in size divided by the interval period of 5 |
| 139 |
seconds). If instead there were 3210 writes and 3211 reads both w/s and r/s would both show |
| 140 |
642 but you would still see a difference between the kB_read/s and kB_wrtn/s values of 2 kB/s. |
| 141 |
|
| 142 |
This command is provided with an interval in seconds. However internally the interval is |
| 143 |
tracked per device and can potentially have an effect on the per second statistics reported. |
| 144 |
The time each set of statistics is captured is kept with those statistics. The difference |
| 145 |
between the current and previous time is converted to milliseconds for use in calculations. |
| 146 |
We can look at how this can impact the statistics reported if we use an example of a tar |
| 147 |
archive being copied between two tape drives using |
| 148 |
.BR "dd" "." |
| 149 |
If both devices reported 28900 kilobytes |
| 150 |
transferred and the reading tape drive had an interval of 5001 milliseconds and the writing |
| 151 |
tape drive 5000 milliseconds that would calculate out as 5778 kB_read/s and 5780 kB_wrtn/s. |
| 152 |
|
| 153 |
The impact of some retrieving statistics during an I/O completion, rounding down, and small differences in the interval period on the statistics calculated should be minimal but may be non-zero. |
| 154 |
|
| 155 |
.SH ENVIRONMENT |
| 156 |
.RB "The " "tapestat" |
| 157 |
command takes into account the following environment variables: |
| 158 |
.TP |
| 159 |
.B S_COLORS |
| 160 |
By default statistics are displayed in color when the output is connected to a terminal. |
| 161 |
Use this variable to change the settings. Possible values for this variable are |
| 162 |
.IR "never" ", " "always " "or " "auto" |
| 163 |
(the latter is equivalent to the default settings). |
| 164 |
.br |
| 165 |
Please note that the color (being red, yellow, or some other color) used to display a value |
| 166 |
is not indicative of any kind of issue simply because of the color. It only indicates different |
| 167 |
ranges of values. |
| 168 |
.TP |
| 169 |
.B S_COLORS_SGR |
| 170 |
Specify the colors and other attributes used to display statistics on the terminal. |
| 171 |
Its value is a colon-separated list of capabilities that defaults to |
| 172 |
.BR "I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22" "." |
| 173 |
Supported capabilities are: |
| 174 |
.RS |
| 175 |
.TP |
| 176 |
.B I= |
| 177 |
SGR (Select Graphic Rendition) substring for tape names. |
| 178 |
.TP |
| 179 |
.B N= |
| 180 |
SGR substring for non-zero statistics values. |
| 181 |
.TP |
| 182 |
.BR "W=" " (or " "M=" ")" |
| 183 |
SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the |
| 184 |
metric's meaning). |
| 185 |
.TP |
| 186 |
.BR "X=" " (or " "H=" ")" |
| 187 |
SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the |
| 188 |
metric's meaning). |
| 189 |
.TP |
| 190 |
.B Z= |
| 191 |
SGR substring for zero values. |
| 192 |
.RE |
| 193 |
.TP |
| 194 |
.B S_TIME_FORMAT |
| 195 |
If this variable exists and its value is |
| 196 |
.BR ISO |
| 197 |
then the current locale will be ignored when printing the date in the report |
| 198 |
header. The |
| 199 |
.B tapestat |
| 200 |
command will use the ISO 8601 format (YYYY-MM-DD) instead. |
| 201 |
The timestamp displayed with option |
| 202 |
.B \-t |
| 203 |
will also be compliant with ISO 8601 format. |
| 204 |
|
| 205 |
.SH BUGS |
| 206 |
.IR "/sys " "filesystem must be mounted for" |
| 207 |
.B tapestat |
| 208 |
to work. It will not work on kernels that do not have sysfs support |
| 209 |
.PP |
| 210 |
This command requires kernel version 4.2 or later |
| 211 |
(or tape statistics support backported for an earlier kernel version). |
| 212 |
.PP |
| 213 |
.RB "Although " "tapestat" |
| 214 |
speaks of kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)... |
| 215 |
A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes. |
| 216 |
|
| 217 |
.SH FILES |
| 218 |
.I /sys/class/scsi_tape/st<num>/stats/* |
| 219 |
.RS |
| 220 |
Statistics files for tape devices. |
| 221 |
.RE |
| 222 |
.PP |
| 223 |
.IR "/proc/uptime " "contains system uptime." |
| 224 |
|
| 225 |
.SH AUTHOR |
| 226 |
Initial revision by Shane M. SEYMOUR (shane.seymour <at> hpe.com) |
| 227 |
.br |
| 228 |
Modified for sysstat by Sebastien Godard (sysstat <at> orange.fr) |
| 229 |
|
| 230 |
.SH SEE ALSO |
| 231 |
.BR "iostat" "(1), " "mpstat" "(1)" |
| 232 |
.PP |
| 233 |
.I https://github.com/sysstat/sysstat |
| 234 |
.br |
| 235 |
.I https://sysstat.github.io/ |