Debian Codegraph @

upstream/fedora-44/man1/tapestat.1

raw
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 "JULY 2025" Linux "Linux User's Manual" -*- nroff -*-
4 .SH NAME
5 tapestat \- Report tape statistics.
6
7 .SH SYNOPSIS
8 .B tapestat [ \-k | \-m ] [ \-t ] [ \-U ] [ \-V ] [ \-y ] [ \-z ] [ \-\-human ] [ \-o JSON ] [
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 kibibytes (by default or if option
43 .BR "\-k " "used) or mebibytes (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 kibibytes (by default or if option
47 .BR "\-k " "used) or mebibytes (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 kibibytes, sectors...) associated with the metrics.
77 .TP
78 .B \-k
79 Show the amount of data written or read in kibibytes per second instead of mebibytes.
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 mebibytes per second instead of kibibytes.
85 This option is mutually exclusive with
86 .BR "\-k" "."
87 .TP
88 .B \-o JSON
89 Display the statistics in JSON (JavaScript Object Notation) format.
90 JSON output field order is undefined, and new fields may be added
91 in the future.
92 .TP
93 .B \-t
94 Display time stamps. The time stamp format may depend
95 on the value of the
96 .BR "S_TIME_FORMAT " "environment variable (see below) and on whether option -U has been used."
97 .TP
98 .B \-U
99 Display timestamp (UTC - Coordinated Universal Time) in seconds from the epoch.
100 .TP
101 .B \-V
102 Print version and exit.
103 .TP
104 .B \-y
105 Omit the initial statistic showing values since boot.
106 .TP
107 .B \-z
108 .RB "Tell " "tapestat"
109 to omit output for any tapes for which there was no activity
110 during the sample period.
111
112 .SH CONSIDERATIONS
113 It is possible for a percentage value (read, write, or other) to be greater than 100 percent (the
114 .B tapestat
115 command will never show a percentage value more than 999).
116 If rewinding a tape takes 40 seconds where the interval time is 5 seconds the %Oa value
117 would show as 0 in the intervals before the rewind completed and then show as approximately
118 800 percent when the rewind completes.
119
120 Similar values will be observed for %Rd and %Wr if a tape drive stops reading or writing
121 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
122 (depending on how long it takes to restart writing or reading).
123 This is only an issue if it happens a lot as it may cause tape wear and will impact
124 on the backup times.
125
126 For fast tape drives you may see low percentage wait times.
127 This does not indicate an issue with the tape drive. For a slower tape drive (e.g. an older
128 generation DDS drive) the speed of the tape (and tape drive) is much slower than filesystem I/O,
129 percent wait times are likely to be higher. For faster tape drives (e.g. LTO) the percentage
130 wait times are likely to be lower as program writing to or reading from tape is going
131 to be doing a lot more filesystem I/O because of the higher throughput.
132
133 Although tape statistics are implemented in the kernel using atomic variables they cannot be
134 read atomically as a group. All of the statistics values are read from different files under
135 .IR "/sys" ","
136 because of this there may be I/O completions while reading the different files for the
137 one tape drive. This may result in a set of statistics for a device that contain some values
138 before an I/O completed and some after.
139
140 This command uses rounding down as the rounding method when calculating per second statistics.
141 If, for example, you are using
142 .BR "dd " "to copy one tape to another and running " "tapestat"
143 with an interval of 5 seconds and over the interval there were 3210 writes and 3209 reads
144 then w/s would show 642 and r/s 641 (641.8 rounded down to 641). In such a case if it was
145 a tar archive being copied (with a 10k block size) you would also see a difference between
146 the kB_read/s and kB_wrtn/s of 2 (one I/O 10k in size divided by the interval period of 5
147 seconds). If instead there were 3210 writes and 3211 reads both w/s and r/s would both show
148 642 but you would still see a difference between the kB_read/s and kB_wrtn/s values of 2 kB/s.
149
150 This command is provided with an interval in seconds. However internally the interval is
151 tracked per device and can potentially have an effect on the per second statistics reported.
152 The time each set of statistics is captured is kept with those statistics. The difference
153 between the current and previous time is converted to milliseconds for use in calculations.
154 We can look at how this can impact the statistics reported if we use an example of a tar
155 archive being copied between two tape drives using
156 .BR "dd" "."
157 If both devices reported 28900 kibibytes
158 transferred and the reading tape drive had an interval of 5001 milliseconds and the writing
159 tape drive 5000 milliseconds that would calculate out as 5778 kB_read/s and 5780 kB_wrtn/s.
160
161 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.
162
163 .SH ENVIRONMENT
164 .RB "The " "tapestat"
165 command takes into account the following environment variables:
166 .TP
167 .B S_COLORS
168 By default statistics are displayed in color when the output is connected to a terminal.
169 Use this variable to change the settings. Possible values for this variable are
170 .IR "never" ", " "always " "or " "auto"
171 (the latter is equivalent to the default settings).
172 .br
173 Please note that the color (being red, yellow, or some other color) used to display a value
174 is not indicative of any kind of issue simply because of the color. It only indicates different
175 ranges of values.
176 .TP
177 .B S_COLORS_SGR
178 Specify the colors and other attributes used to display statistics on the terminal.
179 Its value is a colon-separated list of capabilities that defaults to
180 .BR "I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22" "."
181 Supported capabilities are:
182 .RS
183 .TP
184 .B I=
185 SGR (Select Graphic Rendition) substring for tape names.
186 .TP
187 .B N=
188 SGR substring for non-zero statistics values.
189 .TP
190 .BR "W=" " (or " "M=" ")"
191 SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the
192 metric's meaning).
193 .TP
194 .BR "X=" " (or " "H=" ")"
195 SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the
196 metric's meaning).
197 .TP
198 .B Z=
199 SGR substring for zero values.
200 .RE
201 .TP
202 .B S_TIME_FORMAT
203 If this variable exists and its value is
204 .BR ISO
205 then the current locale will be ignored when printing the date in the report
206 header. The
207 .B tapestat
208 command will use the ISO 8601 format (YYYY-MM-DD) instead.
209 The timestamp displayed with option
210 .B \-t
211 will also be compliant with ISO 8601 format.
212
213 .SH BUGS
214 .IR "/sys " "filesystem must be mounted for"
215 .B tapestat
216 to work. It will not work on kernels that do not have sysfs support
217 .PP
218 This command requires kernel version 4.2 or later
219 (or tape statistics support backported for an earlier kernel version).
220 .PP
221 .RB "Although " "tapestat"
222 displays units corresponding to kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)...
223 A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes.
224
225 .SH FILES
226 .I /sys/class/scsi_tape/st<num>/stats/*
227 .RS
228 Statistics files for tape devices.
229 .RE
230 .PP
231 .IR "/proc/uptime " "contains system uptime."
232
233 .SH AUTHOR
234 Initial revision by Shane M. SEYMOUR (shane.seymour <at> hpe.com)
235 .br
236 Modified for sysstat by Sebastien Godard (sysstat <at> orange.fr)
237
238 .SH SEE ALSO
239 .BR "iostat" "(1), " "mpstat" "(1)"
240 .PP
241 .I https://github.com/sysstat/sysstat
242 .br
243 .I https://sysstat.github.io/