1TAPESTAT(1)                   Linux User's Manual                  TAPESTAT(1)
2
3
4

NAME

6       tapestat - Report tape statistics.
7

SYNOPSIS

9       tapestat [ -k | -m ] [ -t ] [ -V ] [ -y ] [ -z ] [ --human ] [ interval
10       [ count ] ]
11

DESCRIPTION

13       The tapestat command is used for monitoring the activity of tape drives
14       connected to a system.
15
16       The  first report generated by the tapestat command provides statistics
17       concerning the time since the system was booted, unless the  -y  option
18       is  used,  when  this  first report is omitted.  Each subsequent report
19       covers the time since the previous report.
20
21       The interval parameter specifies the amount of time in seconds  between
22       each  report.  The count parameter can be specified in conjunction with
23       the interval parameter. If the count parameter is specified, the  value
24       of count determines the number of reports generated at interval seconds
25       apart. If the interval parameter is specified without the count parame‐
26       ter, the tapestat command generates reports continuously.
27
28

REPORT

30       The  tapestat  report provides statistics for each tape drive connected
31       to the system.  The following data are displayed:
32
33       r/s
34              The number of reads issued expressed as the  number  per  second
35              averaged over the interval.
36
37       w/s
38              The  number  of writes issued expressed as the number per second
39              averaged over the interval.
40
41       kB_read/s | MB_read/s
42              The amount of data read expressed in kilobytes (by default or if
43              option  -k  used)  or  megabytes  (if option -m used) per second
44              averaged over the interval.
45
46       kB_wrtn/s | MB_wrtn/s
47              The amount of data written expressed in kilobytes (by default or
48              if  option  -k used) or megabytes (if option -m used) per second
49              averaged over the interval.
50
51       %Rd
52              Read percentage wait - The percentage of time over the  interval
53              spent  waiting  for read requests to complete.  The time is mea‐
54              sured from when the request is dispatched to the SCSI  mid-layer
55              until it signals that it completed.
56
57       %Wr
58              Write percentage wait - The percentage of time over the interval
59              spent waiting for write requests to complete. The time  is  mea‐
60              sured  from when the request is dispatched to the SCSI mid-layer
61              until it signals that it completed.
62
63       %Oa
64              Overall percentage wait - The percentage of time over the inter‐
65              val  spent waiting for any I/O request to complete (read, write,
66              and other).
67
68       Rs/s
69              The number of I/Os, expressed as the number per second  averaged
70              over  the  interval, where a non-zero residual value was encoun‐
71              tered.
72
73       Ot/s
74              The number of I/Os, expressed as the number per second  averaged
75              over  the  interval,  that  were  included as "other". Other I/O
76              includes ioctl calls made to the tape driver and implicit opera‐
77              tions  performed by the tape driver such as rewind on close (for
78              tape devices that  implement  rewind  on  close).  It  does  not
79              include  any  I/O  performed  using  methods outside of the tape
80              driver (e.g. via sg ioctls).
81

OPTIONS

83       --human
84              Print sizes in human readable format  (e.g.  1.0k,  1.2M,  etc.)
85              The units displayed with this option supersede any other default
86              units (e.g.  kilobytes, sectors...) associated with the metrics.
87
88       -k     Show the amount of data written or read in kilobytes per  second
89              instead  of  megabytes.   This option is mutually exclusive with
90              -m.
91
92       -m     Show the amount of data written or read in megabytes per  second
93              instead  of  kilobytes.   This option is mutually exclusive with
94              -k.
95
96       -t     Display time stamps. The time stamp format  may  depend  on  the
97              value of the S_TIME_FORMAT environment variable (see below).
98
99       -V     Print version and exit.
100
101       -y     Omit the initial statistic showing values since boot.
102
103       -z     Tell  tapestat  to omit output for any tapes for which there was
104              no activity during the sample period.
105
106

CONSIDERATIONS

