1IOSTAT(1)                     Linux User's Manual                    IOSTAT(1)
2
3
4

NAME

6       iostat - Report Central Processing Unit (CPU) statistics and input/out‐
7       put statistics for devices and partitions.
8
9

SYNOPSIS

11       iostat [ -c ] [ -d ] [ -h ] [ -k | -m ] [ -N ] [ -s ] [ -t ] [ -V  ]  [
12       -x  ] [ -y ] [ -z ] [ --compact ] [ --dec={ 0 | 1 | 2 } ] [ { -f | +f }
13       directory ] [ -j { ID | LABEL | PATH | UUID | ... } ] [ -o JSON ]  [  [
14       -H ] -g group_name ] [ --human ] [ --pretty ] [ -p [ device[,...] | ALL
15       ] ] [ device [...] | ALL ] [ interval [ count ] ]
16
17

DESCRIPTION

19       The iostat command is used for monitoring  system  input/output  device
20       loading  by  observing  the  time the devices are active in relation to
21       their average transfer rates. The iostat command generates reports that
22       can  be  used  to change system configuration to better balance the in‐
23       put/output load between physical disks.
24
25       The first report generated by the iostat  command  provides  statistics
26       concerning  the  time since the system was booted, unless the -y option
27       is used (in this case, this first report is omitted).  Each  subsequent
28       report  covers  the  time since the previous report. All statistics are
29       reported each time the iostat command is run. The report consists of  a
30       CPU  header  row followed by a row of CPU statistics. On multiprocessor
31       systems, CPU statistics are calculated system-wide  as  averages  among
32       all  processors. A device header row is displayed followed by a line of
33       statistics for each device that is configured.
34
35       The interval parameter specifies the amount of time in seconds  between
36       each  report.  The count parameter can be specified in conjunction with
37       the interval parameter. If the count parameter is specified, the  value
38       of count determines the number of reports generated at interval seconds
39       apart. If the interval parameter is specified without the count parame‐
40       ter, the iostat command generates reports continuously.
41
42

REPORTS

