'\" te
.\"
.\" CDDL HEADER START
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\" CDDL HEADER END
.\"
.\" Copyright (c) 2003, Sun Microsystems, Inc.  All Rights reserved
.\" Copyright (c) 2012 by Delphix. All rights reserved.
.\"
.TH IOSTAT 8 "Mar 23, 2009"
.SH NAME
iostat \- report I/O statistics
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/iostat\fR  [\fB-cCdDeEiImMnpPrstxXYz\fR] [\fB-l\fR \fIn\fR] [\fB-T\fR u | d]
 [\fIdisk\fR]... [\fIinterval\fR [\fIcount\fR]]
.fi

.SH DESCRIPTION
.sp
.LP
The \fBiostat\fR utility iteratively reports terminal, disk, and tape \fBI/O\fR
activity, as well as \fBCPU\fR utilization. The first line of output is for all
time since boot; each subsequent line is for the prior interval only.
.sp
.LP
To compute this information, the kernel maintains a number of counters. For
each disk, the kernel counts reads, writes, bytes read, and bytes written. The
kernel also takes hi-res time stamps at queue entry and exit points, which
allows it to keep track of the residence time and cumulative residence-length
product for each queue. Using these values, \fBiostat\fR produces highly
accurate measures of throughput, utilization, queue lengths, transaction rates
and service time. For terminals collectively, the kernel simply counts the
number of input and output characters.
.sp
.LP
During execution of the kernel status command, the \fBstate\fR of the system
can change. If relevant, a state change message is included in the \fBiostat\fR
output, in one of the following forms:
.sp
.in +2
.nf
<<device added: sd0>>
<<device removed: sd0>>
<<partition added: sd0,a>>
<<partition removed: sd0,a>>
<<NFS mounted: nfs1>>
<<NFS unmounted: nfs1>>
<<multi-path added: ssd4>>
<<multi-path removed: ssd4>>
<<controller added: c1>>
<<controller removed: c1>>
<<processors added: 1, 3>>
<<processors removed: 1, 3>>
.fi
.in -2
.sp

.sp
.LP
Note that the \fBnames\fR printed in these state change messages are affected
by the \fB-n\fR and \fB-m\fR options as appropriate.
.sp
.LP
For more general system statistics, use \fBsar\fR(1), \fBsar\fR(8), or
\fBvmstat\fR(8).
.SS "Output"
.sp
.LP
The output of the \fBiostat\fR utility includes the following information.
.sp
.ne 2
.na
\fB\fBdevice\fR\fR
.ad
.RS 10n
name of the disk
.RE

.sp
.ne 2
.na
\fB\fBr/s\fR\fR
.ad
.RS 10n
reads per second
.RE

.sp
.ne 2
.na
\fB\fBw/s\fR\fR
.ad
.RS 10n
writes per second
.RE

.sp
.ne 2
.na
\fB\fBkr/s\fR\fR
.ad
.RS 10n
kilobytes read per second
.sp
The average I/O size during the interval can be computed from \fBkr/s\fR
divided by \fBr/s\fR.
.RE

.sp
.ne 2
.na
\fB\fBkw/s\fR\fR
.ad
.RS 10n
kilobytes written per second
.sp
The average I/O size during the interval can be computed from \fBkw/s\fR
divided by \fBw/s\fR.
.RE

.sp
.ne 2
.na
\fB\fBwait\fR\fR
.ad
.RS 10n
average number of transactions waiting for service (queue length)
.sp
This is the number of I/O operations held in the device driver queue waiting
for acceptance by the device.
.RE

.sp
.ne 2
.na
\fB\fBactv\fR\fR
.ad
.RS 10n
average number of transactions actively being serviced (removed from the queue
but not yet completed)
.sp
This is the number of I/O operations accepted, but not yet serviced, by the
device.
.RE

.sp
.ne 2
.na
\fB\fBsvc_t\fR\fR
.ad
.RS 10n
average response time of transactions, in milliseconds
.sp
The \fBsvc_t\fR output reports the overall \fBresponse\fR time, rather than the
\fBservice\fR time, of a device. The overall time includes the time that
transactions are in queue and the time that transactions are being serviced.
The time spent in queue is shown with the \fB-x\fR option in the \fBwsvc_t\fR
output column. The time spent servicing transactions is the true service time.
Service time is also shown with the \fB-x\fR option and appears in the
\fBasvc_t\fR output column of the same report.
.RE

.sp
.ne 2
.na
\fB\fB%w\fR\fR
.ad
.RS 10n
percent of time there are transactions waiting for service (queue non-empty)
.RE

