1 '\" te
   2 .\"
   3 .\" CDDL HEADER START
   4 .\"
   5 .\" The contents of this file are subject to the terms of the
   6 .\" Common Development and Distribution License (the "License").
   7 .\" You may not use this file except in compliance with the License.
   8 .\"
   9 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  10 .\" or http://www.opensolaris.org/os/licensing.
  11 .\" See the License for the specific language governing permissions
  12 .\" and limitations under the License.
  13 .\"
  14 .\" When distributing Covered Code, include this CDDL HEADER in each
  15 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  16 .\" If applicable, add the following below this CDDL HEADER, with the
  17 .\" fields enclosed by brackets "[]" replaced with your own identifying
  18 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  19 .\"
  20 .\" CDDL HEADER END
  21 .\"
  22 .\" Copyright (c) 2003, Sun Microsystems, Inc.  All Rights reserved
  23 .\" Copyright (c) 2012 by Delphix. All rights reserved.
  24 .\"
  25 .TH IOSTAT 1M "Mar 23, 2009"
  26 .SH NAME
  27 iostat \- report I/O statistics
  28 .SH SYNOPSIS
  29 .LP
  30 .nf
  31 \fB/usr/bin/iostat\fR  [\fB-cCdDeEiImMnpPrstxXYz\fR] [\fB-l\fR \fIn\fR] [\fB-T\fR u | d]
  32  [\fIdisk\fR]... [\fIinterval\fR [\fIcount\fR]]
  33 .fi
  34 
  35 .SH DESCRIPTION
  36 .sp
  37 .LP
  38 The \fBiostat\fR utility iteratively reports terminal, disk, and tape \fBI/O\fR
  39 activity, as well as \fBCPU\fR utilization. The first line of output is for all
  40 time since boot; each subsequent line is for the prior interval only.
  41 .sp
  42 .LP
  43 To compute this information, the kernel maintains a number of counters. For
  44 each disk, the kernel counts reads, writes, bytes read, and bytes written. The
  45 kernel also takes hi-res time stamps at queue entry and exit points, which
  46 allows it to keep track of the residence time and cumulative residence-length
  47 product for each queue. Using these values, \fBiostat\fR produces highly
  48 accurate measures of throughput, utilization, queue lengths, transaction rates
  49 and service time. For terminals collectively, the kernel simply counts the
  50 number of input and output characters.
  51 .sp
  52 .LP
  53 During execution of the kernel status command, the \fBstate\fR of the system
  54 can change. If relevant, a state change message is included in the \fBiostat\fR
  55 output, in one of the following forms:
  56 .sp
  57 .in +2
  58 .nf
  59 <<device added: sd0>>
  60 <<device removed: sd0>>
  61 <<partition added: sd0,a>>
  62 <<partition removed: sd0,a>>
  63 <<NFS mounted: nfs1>>
  64 <<NFS unmounted: nfs1>>
  65 <<multi-path added: ssd4>>
  66 <<multi-path removed: ssd4>>
  67 <<controller added: c1>>
  68 <<controller removed: c1>>
  69 <<processors added: 1, 3>>
  70 <<processors removed: 1, 3>>
  71 .fi
  72 .in -2
  73 .sp
  74 
  75 .sp
  76 .LP
  77 Note that the \fBnames\fR printed in these state change messages are affected
  78 by the \fB-n\fR and \fB-m\fR options as appropriate.
  79 .sp
  80 .LP
  81 For more general system statistics, use \fBsar\fR(1), \fBsar\fR(1M), or
  82 \fBvmstat\fR(1M).
  83 .SS "Output"
  84 .sp
  85 .LP
  86 The output of the \fBiostat\fR utility includes the following information.
  87 .sp
  88 .ne 2
  89 .na
  90 \fB\fBdevice\fR\fR
  91 .ad
  92 .RS 10n
  93 name of the disk
  94 .RE
  95 
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fBr/s\fR\fR
 100 .ad
 101 .RS 10n
 102 reads per second
 103 .RE
 104 
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fBw/s\fR\fR
 109 .ad
 110 .RS 10n
 111 writes per second
 112 .RE
 113 
 114 .sp
 115 .ne 2
 116 .na
 117 \fB\fBkr/s\fR\fR
 118 .ad
 119 .RS 10n
 120 kilobytes read per second
 121 .sp
 122 The average I/O size during the interval can be computed from \fBkr/s\fR
 123 divided by \fBr/s\fR.
 124 .RE
 125 
 126 .sp
 127 .ne 2
 128 .na
 129 \fB\fBkw/s\fR\fR
 130 .ad
 131 .RS 10n
 132 kilobytes written per second
 133 .sp
 134 The average I/O size during the interval can be computed from \fBkw/s\fR
 135 divided by \fBw/s\fR.
 136 .RE
 137 
 138 .sp
 139 .ne 2
 140 .na
 141 \fB\fBwait\fR\fR
 142 .ad
 143 .RS 10n
 144 average number of transactions waiting for service (queue length)
 145 .sp
 146 This is the number of I/O operations held in the device driver queue waiting
 147 for acceptance by the device.
 148 .RE
 149 
 150 .sp
 151 .ne 2
 152 .na
 153 \fB\fBactv\fR\fR
 154 .ad
 155 .RS 10n
 156 average number of transactions actively being serviced (removed from the queue
 157 but not yet completed)
 158 .sp
 159 This is the number of I/O operations accepted, but not yet serviced, by the
 160 device.
 161 .RE
 162 
 163 .sp
 164 .ne 2
 165 .na
 166 \fB\fBsvc_t\fR\fR
 167 .ad
 168 .RS 10n
 169 average response time of transactions, in milliseconds
 170 .sp
 171 The \fBsvc_t\fR output reports the overall \fBresponse\fR time, rather than the
 172 \fBservice\fR time, of a device. The overall time includes the time that
 173 transactions are in queue and the time that transactions are being serviced.
 174 The time spent in queue is shown with the \fB-x\fR option in the \fBwsvc_t\fR
 175 output column. The time spent servicing transactions is the true service time.
 176 Service time is also shown with the \fB-x\fR option and appears in the
 177 \fBasvc_t\fR output column of the same report.
 178 .RE
 179 
 180 .sp
 181 .ne 2
 182 .na
 183 \fB\fB%w\fR\fR
 184 .ad
 185 .RS 10n
 186 percent of time there are transactions waiting for service (queue non-empty)
 187 .RE
 188 
 189 .sp
 190 .ne 2
 191 .na
 192 \fB\fB%b\fR\fR
 193 .ad
 194 .RS 10n
 195 percent of time the disk is busy (transactions in progress)
 196 .RE
 197 
 198 .sp
 199 .ne 2
 200 .na
 201 \fB\fBwsvc_t\fR\fR
 202 .ad
 203 .RS 10n
 204 average service time in wait queue, in milliseconds
 205 .RE
 206 
 207 .sp
 208 .ne 2
 209 .na
 210 \fB\fBasvc_t\fR\fR
 211 .ad
 212 .RS 10n
 213 average service time of active transactions, in milliseconds
 214 .RE
 215 
 216 .SH OPTIONS
 217 .sp
 218 .LP
 219 The following options are supported:
 220 .sp
 221 .ne 2
 222 .na
 223 \fB\fB-c\fR\fR
 224 .ad
 225 .RS 12n
 226 Report the percentage of time the system has spent in user mode, in system
 227 mode, in dtrace probes, and idling. See the NOTES section and
 228 \fBmpstat\fR(1m) for more information.
 229 .RE
 230 
 231 .sp
 232 .ne 2
 233 .na
 234 \fB\fB-C\fR\fR
 235 .ad
 236 .RS 12n
 237 When the \fB-x\fR option is also selected, report extended disk statistics
 238 aggregated by \fIcontroller id\fR.
 239 .RE
 240 
 241 .sp
 242 .ne 2
 243 .na
 244 \fB\fB-d\fR\fR
 245 .ad
 246 .RS 12n
 247 For each disk, report the number of kilobytes transferred per second, the
 248 number of transfers per second, and the average service time in milliseconds.
 249 .RE
 250 
 251 .sp
 252 .ne 2
 253 .na
 254 \fB\fB-D\fR\fR
 255 .ad
 256 .RS 12n
 257 For each disk, report the reads per second, writes per second, and percentage
 258 disk utilization.
 259 .RE
 260 
 261 .sp
 262 .ne 2
 263 .na
 264 \fB\fB-e\fR\fR
 265 .ad
 266 .RS 12n
 267 Display device error summary statistics. The total errors, hard errors, soft
 268 errors, and transport errors are displayed.
 269 .RE
 270 
 271 .sp
 272 .ne 2
 273 .na
 274 \fB\fB-E\fR\fR
 275 .ad
 276 .RS 12n
 277 Display all device error statistics.
 278 .RE
 279 
 280 .sp
 281 .ne 2
 282 .na
 283 \fB\fB-i\fR\fR
 284 .ad
 285 .RS 12n
 286 In \fB-E\fR output, display the \fBDevice ID\fR instead of the \fBSerial No\fR.
 287 The \fBDevice Id\fR is a unique identifier registered by a driver through
 288 \fBddi_devid_register\fR(9F).
 289 .RE
 290 
 291 .sp
 292 .ne 2
 293 .na
 294 \fB\fB-I\fR\fR
 295 .ad
 296 .RS 12n
 297 Report the counts in each interval, rather than rates (where applicable).
 298 .RE
 299 
 300 .sp
 301 .ne 2
 302 .na
 303 \fB\fB-l\fR \fIn\fR\fR
 304 .ad
 305 .RS 12n
 306 Limit the number of disks included in the report to \fIn\fR; the disk limit
 307 defaults to 4 for \fB-d\fR and \fB-D\fR, and unlimited for \fB-x\fR. Note:
 308 disks explicitly requested (see \fIdisk\fR below) are not subject to this disk
 309 limit.
 310 .RE
 311 
 312 .sp
 313 .ne 2
 314 .na
 315 \fB\fB-m\fR\fR
 316 .ad
 317 .RS 12n
 318 Report file system mount points. This option is most useful if the \fB-P\fR or
 319 \fB-p\fR option is also specified or used in conjunction with \fB-Xn\fR or
 320 \fB-en\fR. The \fB-m\fR option is useful only if the mount point is actually
 321 listed in the output. This option can only be used in conjunction with the
 322 \fB-n\fR option.
 323 .RE
 324 
 325 .sp
 326 .ne 2
 327 .na
 328 \fB\fB-M\fR\fR
 329 .ad
 330 .RS 12n
 331 Display data throughput in \fBMB\fR/sec instead of KB/sec.
 332 .RE
 333 
 334 .sp
 335 .ne 2
 336 .na
 337 \fB\fB-n\fR\fR
 338 .ad
 339 .RS 12n
 340 Display names in descriptive format. For example, \fBcXtYdZ\fR, \fBrmt/N\fR,
 341 \fBserver:/export/path\fR.
 342 .sp
 343 By default, disks are identified by instance names such as \fBssd23\fR or
 344 \fBmd301\fR. Combining the \fB-n\fR option with the \fB-x\fR option causes disk
 345 names to display in the \fBcXtYdZsN\fR format which is more easily associated
 346 with physical hardware characteristics. The \fBcXtYdZsN\fR format is
 347 particularly useful in FibreChannel (FC) environments where the FC World Wide
 348 Name appears in the \fBt\fR field.
 349 .RE
 350 
 351 .sp
 352 .ne 2
 353 .na
 354 \fB\fB-p\fR\fR
 355 .ad
 356 .RS 12n
 357 For each disk, report per-partition statistics in addition to per-device
 358 statistics.
 359 .RE
 360 
 361 .sp
 362 .ne 2
 363 .na
 364 \fB\fB-P\fR\fR
 365 .ad
 366 .RS 12n
 367 For each disk, report per-partition statistics only, no per-device statistics.
 368 .RE
 369 
 370 .sp
 371 .ne 2
 372 .na
 373 \fB\fB-r\fR\fR
 374 .ad
 375 .RS 12n
 376 Display data in a comma-separated format.
 377 .RE
 378 
 379 .sp
 380 .ne 2
 381 .na
 382 \fB\fB-s\fR\fR
 383 .ad
 384 .RS 12n
 385 Suppress messages related to \fBstate changes\fR.
 386 .RE
 387 
 388 .sp
 389 .ne 2
 390 .na
 391 \fB\fB-t\fR\fR
 392 .ad
 393 .RS 12n
 394 Report the number of characters read and written to terminals per second.
 395 .RE
 396 
 397 .sp
 398 .ne 2
 399 .na
 400 \fB\fB-T\fR u | d\fR
 401 .ad
 402 .RS 12n
 403 Display a time stamp.
 404 .sp
 405 Specify \fBu\fR for a printed representation of the internal representation of
 406 time. See \fBtime\fR(2). Specify \fBd\fR for standard date format. See
 407 \fBdate\fR(1).
 408 .RE
 409 
 410 .sp
 411 .ne 2
 412 .na
 413 \fB\fB-X\fR\fR
 414 .ad
 415 .RS 12n
 416 For disks under \fBscsi_vhci\fR(7D) control, in addition to disk \fIlun\fR
 417 statistics, also report statistics for \fIlun\fR.\fIcontroller\fR.
 418 .RE
 419 
 420 .sp
 421 .ne 2
 422 .na
 423 \fB\fB-x\fR\fR
 424 .ad
 425 .RS 12n
 426 Report extended disk statistics. By default, disks are identified by instance
 427 names such as \fBssd23\fR or \fBmd301\fR. Combining the \fBx\fR option with the
 428 \fB-n\fR option causes disk names to display in the \fBcXtYdZsN\fR format, more
 429 easily associated with physical hardware characteristics. Using the
 430 \fBcXtYdZsN\fR format is particularly helpful in the FibreChannel environments
 431 where the FC World Wide Name appears in the \fBt\fR field.
 432 .sp
 433 If no output display is requested (no \fB-x\fR, \fB-e\fR, \fB-E\fR), \fB-x\fR
 434 is implied.
 435 .RE
 436 
 437 .sp
 438 .ne 2
 439 .na
 440 \fB\fB-Y\fR\fR
 441 .ad
 442 .RS 12n
 443 For disks under \fBscsi_vhci\fR(7D) control, in addition to disk \fIlun\fR
 444 statistics, also report statistics for \fIlun\fR.\fItargetport\fR and
 445 \fIlun\fR.\fItargetport\fR.\fIcontroller\fR.
 446 .sp
 447 In \fB-n\fR (descriptive) mode the \fItargetport\fR is shown in using the
 448 \fBtarget-port\fR property of the path. Without \fB-n\fR the \fItargetport\fR
 449 is shown using the shorter \fBport-id\fR. All target ports with the same
 450 \fBtarget-port\fR property value share the same \fBport-id\fR. The
 451 \fBtarget-port\fR-to-\fBport-id\fR association does not persist across reboot.
 452 .sp
 453 If no output display is requested (no \fB-x\fR, \fB-e\fR, \fB-E\fR), \fB-x\fR
 454 is implied.
 455 .RE
 456 
 457 .sp
 458 .ne 2
 459 .na
 460 \fB\fB-z\fR\fR
 461 .ad
 462 .RS 12n
 463 Do not print lines whose underlying data values are all zeros.
 464 .RE
 465 
 466 .sp
 467 .LP
 468 The option set \fB-xcnCXTdz\fR \fIinterval\fR is particularly useful for
 469 determining whether disk I/O problems exist and for identifying problems.
 470 .SH OPERANDS
 471 .sp
 472 .LP
 473 The following operands are supported:
 474 .sp
 475 .ne 2
 476 .na
 477 \fB\fIcount\fR\fR
 478 .ad
 479 .RS 12n
 480 Display only \fIcount\fR reports.
 481 .RE
 482 
 483 .sp
 484 .ne 2
 485 .na
 486 \fB\fIdisk\fR\fR
 487 .ad
 488 .RS 12n
 489 Explicitly specify the disks to be reported; in addition to any explicit disks,
 490 any active disks up to the disk limit (see \fB-l\fR above) will also be
 491 reported.
 492 .RE
 493 
 494 .sp
 495 .ne 2
 496 .na
 497 \fB\fIinterval\fR\fR
 498 .ad
 499 .RS 12n
 500 Report once each \fIinterval\fR seconds.
 501 .RE
 502 
 503 .SH EXAMPLES
 504 .LP
 505 \fBExample 1 \fRUsing \fBiostat\fR to Generate User and System Operation
 506 Statistics
 507 .sp
 508 .LP
 509 The following command displays two reports of extended device statistics,
 510 aggregated by \fIcontroller id\fR, for user (\fBus\fR) and system (\fBsy\fR)
 511 operations. Because the \fB-n\fR option is used with the \fB-x\fR option,
 512 devices are identified by controller names.
 513 
 514 .sp
 515 .in +2
 516 .nf
 517 example% \fBiostat\fR \fB-xcnCXTdz\fR \fB5\fR
 518 
 519 
 520 Mon Nov 24 14:58:36 2003
 521     cpu
 522  us sy dt id
 523  14 31  0 20
 524                     extended device statistics
 525   r/s    w/s    kr/s      kw wait  actv wsvc_t asvc_t  %w  %b device
 526   3.8   29.9   145.8    44.0  0.0   0.2    0.1    6.4   0   5     c0
 527 666.3  814.8 12577.6 17591.1 91.3  82.3   61.6   55.6   0   2    c12
 528 180.0  234.6  4401.1  5712.6  0.0 147.7    0.0  356.3   0  98    d10
 529 
 530 Mon Nov 24 14:58:41 2003
 531     cpu
 532  us sy dt id
 533  11 31  1 22
 534                     extended device statistics
 535   r/s    w/s    kr/s      kw wait  actv wsvc_t asvc_t  %w  %b device
 536   0.8   41.0     5.2    20.5 0.0    0.2    0.2    4.4   0   6     c0
 537 565.3  581.7  8573.2 10458.9 0.0   26.6    0.0   23.2   0   3    c12
 538 106.5   81.3  3393.2  1948.6 0.0    5.7    0.0   30.1   0  99    d10
 539 .fi
 540 .in -2
 541 .sp
 542 
 543 .LP
 544 \fBExample 2 \fRUsing \fBiostat\fR to Generate TTY Statistics
 545 .sp
 546 .LP
 547 The following command displays two reports on the activity of five disks in
 548 different modes of operation. Because the \fB-x\fR option is used, disks are
 549 identified by instance names.
 550 
 551 .sp
 552 .in +2
 553 .nf
 554 example% \fBiostat\fR \fB-x\fR \fBtc 5 2\fR
 555 
 556 
 557                   extended device statistics        tty         cpu
 558 device r/s  w/s kr/s  kw/s wait actv svc_t %w  %b  tin tout  us sy dt id
 559 sd0    0.4  0.3 10.4   8.0  0.0  0.0  36.9  0   1    0   10   0  0  0 99
 560 sd1    0.0  0.0  0.3   0.4  0.0  0.0  35.0  0   0
 561 sd6    0.0  0.0  0.0   0.0  0.0  0.0   0.0  0   0
 562 nfs1   0.0  0.0  0.0   0.0  0.0  0.0   0.0  0   0
 563 nfs2   0.0  0.0  0.0   0.1  0.0  0.0  35.6  0   0
 564             extended device statistics              tty         cpu
 565 device r/s  w/s  kr/s  kw/s wait actv svc_t %w  %b tin tout  us sy dt id
 566 sd0    0.0  0.0  0.0   0.0  0.0  0.0  0.0   0   0   0  155   0  0  0 100
 567 sd1    0.0  0.0  0.0   0.0  0.0  0.0  0.0   0   0
 568 sd6    0.0  0.0  0.0   0.0  0.0  0.0  0.0   0   0
 569 nfs1   0.0  0.0  0.0   0.0  0.0  0.0  0.0   0   0
 570 nfs2   0.0  0.0  0.0   0.0  0.0  0.0  0.0   0   0
 571 
 572 .fi
 573 .in -2
 574 .sp
 575 
 576 .LP
 577 \fBExample 3 \fRUsing \fBiostat\fR to Generate Partition and Device Statistics
 578 .sp
 579 .LP
 580 The following command generates partition and device statistics for each disk.
 581 Because the \fB-n\fR option is used with the \fB-x\fR option, disks are
 582 identified by controller names.
 583 
 584 .sp
 585 .in +2
 586 .nf
 587 example% \fBiostat -xnp\fR
 588 
 589                 extended device statistics
 590 r/s  w/s  kr/s kw/s wait actv wsvc_t asvc_t %w %b device
 591 0.4  0.3  10.4  7.9  0.0  0.0    0.0   36.9  0  1 c0t0d0
 592 0.3  0.3   9.0  7.3  0.0  0.0    0.0   37.2  0  1 c0t0d0s0
 593 0.0  0.0   0.1  0.5  0.0  0.0    0.0   34.0  0  0 c0t0d0s1
 594 0.0  0.0   0.0  0.1  0.0  0.0    0.6   35.0  0  0 fuji:/export/home/user3
 595 .fi
 596 .in -2
 597 .sp
 598 
 599 .LP
 600 \fBExample 4 \fRShow Translation from Instance Name to Descriptive Name
 601 .sp
 602 .LP
 603 The following example illustrates the use of \fBiostat\fR to translate a
 604 specific instance name to a descriptive name.
 605 
 606 .sp
 607 .in +2
 608 .nf
 609 example% \fBiostat -xn sd1\fR
 610                         extended device statistics
 611 r/s    w/s   kr/s   kw/s wait actv wsvc_t asvc_t  %w  %b device
 612 0.0    0.0    0.0    0.0  0.0  0.0    0.0    0.0   0   0 c8t1d0
 613 .fi
 614 .in -2
 615 .sp
 616 
 617 .LP
 618 \fBExample 5 \fRShow Target Port and Controller Activity for a Specific Disk
 619 .sp
 620 .LP
 621 In the following example, there are four controllers, all connected to the same
 622 target port.
 623 
 624 .sp
 625 .in +2
 626 .nf
 627 # \fBiostat -Y ssd22\fR
 628                     extended device statistics
 629 device          r/s    w/s   kr/s   kw/s wait actv  svc_t  %w  %b
 630 ssd22           0.2    0.0    1.5    0.0  0.0  0.0    0.7   0   0
 631 ssd22.t2        0.2    0.0    1.5    0.0  0.0  0.0    0.0   0   0
 632 ssd22.t2.fp0    0.0    0.0    0.4    0.0  0.0  0.0    0.0   0   0
 633 ssd22.t2.fp1    0.0    0.0    0.4    0.0  0.0  0.0    0.0   0   0
 634 ssd22.t2.fp2    0.0    0.0    0.4    0.0  0.0  0.0    0.0   0   0
 635 ssd22.t2.fp3    0.0    0.0    0.4    0.0  0.0  0.0    0.0   0   0
 636 .fi
 637 .in -2
 638 .sp
 639 
 640 .SH ATTRIBUTES
 641 .sp
 642 .LP
 643 See \fBattributes\fR(5) for descriptions of the following attributes:
 644 .sp
 645 
 646 .sp
 647 .TS
 648 box;
 649 c | c
 650 l | l .
 651 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 652 _
 653 Interface Stability     See below.
 654 .TE
 655 
 656 .sp
 657 .LP
 658 Invocation is evolving. Human readable output is unstable.
 659 .SH SEE ALSO
 660 .sp
 661 .LP
 662 \fBdate\fR(1), \fBsar\fR(1), \fBsar\fR(1M), \fBmpstat\fR(1M), \fBvmstat\fR(1M),
 663 \fBtime\fR(2), \fBattributes\fR(5), \fBscsi_vhci\fR(7D)
 664 .SH NOTES
 665 .sp
 666 .LP
 667 The sum of \fBCPU\fR utilization might vary slightly from 100 because of
 668 rounding errors in the production of a percentage figure.
 669 .sp
 670 .LP
 671 The \fBsvc_t\fR response time is not particularly significant when the
 672 \fBI/0\fR (\fBr/s\fR+\fBw/s\fR) rates are under 0.5 per second. Harmless spikes
 673 are fairly normal in such cases.
 674 .sp
 675 .LP
 676 The \fBmpstat\fR utility reports the same \fBdt\fR, \fBusr\fR, and \fBsys\fR
 677 statistics. See \fBmpstat\fR(1M) for more information.
 678 .sp
 679 .LP
 680 When executed in a \fBzone\fR and if the pools facility is active,
 681 \fBiostat\fR(1M) will only provide information for those processors in the
 682 processor set of the pool to which the \fBzone\fR is bound.