Debian Codegraph @

upstream/debian-unstable/man1/iostat.1

raw
1 .\" iostat manual page - (C) 1998-2020 Sebastien Godard (sysstat <at> orange.fr)
2 .TH IOSTAT 1 "AUGUST 2023" Linux "Linux User's Manual" -*- nroff -*-
3 .SH NAME
4 iostat \- Report Central Processing Unit (CPU) statistics and input/output
5 statistics for devices and partitions.
6
7 .SH SYNOPSIS
8 .ie 'yes'no' \{
9 .B iostat [ \-c ] [ \-d ] [ \-h ] [ \-k | \-m ] [ \-N ] [ \-s ] [ \-t ] [ \-V ] [ \-x ] [ \-y ] [ \-z ]
10 .BI "[ \-\-compact ] [ \-\-dec={ 0 | 1 | 2 } ] [ { \-f | +f } " "directory" " ] [ \-j { ID | LABEL | PATH | UUID | ... } ] "
11 .BI "[ \-o JSON ] [ [ \-H ] \-g " "group_name " "] [ \-\-human ] [ \-\-pretty ] [ \-p [ " "device" "[,...] | ALL ] ] ["
12 .IB "device " "[...] | ALL ] [ \-\-debuginfo ] [ " "interval " "[ " "count " "] ] "
13 .\}
14 .el \{
15 .B iostat [ \-c ] [ \-d ] [ \-h ] [ \-k | \-m ] [ \-N ] [ \-s ] [ \-t ] [ \-V ] [ \-x ] [ \-y ] [ \-z ]
16 .BI "[ \-\-compact ] [ \-\-dec={ 0 | 1 | 2 } ] [ { \-f | +f } " "directory" " ] [ \-j { ID | LABEL | PATH | UUID | ... } ] "
17 .BI "[ \-o JSON ] [ [ \-H ] \-g " "group_name " "] [ \-\-human ] [ \-\-pretty ] [ \-p [ " "device" "[,...] | ALL ] ] ["
18 .IB "device " "[...] | ALL ] [ " "interval " "[ " "count " "] ]"
19 .\}
20
21 .SH DESCRIPTION
22 .RB "The " "iostat"
23 command is used for monitoring system input/output device
24 loading by observing the time the devices are active in relation
25 to their average transfer rates. The
26 .B iostat
27 command generates reports
28 that can be used to change system configuration to better balance
29 the input/output load between physical disks.
30 .PP
31 The first report generated by the
32 .B iostat
33 command provides statistics
34 concerning the time since the system was booted, unless the
35 .B \-y
36 option is used (in this case, this first report is omitted).
37 Each subsequent report
38 covers the time since the previous report. All statistics are reported
39 each time the
40 .B iostat
41 command is run. The report consists of a
42 CPU header row followed by a row of
43 CPU statistics. On
44 multiprocessor systems, CPU statistics are calculated system-wide
45 as averages among all processors. A device header row is displayed
46 followed by a line of statistics for each device that is configured.
47 .PP
48 The
49 .I interval
50 parameter specifies the amount of time in seconds between
51 each report. The
52 .IR "count " "parameter can be specified in conjunction with the " "interval"
53 .RI "parameter. If the " "count " "parameter is specified, the value of " "count"
54 .RI "determines the number of reports generated at " "interval " "seconds apart. If the"
55 .IR "interval " "parameter is specified without the " "count " "parameter, the"
56 .B iostat
57 command generates reports continuously.
58
59 .SH REPORTS
60 The
61 .B iostat
62 command generates two types of reports, the CPU
63 Utilization report and the Device Utilization report.
64
65 .IP "CPU Utilization Report"
66 The first report generated by the
67 .B iostat
68 command is the CPU Utilization Report. For multiprocessor systems, the CPU values are
69 global averages among all processors.
70 The report has the following format:
71 .RS
72 .IP %user
73 Show the percentage of CPU utilization that occurred while
74 executing at the user level (application).
75 .IP %nice
76 Show the percentage of CPU utilization that occurred while
77 executing at the user level with nice priority.
78 .IP %system
79 Show the percentage of CPU utilization that occurred while
80 executing at the system level (kernel).
81 .IP %iowait
82 Show the percentage of time that the CPU or CPUs were idle during which
83 the system had an outstanding disk I/O request.
84 .IP %steal
85 Show the percentage of time spent in involuntary wait by the virtual CPU
86 or CPUs while the hypervisor was servicing another virtual processor.
87 .IP %idle
88 Show the percentage of time that the CPU or CPUs were idle and the system
89 did not have an outstanding disk I/O request.
90 .RE
91 .PP
92 .IP "Device Utilization Report"
93 The second report generated by the
94 .B iostat
95 command is the Device Utilization Report.
96 The device report provides statistics on a per physical device
97 or partition basis. Block devices and partitions for which statistics are
98 to be displayed may be entered on the command line.
99 If no device nor partition is entered, then statistics are displayed
100 for every device used by the system, and
101 providing that the kernel maintains statistics for it.
102 If the
103 .B ALL
104 keyword is given on the command line, then statistics are
105 displayed for every device defined by the system, including those
106 that have never been used.
107 Transfer rates are shown in 1K blocks by default, unless the environment
108 variable
109 .B POSIXLY_CORRECT
110 is set, in which case 512-byte blocks are used.
111 The report may show the following fields, depending on the flags used (e.g.
112 .BR "\-x" ", " "\-s " "and " "\-k " "or " "\-m" "):"
113 .RS
114 .IP Device:
115 This column gives the device (or partition) name as listed in the
116 .IR "/dev " "directory."
117 .IP tps
118 Indicate the number of transfers per second that were issued
119 to the device. A transfer is an I/O request to the
120 device. Multiple logical requests can be combined into a single I/O
121 request to the device. A transfer is of indeterminate size.
122 .IP "Blk_read/s (kB_read/s, MB_read/s)"
123 Indicate the amount of data read from the device expressed in a number of
124 blocks (kilobytes, megabytes) per second. Blocks are equivalent to sectors
125 and therefore have a size of 512 bytes.
126 .IP "Blk_wrtn/s (kB_wrtn/s, MB_wrtn/s)"
127 Indicate the amount of data written to the device expressed in a number of
128 blocks (kilobytes, megabytes) per second.
129 .IP "Blk_dscd/s (kB_dscd/s, MB_dscd/s)"
130 Indicate the amount of data discarded for the device expressed in a number of
131 blocks (kilobytes, megabytes) per second.
132 .IP "Blk_w+d/s (kB_w+d/s, MB_w+d/s)"
133 Indicate the amount of data written to or discarded for the device expressed
134 in a number of blocks (kilobytes, megabytes) per second.
135 .IP "Blk_read (kB_read, MB_read)"
136 The total number of blocks (kilobytes, megabytes) read.
137 .IP "Blk_wrtn (kB_wrtn, MB_wrtn)"
138 The total number of blocks (kilobytes, megabytes) written.
139 .IP "Blk_dscd (kB_dscd, MB_dscd)"
140 The total number of blocks (kilobytes, megabytes) discarded.
141 .IP "Blk_w+d (kB_w+d, MB_w+d)"
142 The total number of blocks (kilobytes, megabytes) written or discarded.
143 .IP r/s
144 The number (after merges) of read requests completed per second for the device.
145 .IP w/s
146 The number (after merges) of write requests completed per second for the device.
147 .IP d/s
148 The number (after merges) of discard requests completed per second for the device.
149 .IP f/s
150 The number (after merges) of flush requests completed per second for the device.
151 This counts flush requests executed by disks. Flush requests are not tracked for partitions.
152 Before being merged, flush operations are counted as writes.
153 .IP "sec/s (kB/s, MB/s)"
154 The number of sectors (kilobytes, megabytes) read from, written to or
155 discarded for the device per second.
156 .IP "rsec/s (rkB/s, rMB/s)"
157 The number of sectors (kilobytes, megabytes) read from the device per second.
158 .IP "wsec/s (wkB/s, wMB/s)"
159 The number of sectors (kilobytes, megabytes) written to the device per second.
160 .IP "dsec/s (dkB/s, dMB/s)"
161 The number of sectors (kilobytes, megabytes) discarded for the device per second.
162 .IP rqm/s
163 The number of I/O requests merged per second that were queued to the device.
164 .IP rrqm/s
165 The number of read requests merged per second that were queued to the device.
166 .IP wrqm/s
167 The number of write requests merged per second that were queued to the device.
168 .IP drqm/s
169 The number of discard requests merged per second that were queued to the device.
170 .IP %rrqm
171 The percentage of read requests merged together before being sent to the device.
172 .IP %wrqm
173 The percentage of write requests merged together before being sent to the device.
174 .IP %drqm
175 The percentage of discard requests merged together before being sent to the device.
176 .IP areq\-sz
177 The average size (in kilobytes) of the I/O requests that were issued to the device.
178 .br
179 Note: In previous versions, this field was known as avgrq\-sz and was expressed in sectors.
180 .IP rareq\-sz
181 The average size (in kilobytes) of the read requests that were issued to the device.
182 .IP wareq\-sz
183 The average size (in kilobytes) of the write requests that were issued to the device.
184 .IP dareq\-sz
185 The average size (in kilobytes) of the discard requests that were issued to the device.
186 .IP await
187 The average time (in milliseconds) for I/O requests issued to the device
188 to be served. This includes the time spent by the requests in queue and
189 the time spent servicing them.
190 .IP r_await
191 The average time (in milliseconds) for read requests issued to the device
192 to be served. This includes the time spent by the requests in queue and
193 the time spent servicing them.
194 .IP w_await
195 The average time (in milliseconds) for write requests issued to the device
196 to be served. This includes the time spent by the requests in queue and
197 the time spent servicing them.
198 .IP d_await
199 The average time (in milliseconds) for discard requests issued to the device
200 to be served. This includes the time spent by the requests in queue and
201 the time spent servicing them.
202 .IP f_await
203 The average time (in milliseconds) for flush requests issued to the device
204 to be served.
205 The block layer combines flush requests and executes at most one at a time.
206 Thus flush operations could be twice as long: Wait for current flush request,
207 then execute it, then wait for the next one.
208 .IP aqu\-sz
209 The average queue length of the requests that were issued to the device.
210 .br
211 Note: In previous versions, this field was known as avgqu\-sz.
212 .IP %util
213 Percentage of elapsed time during which I/O requests were issued to the device
214 (bandwidth utilization for the device). Device saturation occurs when this
215 value is close to 100% for devices serving requests serially.
216 But for devices serving requests in parallel, such as RAID arrays and
217 modern SSDs, this number does not reflect their performance limits.
218 .RE
219
220 .SH OPTIONS
221 .TP
222 .B \-c
223 Display the CPU utilization report.
224 .TP
225 .B \-\-compact
226 Don't break the Device Utilization Report into sub-reports so that all the metrics get displayed
227 on a single line.
228 .TP
229 .B \-d
230 Display the device utilization report.
231 .if 'yes'no' \{
232 .TP
233 .B \-\-debuginfo
234 Print debug output to stderr.
235 .\}
236 .TP
237 .B \-\-dec={ 0 | 1 | 2 }
238 Specify the number of decimal places to use (0 to 2, default value is 2).
239 .TP
240 .BI "\-f " "directory"
241 .RE
242 .BI "+f " "directory"
243 .RS
244 Specify an alternative directory for
245 .B iostat
246 to read devices statistics. Option
247 .BR "\-f " "tells " "iostat " "to use only the files located in the alternative directory, "
248 whereas option
249 .B +f
250 tells it to use both the standard kernel files and the files located in the alternative directory
251 to read device statistics.
252
253 .IR "directory" " is a directory containing files with statistics for devices managed in userspace."
254 It may contain:
255
256 - a "diskstats" file whose format is compliant with that located in "/proc",
257 .br
258 - statistics for individual devices contained in files whose format is compliant with that of files located in
259 "/sys".
260
261 In particular, the following files located in
262 .I "directory"
263 .RB "may be used by " "iostat" ":"
264
265 .IR "directory" "/block/" "device" "/stat"
266 .br
267 .IR "directory" "/block/" "device" "/" "partition" "/stat"
268
269 .IR "partition" " files must have an entry in " "directory" "/dev/block/ directory, e.g.:"
270
271 .IR "directory" "/dev/block/" "major" ":" "minor" " --> ../../block/" "device" "/" "partition"
272 .RE
273 .TP
274 .BI "\-g " "group_name " "{ " "device " "[...] | ALL }"
275 Display statistics for a group of devices.
276 The
277 .B iostat
278 command reports statistics for each individual device in the list
279 then a line of global statistics for the group displayed as
280 .I group_name
281 and made up of all the devices in the list. The
282 .B ALL
283 keyword means that all the block devices defined by the system shall be
284 included in the group.
285 .TP
286 .B \-H
287 This option must be used with option
288 .B \-g
289 and indicates that only global
290 statistics for the group are to be displayed, and not statistics for
291 individual devices in the group.
292 .TP
293 .B \-h
294 This option is equivalent to specifying
295 .BR "\-\-human \-\-pretty" "."
296 .TP
297 .B \-\-human
298 Print sizes in human readable format (e.g. 1.0k, 1.2M, etc.)
299 The units displayed with this option supersede any other default units (e.g.
300 kilobytes, sectors...) associated with the metrics.
301 .TP
302 .BI "\-j { ID | LABEL | PATH | UUID | ... } [ " "device " "[...] | ALL ]"
303 Display persistent device names. Keywords
304 .BR "ID" ", " "LABEL" ", "
305 etc. specify the type of the persistent name. These keywords are not limited,
306 only prerequisite is that directory with required persistent names is present in
307 .IR "/dev/disk" "."
308 Optionally, multiple devices can be specified in the chosen persistent name type.
309 Because persistent device names are usually long, option
310 .B \-\-pretty
311 is implicitly set with this option.
312 .TP
313 .B \-k
314 Display statistics in kilobytes per second.
315 .TP
316 .B \-m
317 Display statistics in megabytes per second.
318 .TP
319 .B \-N
320 Display the registered device mapper names for any device mapper devices.
321 Useful for viewing LVM2 statistics.
322 .TP
323 .B \-o JSON
324 Display the statistics in JSON (JavaScript Object Notation) format.
325 JSON output field order is undefined, and new fields may be added
326 in the future.
327 .TP
328 .BI "\-p [ { " "device" "[,...] | ALL } ]"
329 Display statistics for
330 block devices and all their partitions that are used by the system.
331 If a device name is entered on the command line, then statistics for it
332 and all its partitions are displayed. Last, the
333 .B ALL
334 keyword indicates that statistics have to be displayed for all the block
335 devices and partitions defined by the system, including those that have
336 never been used. If option
337 .B \-j
338 is defined before this option, devices entered on the command line can be
339 specified with the chosen persistent name type.
340 .TP
341 .B \-\-pretty
342 Make the Device Utilization Report easier to read by a human.
343 The device name will be printed on the right side. The report may also be broken
344 into sub-reports if there are many metrics to display (use
345 .B \-\-compact
346 option to prevent this).
347 .TP
348 .B \-s
349 Display a short (narrow) version of the report that should fit in 80
350 characters wide screens.
351 .TP
352 .B \-t
353 Print the time for each report displayed. The timestamp format may depend
354 on the value of the
355 .BR "S_TIME_FORMAT " "environment variable (see below)."
356 .TP
357 .B \-V
358 Print version number then exit.
359 .TP
360 .B \-x
361 Display extended statistics.
362 .TP
363 .B \-y
364 Omit first report with statistics since system boot, if displaying
365 multiple records at given interval.
366 .TP
367 .B \-z
368 Tell
369 .B iostat
370 to omit output for any devices for which there was no activity
371 during the sample period.
372
373 .SH ENVIRONMENT
374 The
375 .B iostat
376 command takes into account the following environment variables:
377 .TP
378 .B POSIXLY_CORRECT
379 When this variable is set, transfer rates are shown in 512-byte blocks instead
380 of the default 1K blocks.
381 .TP
382 .B S_COLORS
383 By default statistics are displayed in color when the output is connected to a terminal.
384 Use this variable to change the settings. Possible values for this variable are
385 .IR "never" ", " "always " "or " "auto"
386 (the latter is equivalent to the default settings).
387 .br
388 Please note that the color (being red, yellow, or some other color) used to display a value
389 is not indicative of any kind of issue simply because of the color. It only indicates different
390 ranges of values.
391 .TP
392 .B S_COLORS_SGR
393 Specify the colors and other attributes used to display statistics on the terminal.
394 Its value is a colon-separated list of capabilities that defaults to
395 .BR "I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22" "."
396 Supported capabilities are:
397 .RS
398 .TP
399 .B I=
400 SGR (Select Graphic Rendition) substring for device names.
401 .TP
402 .B N=
403 SGR substring for non-zero statistics values.
404 .TP
405 .BR "W=" " (or " "M=" ")"
406 SGR substring for percentage values in the range from 75% to 90% (or in the range 10% to 25% depending on the
407 metric's meaning).
408 .TP
409 .BR "X=" " (or " "H=" ")"
410 SGR substring for percentage values greater than or equal to 90% (or lower than or equal to 10% depending on the
411 metric's meaning).
412 .TP
413 .B Z=
414 SGR substring for zero values.
415 .RE
416 .TP
417 .B S_TIME_FORMAT
418 If this variable exists and its value is
419 .B ISO
420 then the current locale will be ignored when printing the date in the report
421 header. The
422 .B iostat
423 command will use the ISO 8601 format (YYYY-MM-DD) instead.
424 The timestamp displayed with option
425 .B \-t
426 will also be compliant with ISO 8601 format.
427
428 .SH EXAMPLES
429 .TP
430 .B iostat
431 Display a single history since boot report for all CPU and Devices.
432 .TP
433 .B iostat \-d 2
434 Display a continuous device report at two second intervals.
435 .TP
436 .B iostat \-d 2 6
437 Display six reports at two second intervals for all devices.
438 .TP
439 .B iostat \-x sda sdb 2 6
440 Display six reports of extended statistics at two second intervals for devices
441 sda and sdb.
442 .TP
443 .B iostat \-p sda 2 6
444 Display six reports at two second intervals for device sda and all its
445 partitions (sda1, etc.)
446
447 .SH BUGS
448 .IR "/proc " "filesystem must be mounted for"
449 .BR "iostat " "to work."
450 .PP
451 Kernels older than 2.6.x are no longer supported.
452 .PP
453 .RB "Although " "iostat"
454 speaks of kilobytes (kB), megabytes (MB)..., it actually uses kibibytes (kiB), mebibytes (MiB)...
455 A kibibyte is equal to 1024 bytes, and a mebibyte is equal to 1024 kibibytes.
456
457 .SH FILES
458 .IR "/proc/stat " "contains system statistics."
459 .br
460 .IR "/proc/uptime " "contains system uptime."
461 .br
462 .IR "/proc/diskstats " "contains disks statistics."
463 .br
464 .IR "/sys " "contains statistics for block devices."
465 .br
466 .IR "/proc/self/mountstats " "contains statistics for network filesystems."
467 .br
468 .IR "/dev/disk " "contains persistent device names."
469
470 .SH AUTHOR
471 Sebastien Godard (sysstat <at> orange.fr)
472
473 .SH SEE ALSO
474 .BR "sar" "(1), " "pidstat" "(1), " "mpstat" "(1), " "vmstat" "(8), " "tapestat" "(1), " "nfsiostat" "(1),"
475 .BR "cifsiostat" "(1)"
476 .PP
477 .I https://github.com/sysstat/sysstat
478 .br
479 .I https://sysstat.github.io/