.sp
.ne 2
.na
\fB\fB%b\fR\fR
.ad
.RS 10n
percent of time the disk is busy (transactions in progress)
.RE

.sp
.ne 2
.na
\fB\fBwsvc_t\fR\fR
.ad
.RS 10n
average service time in wait queue, in milliseconds
.RE

.sp
.ne 2
.na
\fB\fBasvc_t\fR\fR
.ad
.RS 10n
average service time of active transactions, in milliseconds
.RE

.SH OPTIONS
.sp
.LP
The following options are supported:
.sp
.ne 2
.na
\fB\fB-c\fR\fR
.ad
.RS 12n
Report the percentage of time the system has spent in user mode, in system
mode, in dtrace probes, and idling. See the NOTES section and
\fBmpstat\fR(8) for more information.
.RE

.sp
.ne 2
.na
\fB\fB-C\fR\fR
.ad
.RS 12n
When the \fB-x\fR option is also selected, report extended disk statistics
aggregated by \fIcontroller id\fR.
.RE

.sp
.ne 2
.na
\fB\fB-d\fR\fR
.ad
.RS 12n
For each disk, report the number of kilobytes transferred per second, the
number of transfers per second, and the average service time in milliseconds.
.RE

.sp
.ne 2
.na
\fB\fB-D\fR\fR
.ad
.RS 12n
For each disk, report the reads per second, writes per second, and percentage
disk utilization.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 12n
Display device error summary statistics. The total errors, hard errors, soft
errors, and transport errors are displayed.
.RE

.sp
.ne 2
.na
\fB\fB-E\fR\fR
.ad
.RS 12n
Display all device error statistics.
.RE

.sp
.ne 2
.na
\fB\fB-i\fR\fR
.ad
.RS 12n
In \fB-E\fR output, display the \fBDevice ID\fR instead of the \fBSerial No\fR.
The \fBDevice Id\fR is a unique identifier registered by a driver through
\fBddi_devid_register\fR(9F).
.RE

.sp
.ne 2
.na
\fB\fB-I\fR\fR
.ad
.RS 12n
Report the counts in each interval, rather than rates (where applicable).
.RE

.sp
.ne 2
.na
\fB\fB-l\fR \fIn\fR\fR
.ad
.RS 12n
Limit the number of disks included in the report to \fIn\fR; the disk limit
defaults to 4 for \fB-d\fR and \fB-D\fR, and unlimited for \fB-x\fR. Note:
disks explicitly requested (see \fIdisk\fR below) are not subject to this disk
limit.
.RE

.sp
.ne 2
.na
\fB\fB-m\fR\fR
.ad
.RS 12n
Report file system mount points. This option is most useful if the \fB-P\fR or
\fB-p\fR option is also specified or used in conjunction with \fB-Xn\fR or
\fB-en\fR. The \fB-m\fR option is useful only if the mount point is actually
listed in the output. This option can only be used in conjunction with the
\fB-n\fR option.
.RE

.sp
.ne 2
.na
\fB\fB-M\fR\fR
.ad
.RS 12n
Display data throughput in \fBMB\fR/sec instead of KB/sec.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 12n
Display names in descriptive format. For example, \fBcXtYdZ\fR, \fBrmt/N\fR,
\fBserver:/export/path\fR.
.sp
By default, disks are identified by instance names such as \fBssd23\fR or
\fBmd301\fR. Combining the \fB-n\fR option with the \fB-x\fR option causes disk
names to display in the \fBcXtYdZsN\fR format which is more easily associated
with physical hardware characteristics. The \fBcXtYdZsN\fR format is
particularly useful in FibreChannel (FC) environments where the FC World Wide
Name appears in the \fBt\fR field.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 12n
For each disk, report per-partition statistics in addition to per-device
statistics.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.RS 12n
For each disk, report per-partition statistics only, no per-device statistics.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.RS 12n
Display data in a comma-separated format.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 12n
Suppress messages related to \fBstate changes\fR.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 12n
Report the number of characters read and written to terminals per second.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR u | d\fR
.ad
.RS 12n
Display a time stamp.
.sp
Specify \fBu\fR for a printed representation of the internal representation of
time. See \fBtime\fR(2). Specify \fBd\fR for standard date format. See
\fBdate\fR(1).
.RE