44       The  iostat command generates two types of reports, the CPU Utilization
45       report and the Device Utilization report.
46
47
48       CPU Utilization Report
49              The first report generated by the iostat command is the CPU Uti‐
50              lization  Report. For multiprocessor systems, the CPU values are
51              global averages among all processors.  The report has  the  fol‐
52              lowing format:
53
54              %user  Show  the  percentage  of  CPU  utilization that occurred
55                     while executing at the user level (application).
56
57              %nice  Show the percentage  of  CPU  utilization  that  occurred
58                     while executing at the user level with nice priority.
59
60              %system
61                     Show  the  percentage  of  CPU  utilization that occurred
62                     while executing at the system level (kernel).
63
64              %iowait
65                     Show the percentage of time that the  CPU  or  CPUs  were
66                     idle  during which the system had an outstanding disk I/O
67                     request.
68
69              %steal Show the percentage of time spent in involuntary wait  by
70                     the  virtual CPU or CPUs while the hypervisor was servic‐
71                     ing another virtual processor.
72
73              %idle  Show the percentage of time that the  CPU  or  CPUs  were
74                     idle  and the system did not have an outstanding disk I/O
75                     request.
76
77       Device Utilization Report
78              The second report generated by the iostat command is the  Device
79              Utilization  Report.  The device report provides statistics on a
80              per physical device or partition basis. Block devices and parti‐
81              tions for which statistics are to be displayed may be entered on
82              the command line.  If no device nor partition is  entered,  then
83              statistics  are  displayed  for every device used by the system,
84              and providing that the kernel maintains statistics for  it.   If
85              the  ALL  keyword  is given on the command line, then statistics
86              are displayed for every device defined by the system,  including
87              those that have never been used.  Transfer rates are shown in 1K
88              blocks by default, unless the environment variable  POSIXLY_COR‐
89              RECT is set, in which case 512-byte blocks are used.  The report
90              may show the following fields, depending on the flags used (e.g.
91              -x, -s and -k or -m):
92
93              Device:
94                     This  column  gives  the  device  (or  partition) name as
95                     listed in the /dev directory.
96
97              tps    Indicate the number of transfers per second that were is‐
98                     sued  to  the device. A transfer is an I/O request to the
99                     device. Multiple logical requests can be combined into  a
100                     single  I/O request to the device. A transfer is of inde‐
101                     terminate size.
102
103              Blk_read/s (kB_read/s, MB_read/s)
104                     Indicate the amount of data  read  from  the  device  ex‐
105                     pressed  in a number of blocks (kilobytes, megabytes) per
106                     second. Blocks are equivalent to  sectors  and  therefore
107                     have a size of 512 bytes.
108
109              Blk_wrtn/s (kB_wrtn/s, MB_wrtn/s)
110                     Indicate  the  amount  of  data written to the device ex‐
111                     pressed in a number of blocks (kilobytes, megabytes)  per
112                     second.
113
114              Blk_dscd/s (kB_dscd/s, MB_dscd/s)
115                     Indicate  the amount of data discarded for the device ex‐
116                     pressed in a number of blocks (kilobytes, megabytes)  per
117                     second.
118
119              Blk_w+d/s (kB_w+d/s, MB_w+d/s)
120                     Indicate  the  amount of data written to or discarded for
121                     the device expressed in a number  of  blocks  (kilobytes,
122                     megabytes) per second.
123
124              Blk_read (kB_read, MB_read)
125                     The total number of blocks (kilobytes, megabytes) read.
126
127              Blk_wrtn (kB_wrtn, MB_wrtn)
128                     The  total  number of blocks (kilobytes, megabytes) writ‐
129                     ten.
130
131              Blk_dscd (kB_dscd, MB_dscd)
132                     The total number of blocks  (kilobytes,  megabytes)  dis‐
133                     carded.
134
135              Blk_w+d (kB_w+d, MB_w+d)
136                     The total number of blocks (kilobytes, megabytes) written
137                     or discarded.
138
139              r/s    The number (after merges) of read requests completed  per
140                     second for the device.
141
142              w/s    The number (after merges) of write requests completed per
143                     second for the device.
144
145              d/s    The number (after merges) of discard  requests  completed
146                     per second for the device.
147
148              f/s    The number (after merges) of flush requests completed per
149                     second for the device.  This counts flush  requests  exe‐
150                     cuted by disks. Flush requests are not tracked for parti‐
151                     tions.  Before being merged, flush operations are counted
152                     as writes.
153
154              sec/s (kB/s, MB/s)
155                     The  number  of sectors (kilobytes, megabytes) read from,
156                     written to or discarded for the device per second.
157
158              rsec/s (rkB/s, rMB/s)
159                     The number of sectors (kilobytes,  megabytes)  read  from
160                     the device per second.
161
162              wsec/s (wkB/s, wMB/s)
163                     The  number  of sectors (kilobytes, megabytes) written to
164                     the device per second.
165
166              dsec/s (dkB/s, dMB/s)
167                     The number of sectors  (kilobytes,  megabytes)  discarded
168                     for the device per second.
169
170              rqm/s  The  number  of  I/O requests merged per second that were
171                     queued to the device.
172
173              rrqm/s The number of read requests merged per second  that  were
174                     queued to the device.
175
176              wrqm/s The  number of write requests merged per second that were
177                     queued to the device.
178
179              drqm/s The number of discard requests  merged  per  second  that
180                     were queued to the device.
181
182              %rrqm  The  percentage  of  read requests merged together before
183                     being sent to the device.
184
185              %wrqm  The percentage of write requests merged  together  before
186                     being sent to the device.
187
188              %drqm  The percentage of discard requests merged together before
189                     being sent to the device.
190
191              areq-sz
192                     The average size (in kilobytes) of the I/O requests  that
193                     were issued to the device.
194                     Note:  In  previous versions, this field was known as av‐
195                     grq-sz and was expressed in sectors.
196
197              rareq-sz
198                     The average size (in kilobytes) of the read requests that
199                     were issued to the device.
200
201              wareq-sz
202                     The  average  size  (in  kilobytes) of the write requests
203                     that were issued to the device.
204
205              dareq-sz
206                     The average size (in kilobytes) of the  discard  requests
207                     that were issued to the device.
208
209              await  The  average  time (in milliseconds) for I/O requests is‐
210                     sued to the device to be served. This includes  the  time
211                     spent by the requests in queue and the time spent servic‐
212                     ing them.
213
214              r_await
215                     The average time (in milliseconds) for read requests  is‐
216                     sued  to  the device to be served. This includes the time
217                     spent by the requests in queue and the time spent servic‐
218                     ing them.
219
220              w_await
221                     The average time (in milliseconds) for write requests is‐
222                     sued to the device to be served. This includes  the  time
223                     spent by the requests in queue and the time spent servic‐
224                     ing them.
225
226              d_await
227                     The average time (in milliseconds) for  discard  requests
228                     issued to the device to be served. This includes the time
229                     spent by the requests in queue and the time spent servic‐
230                     ing them.
231
232              f_await
233                     The average time (in milliseconds) for flush requests is‐
234                     sued to the device to be served.  The  block  layer  com‐
235                     bines  flush requests and executes at most one at a time.
236                     Thus flush operations could be twice as  long:  Wait  for
237                     current flush request, then execute it, then wait for the
238                     next one.
239
240              aqu-sz The average queue length of the requests that were issued
241                     to the device.
242                     Note:  In  previous  versions,  this  field  was known as
243                     avgqu-sz.
244
245              %util  Percentage of elapsed time during which I/O requests were
246                     issued  to  the device (bandwidth utilization for the de‐
247                     vice). Device saturation occurs when this value is  close
248                     to  100%  for devices serving requests serially.  But for
249                     devices serving requests in parallel, such as RAID arrays
250                     and  modern SSDs, this number does not reflect their per‐
251                     formance limits.
252
253

