| blob | 9c54d91142a25ac2dca44c496b4d1837731c7490 |
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
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
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
96 .sp
97 .ne 2
98 .na
99 \fB\fBr/s\fR\fR
100 .ad
101 .RS 10n
102 reads per second
103 .RE
105 .sp
106 .ne 2
107 .na
108 \fB\fBw/s\fR\fR
109 .ad
110 .RS 10n
111 writes per second
112 .RE
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
514 .sp
515 .in +2
516 .nf
517 example% \fBiostat\fR \fB-xcnCXTdz\fR \fB5\fR
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
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
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.
551 .sp
552 .in +2
553 .nf
554 example% \fBiostat\fR \fB-x\fR \fBtc 5 2\fR
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
572 .fi
573 .in -2
574 .sp
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.
584 .sp
585 .in +2
586 .nf
587 example% \fBiostat -xnp\fR
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
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.
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
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.
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
640 .SH ATTRIBUTES
641 .sp
642 .LP
643 See \fBattributes\fR(5) for descriptions of the following attributes:
644 .sp
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
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.