.sp
.ne 2
.na
\fB\fB-X\fR\fR
.ad
.RS 12n
For disks under \fBscsi_vhci\fR(4D) control, in addition to disk \fIlun\fR
statistics, also report statistics for \fIlun\fR.\fIcontroller\fR.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.RS 12n
Report extended disk statistics. By default, disks are identified by instance
names such as \fBssd23\fR or \fBmd301\fR. Combining the \fBx\fR option with the
\fB-n\fR option causes disk names to display in the \fBcXtYdZsN\fR format, more
easily associated with physical hardware characteristics. Using the
\fBcXtYdZsN\fR format is particularly helpful in the FibreChannel environments
where the FC World Wide Name appears in the \fBt\fR field.
.sp
If no output display is requested (no \fB-x\fR, \fB-e\fR, \fB-E\fR), \fB-x\fR
is implied.
.RE

.sp
.ne 2
.na
\fB\fB-Y\fR\fR
.ad
.RS 12n
For disks under \fBscsi_vhci\fR(4D) control, in addition to disk \fIlun\fR
statistics, also report statistics for \fIlun\fR.\fItargetport\fR and
\fIlun\fR.\fItargetport\fR.\fIcontroller\fR.
.sp
In \fB-n\fR (descriptive) mode the \fItargetport\fR is shown in using the
\fBtarget-port\fR property of the path. Without \fB-n\fR the \fItargetport\fR
is shown using the shorter \fBport-id\fR. All target ports with the same
\fBtarget-port\fR property value share the same \fBport-id\fR. The
\fBtarget-port\fR-to-\fBport-id\fR association does not persist across reboot.
.sp
If no output display is requested (no \fB-x\fR, \fB-e\fR, \fB-E\fR), \fB-x\fR
is implied.
.RE

.sp
.ne 2
.na
\fB\fB-z\fR\fR
.ad
.RS 12n
Do not print lines whose underlying data values are all zeros.
.RE

.sp
.LP
The option set \fB-xcnCXTdz\fR \fIinterval\fR is particularly useful for
determining whether disk I/O problems exist and for identifying problems.
.SH OPERANDS
.sp
.LP
The following operands are supported:
.sp
.ne 2
.na
\fB\fIcount\fR\fR
.ad
.RS 12n
Display only \fIcount\fR reports.
.RE

.sp
.ne 2
.na
\fB\fIdisk\fR\fR
.ad
.RS 12n
Explicitly specify the disks to be reported; in addition to any explicit disks,
any active disks up to the disk limit (see \fB-l\fR above) will also be
reported.
.RE

.sp
.ne 2
.na
\fB\fIinterval\fR\fR
.ad
.RS 12n
Report once each \fIinterval\fR seconds.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRUsing \fBiostat\fR to Generate User and System Operation
Statistics
.sp
.LP
The following command displays two reports of extended device statistics,
aggregated by \fIcontroller id\fR, for user (\fBus\fR) and system (\fBsy\fR)
operations. Because the \fB-n\fR option is used with the \fB-x\fR option,
devices are identified by controller names.

.sp
.in +2
.nf
example% \fBiostat\fR \fB-xcnCXTdz\fR \fB5\fR


Mon Nov 24 14:58:36 2003
    cpu
 us sy dt id
 14 31  0 20
                    extended device statistics
  r/s    w/s    kr/s      kw wait  actv wsvc_t asvc_t  %w  %b device
  3.8   29.9   145.8    44.0  0.0   0.2    0.1    6.4   0   5     c0
666.3  814.8 12577.6 17591.1 91.3  82.3   61.6   55.6   0   2    c12
180.0  234.6  4401.1  5712.6  0.0 147.7    0.0  356.3   0  98    d10

Mon Nov 24 14:58:41 2003
    cpu
 us sy dt id
 11 31  1 22
                    extended device statistics
  r/s    w/s    kr/s      kw wait  actv wsvc_t asvc_t  %w  %b device
  0.8   41.0     5.2    20.5 0.0    0.2    0.2    4.4   0   6     c0
565.3  581.7  8573.2 10458.9 0.0   26.6    0.0   23.2   0   3    c12
106.5   81.3  3393.2  1948.6 0.0    5.7    0.0   30.1   0  99    d10
.fi
.in -2
.sp

.LP
\fBExample 2 \fRUsing \fBiostat\fR to Generate TTY Statistics
.sp
.LP
The following command displays two reports on the activity of five disks in
different modes of operation. Because the \fB-x\fR option is used, disks are
identified by instance names.

.sp
.in +2
.nf
example% \fBiostat\fR \fB-x\fR \fBtc 5 2\fR


                  extended device statistics        tty         cpu