108       It is possible for a percentage value (read, write,  or  other)  to  be
109       greater  than  100 percent (the tapestat command will never show a per‐
110       centage value more than 999).  If rewinding a  tape  takes  40  seconds
111       where  the  interval time is 5 seconds the %Oa value would show as 0 in
112       the intervals before the rewind completed and  then  show  as  approxi‐
113       mately 800 percent when the rewind completes.
114
115       Similar  values  will be observed for %Rd and %Wr if a tape drive stops
116       reading or writing and then restarts (that is it stopped streaming). In
117       such  a  case  you  may see the r/s or w/s drop to zero and the %Rd/%Wr
118       value could be higher  than  100  when  reading  or  writing  continues
119       (depending  on  how long it takes to restart writing or reading).  This
120       is only an issue if it happens a lot as it may cause tape wear and will
121       impact on the backup times.
122
123       For  fast tape drives you may see low percentage wait times.  This does
124       not indicate an issue with the tape drive.  For  a  slower  tape  drive
125       (e.g.  an  older  generation DDS drive) the speed of the tape (and tape
126       drive) is much slower than  filesystem  I/O,  percent  wait  times  are
127       likely  to  be higher. For faster tape drives (e.g. LTO) the percentage
128       wait times are likely to be lower as program writing to or reading from
129       tape  is  going  to  be  doing a lot more filesystem I/O because of the
130       higher throughput.
131
132       Although tape statistics are implemented in  the  kernel  using  atomic
133       variables they cannot be read atomically as a group. All of the statis‐
134       tics values are read from different files under /sys, because  of  this
135       there  may be I/O completions while reading the different files for the
136       one tape drive. This may result in a set of  statistics  for  a  device
137       that contain some values before an I/O completed and some after.
138
139       This command uses rounding down as the rounding method when calculating
140       per second statistics.  If, for example, you are using dd to  copy  one
141       tape  to another and running tapestat with an interval of 5 seconds and
142       over the interval there were 3210 writes and 3209 reads then w/s  would
143       show  642 and r/s 641 (641.8 rounded down to 641). In such a case if it
144       was a tar archive being copied (with a 10k block size) you  would  also
145       see  a difference between the kB_read/s and kB_wrtn/s of 2 (one I/O 10k
146       in size divided by the interval period of 5 seconds). If instead  there
147       were  3210  writes  and 3211 reads both w/s and r/s would both show 642
148       but you  would  still  see  a  difference  between  the  kB_read/s  and
149       kB_wrtn/s values of 2 kB/s.
150
151       This  command  is  provided with an interval in seconds. However inter‐
152       nally the interval is tracked per device and can  potentially  have  an
153       effect  on  the  per  second statistics reported.  The time each set of
154       statistics is captured is kept with those  statistics.  The  difference
155       between  the current and previous time is converted to milliseconds for
156       use in calculations.  We can look at how this can impact the statistics
157       reported if we use an example of a tar archive being copied between two
158       tape drives using dd. If both devices reported 28900  kilobytes  trans‐
159       ferred  and the reading tape drive had an interval of 5001 milliseconds
160       and the writing tape drive 5000 milliseconds that would  calculate  out
161       as 5778 kB_read/s and 5780 kB_wrtn/s.
162
163       The  impact  of  some  retrieving  statistics during an I/O completion,
164       rounding down, and small differences in the interval period on the sta‐
165       tistics calculated should be minimal but may be non-zero.
166

ENVIRONMENT

168       The tapestat command takes into account the following environment vari‐
169       ables:
170
171
172       S_COLORS
173              When this variable is set, display statistics in  color  on  the
174              terminal.   Possible  values for this variable are never, always
175              or auto (the latter is the default).
176
177              Please note that the color (being red,  yellow,  or  some  other
178              color)  used to display a value is not indicative of any kind of
179              issue simply because of the color. It only  indicates  different
180              ranges of values.
181
182
183       S_COLORS_SGR
184              Specify  the colors and other attributes used to display statis‐
185              tics on the terminal.  Its value is a  colon-separated  list  of
186              capabilities             that             defaults            to
187              H=31;1:I=32;22:M=35;1:N=34;1:Z=34;22.   Supported   capabilities
188              are:
189
190
191              H=     SGR  (Select  Graphic Rendition) substring for percentage
192                     values greater than or equal to 75%.
193
194
195              I=     SGR substring for tape names.
196
197
198              M=     SGR substring for percentage values in the range from 50%
199                     to 75%.
200
201
202              N=     SGR substring for non-zero statistics values.
203
204
205              Z=     SGR substring for zero values.
206
207
208       S_TIME_FORMAT
209              If  this  variable  exists and its value is ISO then the current
210              locale will be ignored when printing  the  date  in  the  report
211              header. The tapestat command will use the ISO 8601 format (YYYY-
212              MM-DD) instead.  The timestamp displayed  with  option  -t  will
213              also be compliant with ISO 8601 format.
214
215

BUGS

217       /sys  filesystem must be mounted for tapestat to work. It will not work
218       on kernels that do not have sysfs support
219
220       This command requires kernel version 4.2 or later (or  tape  statistics
221       support backported for an earlier kernel version).
222
223

FILES

225       /sys/class/scsi_tape/st<num>/stats/* Statistics files for tape devices.
226
227       /proc/uptime contains system uptime.
228

AUTHOR

230       Initial revision by Shane M. SEYMOUR (shane.seymour <at> hpe.com)
231       Modified for sysstat by Sebastien Godard (sysstat <at> orange.fr)
232

SEE ALSO

234       iostat(1), mpstat(1)
235
236       http://pagesperso-orange.fr/sebastien.godard/
237
238
239
240Linux                            JANUARY 2018                      TAPESTAT(1)
Impressum