manual/sysstat/original/man1/iostat.1

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