device r/s  w/s kr/s  kw/s wait actv svc_t %w  %b  tin tout  us sy dt id
sd0    0.4  0.3 10.4   8.0  0.0  0.0  36.9  0   1    0   10   0  0  0 99
sd1    0.0  0.0  0.3   0.4  0.0  0.0  35.0  0   0
sd6    0.0  0.0  0.0   0.0  0.0  0.0   0.0  0   0
nfs1   0.0  0.0  0.0   0.0  0.0  0.0   0.0  0   0
nfs2   0.0  0.0  0.0   0.1  0.0  0.0  35.6  0   0
            extended device statistics              tty         cpu
device r/s  w/s  kr/s  kw/s wait actv svc_t %w  %b tin tout  us sy dt id
sd0    0.0  0.0  0.0   0.0  0.0  0.0  0.0   0   0   0  155   0  0  0 100
sd1    0.0  0.0  0.0   0.0  0.0  0.0  0.0   0   0
sd6    0.0  0.0  0.0   0.0  0.0  0.0  0.0   0   0
nfs1   0.0  0.0  0.0   0.0  0.0  0.0  0.0   0   0
nfs2   0.0  0.0  0.0   0.0  0.0  0.0  0.0   0   0

.fi
.in -2
.sp

.LP
\fBExample 3 \fRUsing \fBiostat\fR to Generate Partition and Device Statistics
.sp
.LP
The following command generates partition and device statistics for each disk.
Because the \fB-n\fR option is used with the \fB-x\fR option, disks are
identified by controller names.

.sp
.in +2
.nf
example% \fBiostat -xnp\fR

                extended device statistics
r/s  w/s  kr/s kw/s wait actv wsvc_t asvc_t %w %b device
0.4  0.3  10.4  7.9  0.0  0.0    0.0   36.9  0  1 c0t0d0
0.3  0.3   9.0  7.3  0.0  0.0    0.0   37.2  0  1 c0t0d0s0
0.0  0.0   0.1  0.5  0.0  0.0    0.0   34.0  0  0 c0t0d0s1
0.0  0.0   0.0  0.1  0.0  0.0    0.6   35.0  0  0 fuji:/export/home/user3
.fi
.in -2
.sp

.LP
\fBExample 4 \fRShow Translation from Instance Name to Descriptive Name
.sp
.LP
The following example illustrates the use of \fBiostat\fR to translate a
specific instance name to a descriptive name.

.sp
.in +2
.nf
example% \fBiostat -xn sd1\fR
                        extended device statistics
r/s    w/s   kr/s   kw/s wait actv wsvc_t asvc_t  %w  %b device
0.0    0.0    0.0    0.0  0.0  0.0    0.0    0.0   0   0 c8t1d0
.fi
.in -2
.sp

.LP
\fBExample 5 \fRShow Target Port and Controller Activity for a Specific Disk
.sp
.LP
In the following example, there are four controllers, all connected to the same
target port.

.sp
.in +2
.nf
# \fBiostat -Y ssd22\fR
                    extended device statistics
device          r/s    w/s   kr/s   kw/s wait actv  svc_t  %w  %b
ssd22           0.2    0.0    1.5    0.0  0.0  0.0    0.7   0   0
ssd22.t2        0.2    0.0    1.5    0.0  0.0  0.0    0.0   0   0
ssd22.t2.fp0    0.0    0.0    0.4    0.0  0.0  0.0    0.0   0   0
ssd22.t2.fp1    0.0    0.0    0.4    0.0  0.0  0.0    0.0   0   0
ssd22.t2.fp2    0.0    0.0    0.4    0.0  0.0  0.0    0.0   0   0
ssd22.t2.fp3    0.0    0.0    0.4    0.0  0.0  0.0    0.0   0   0
.fi
.in -2
.sp

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	See below.
.TE

.sp
.LP
Invocation is evolving. Human readable output is unstable.
.SH SEE ALSO
.sp
.LP
.BR date (1),
.BR sar (1),
.BR time (2),
.BR scsi_vhci (4D),
.BR attributes (7),
.BR mpstat (8),
.BR sar (8),
.BR vmstat (8)
.SH NOTES
.sp
.LP
The sum of \fBCPU\fR utilization might vary slightly from 100 because of
rounding errors in the production of a percentage figure.
.sp
.LP
The \fBsvc_t\fR response time is not particularly significant when the
\fBI/0\fR (\fBr/s\fR+\fBw/s\fR) rates are under 0.5 per second. Harmless spikes
are fairly normal in such cases.
.sp
.LP
The \fBmpstat\fR utility reports the same \fBdt\fR, \fBusr\fR, and \fBsys\fR
statistics. See \fBmpstat\fR(8) for more information.
.sp
.LP
When executed in a \fBzone\fR and if the pools facility is active,
\fBiostat\fR(8) will only provide information for those processors in the
processor set of the pool to which the \fBzone\fR is bound.