OPTIONS

255       -c     Display the CPU utilization report.
256
257       --compact
258              Don't break the Device Utilization Report  into  sub-reports  so
259              that all the metrics get displayed on a single line.
260
261       -d     Display the device utilization report.
262
263       --dec={ 0 | 1 | 2 }
264              Specify  the  number  of  decimal places to use (0 to 2, default
265              value is 2).
266
267       -f directory
268       +f directory
269              Specify an alternative directory for iostat to read devices sta‐
270              tistics. Option -f tells iostat to use only the files located in
271              the alternative directory, whereas option +f  tells  it  to  use
272              both  the standard kernel files and the files located in the al‐
273              ternative directory to read device statistics.
274
275              directory is a directory containing files  with  statistics  for
276              devices managed in userspace.  It may contain:
277
278              - a "diskstats" file whose format is compliant with that located
279              in "/proc",
280              - statistics for individual devices  contained  in  files  whose
281              format is compliant with that of files located in "/sys".
282
283              In  particular,  the following files located in directory may be
284              used by iostat:
285
286              directory/block/device/stat
287              directory/block/device/partition/stat
288
289              partition files must have an entry in  directory/dev/block/  di‐
290              rectory, e.g.:
291
292              directory/dev/block/major:minor --> ../../block/device/partition
293
294       -g group_name { device [...] | ALL }
295              Display  statistics  for a group of devices.  The iostat command
296              reports statistics for each individual device in the list then a
297              line  of global statistics for the group displayed as group_name
298              and made up of all the devices in  the  list.  The  ALL  keyword
299              means  that all the block devices defined by the system shall be
300              included in the group.
301
302       -H     This option must be used with option -g and indicates that  only
303              global  statistics  for  the  group are to be displayed, and not
304              statistics for individual devices in the group.
305
306       -h     This option is equivalent to specifying --human --pretty.
307
308       --human
309              Print sizes in human readable format  (e.g.  1.0k,  1.2M,  etc.)
310              The units displayed with this option supersede any other default
311              units (e.g.  kilobytes, sectors...) associated with the metrics.
312
313       -j { ID | LABEL | PATH | UUID | ... } [ device [...] | ALL ]
314              Display persistent device names. Keywords ID, LABEL, etc.  spec‐
315              ify the type of the persistent name. These keywords are not lim‐
316              ited, only prerequisite is that directory with required  persis‐
317              tent  names  is  present in /dev/disk.  Optionally, multiple de‐
318              vices can be specified in the chosen persistent name type.   Be‐
319              cause  persistent device names are usually long, option --pretty
320              is implicitly set with this option.
321
322       -k     Display statistics in kilobytes per second.
323
324       -m     Display statistics in megabytes per second.
325
326       -N     Display the registered device mapper names for any device mapper
327              devices.  Useful for viewing LVM2 statistics.
328
329       -o JSON
330              Display the statistics in JSON (JavaScript Object Notation) for‐
331              mat.  JSON output field order is undefined, and new  fields  may
332              be added in the future.
333
334       -p [ { device[,...] | ALL } ]
335              Display  statistics  for  block devices and all their partitions
336              that are used by the system.  If a device name is entered on the
337              command  line, then statistics for it and all its partitions are
338              displayed. Last, the ALL keyword indicates that statistics  have
339              to be displayed for all the block devices and partitions defined
340              by the system, including those that have never been used. If op‐
341              tion  -j  is  defined before this option, devices entered on the
342              command line can be specified with the  chosen  persistent  name
343              type.
344
345       --pretty
346              Make  the  Device  Utilization Report easier to read by a human.
347              The device name will be printed on the right  side.  The  report
348              may also be broken into sub-reports if there are many metrics to
349              display (use --compact option to prevent this).
350
351       -s     Display a short (narrow) version of the report that  should  fit
352              in 80 characters wide screens.
353
354       -t     Print  the  time for each report displayed. The timestamp format
355              may depend on the value of the S_TIME_FORMAT  environment  vari‐
356              able (see below).
357
358       -V     Print version number then exit.
359
360       -x     Display extended statistics.
361
362       -y     Omit first report with statistics since system boot, if display‐
363              ing multiple records at given interval.
364
365       -z     Tell iostat to omit output for any devices for which  there  was
366              no activity during the sample period.
367
368

ENVIRONMENT

370       The  iostat  command takes into account the following environment vari‐
371       ables:
372
373       POSIXLY_CORRECT
374              When this variable is set, transfer rates are shown in  512-byte
375              blocks instead of the default 1K blocks.
376
377       S_COLORS
378              By  default statistics are displayed in color when the output is
379              connected to a terminal.  Use this variable to change  the  set‐
380              tings.  Possible  values  for this variable are never, always or
381              auto (the latter is equivalent to the default settings).
382              Please note that the color (being red,  yellow,  or  some  other
383              color)  used to display a value is not indicative of any kind of
384              issue simply because of the color. It only  indicates  different
385              ranges of values.
386
387       S_COLORS_SGR
388              Specify  the colors and other attributes used to display statis‐
389              tics on the terminal.  Its value is a  colon-separated  list  of
390              capabilities             that             defaults            to
391              I=32;22:N=34;1:W=35;1:X=31;1:Z=34;22.   Supported   capabilities
392              are:
393
394              I=     SGR  (Select  Graphic  Rendition)  substring  for  device
395                     names.
396
397              N=     SGR substring for non-zero statistics values.
398
399              W= (or M=)
400                     SGR substring for percentage values in the range from 75%
401                     to  90% (or in the range 10% to 25% depending on the met‐
402                     ric's meaning).
403
404              X= (or H=)
405                     SGR substring for percentage values greater than or equal
406                     to  90%  (or  lower than or equal to 10% depending on the
407                     metric's meaning).
408
409              Z=     SGR substring for zero values.
410
411       S_TIME_FORMAT
412              If this variable exists and its value is ISO  then  the  current
413              locale  will  be  ignored  when  printing the date in the report
414              header. The iostat command will use the ISO 8601  format  (YYYY-
415              MM-DD)  instead.   The  timestamp  displayed with option -t will
416              also be compliant with ISO 8601 format.
417
418

EXAMPLES

420       iostat Display a single history since boot report for all CPU  and  De‐
421              vices.
422
423       iostat -d 2
424              Display a continuous device report at two second intervals.
425
426       iostat -d 2 6
427              Display six reports at two second intervals for all devices.
428
429       iostat -x sda sdb 2 6
430              Display  six reports of extended statistics at two second inter‐
431              vals for devices sda and sdb.
432
433       iostat -p sda 2 6
434              Display six reports at two second intervals for device  sda  and
435              all its partitions (sda1, etc.)
436
437

BUGS

439       /proc filesystem must be mounted for iostat to work.
440
441       Kernels older than 2.6.x are no longer supported.
442
443       Although  iostat  speaks of kilobytes (kB), megabytes (MB)..., it actu‐
444       ally uses kibibytes (kiB), mebibytes (MiB)...  A kibibyte is  equal  to
445       1024 bytes, and a mebibyte is equal to 1024 kibibytes.
446
447

FILES

449       /proc/stat contains system statistics.
450       /proc/uptime contains system uptime.
451       /proc/diskstats contains disks statistics.
452       /sys contains statistics for block devices.
453       /proc/self/mountstats contains statistics for network filesystems.
454       /dev/disk contains persistent device names.
455
456

AUTHOR

458       Sebastien Godard (sysstat <at> orange.fr)
459
460

SEE ALSO

462       sar(1),  pidstat(1),  mpstat(1),  vmstat(8), tapestat(1), nfsiostat(1),
463       cifsiostat(1)
464
465       https://github.com/sysstat/sysstat
466
467
468
469Linux                              MAY 2023                          IOSTAT(1)
Impressum