blob: 8e6e29bbc7dd98e6eb9857596c02de03ebdd0635 [file] [log] [blame]
Jens Axboe71bfa162006-10-25 11:08:19 +02001Table of contents
2-----------------
3
41. Overview
52. How fio works
63. Running fio
74. Job file format
85. Detailed list of parameters
96. Normal output
107. Terse output
11
12
131.0 Overview and history
14------------------------
15fio was originally written to save me the hassle of writing special test
16case programs when I wanted to test a specific workload, either for
17performance reasons or to find/reproduce a bug. The process of writing
18such a test app can be tiresome, especially if you have to do it often.
19Hence I needed a tool that would be able to simulate a given io workload
20without resorting to writing a tailored test case again and again.
21
22A test work load is difficult to define, though. There can be any number
23of processes or threads involved, and they can each be using their own
24way of generating io. You could have someone dirtying large amounts of
25memory in an memory mapped file, or maybe several threads issuing
26reads using asynchronous io. fio needed to be flexible enough to
27simulate both of these cases, and many more.
28
292.0 How fio works
30-----------------
31The first step in getting fio to simulate a desired io workload, is
32writing a job file describing that specific setup. A job file may contain
33any number of threads and/or files - the typical contents of the job file
34is a global section defining shared parameters, and one or more job
35sections describing the jobs involved. When run, fio parses this file
36and sets everything up as described. If we break down a job from top to
37bottom, it contains the following basic parameters:
38
39 IO type Defines the io pattern issued to the file(s).
40 We may only be reading sequentially from this
41 file(s), or we may be writing randomly. Or even
42 mixing reads and writes, sequentially or randomly.
43
44 Block size In how large chunks are we issuing io? This may be
45 a single value, or it may describe a range of
46 block sizes.
47
48 IO size How much data are we going to be reading/writing.
49
50 IO engine How do we issue io? We could be memory mapping the
51 file, we could be using regular read/write, we
Jens Axboed0ff85d2007-02-14 01:19:41 +010052 could be using splice, async io, syslet, or even
Jens Axboe71bfa162006-10-25 11:08:19 +020053 SG (SCSI generic sg).
54
Jens Axboe6c219762006-11-03 15:51:45 +010055 IO depth If the io engine is async, how large a queuing
Jens Axboe71bfa162006-10-25 11:08:19 +020056 depth do we want to maintain?
57
58 IO type Should we be doing buffered io, or direct/raw io?
59
60 Num files How many files are we spreading the workload over.
61
62 Num threads How many threads or processes should we spread
63 this workload over.
64
65The above are the basic parameters defined for a workload, in addition
66there's a multitude of parameters that modify other aspects of how this
67job behaves.
68
69
703.0 Running fio
71---------------
72See the README file for command line parameters, there are only a few
73of them.
74
75Running fio is normally the easiest part - you just give it the job file
76(or job files) as parameters:
77
78$ fio job_file
79
80and it will start doing what the job_file tells it to do. You can give
81more than one job file on the command line, fio will serialize the running
82of those files. Internally that is the same as using the 'stonewall'
83parameter described the the parameter section.
84
Jens Axboeb4692822006-10-27 13:43:22 +020085If the job file contains only one job, you may as well just give the
86parameters on the command line. The command line parameters are identical
87to the job parameters, with a few extra that control global parameters
88(see README). For example, for the job file parameter iodepth=2, the
Jens Axboec2b1e752006-10-30 09:03:13 +010089mirror command line option would be --iodepth 2 or --iodepth=2. You can
90also use the command line for giving more than one job entry. For each
91--name option that fio sees, it will start a new job with that name.
92Command line entries following a --name entry will apply to that job,
93until there are no more entries or a new --name entry is seen. This is
94similar to the job file options, where each option applies to the current
95job until a new [] job entry is seen.
Jens Axboeb4692822006-10-27 13:43:22 +020096
Jens Axboe71bfa162006-10-25 11:08:19 +020097fio does not need to run as root, except if the files or devices specified
98in the job section requires that. Some other options may also be restricted,
Jens Axboe6c219762006-11-03 15:51:45 +010099such as memory locking, io scheduler switching, and decreasing the nice value.
Jens Axboe71bfa162006-10-25 11:08:19 +0200100
101
1024.0 Job file format
103-------------------
104As previously described, fio accepts one or more job files describing
105what it is supposed to do. The job file format is the classic ini file,
106where the names enclosed in [] brackets define the job name. You are free
107to use any ascii name you want, except 'global' which has special meaning.
108A global section sets defaults for the jobs described in that file. A job
109may override a global section parameter, and a job file may even have
110several global sections if so desired. A job is only affected by a global
111section residing above it. If the first character in a line is a ';', the
112entire line is discarded as a comment.
113
114So lets look at a really simple job file that define to threads, each
115randomly reading from a 128MiB file.
116
117; -- start job file --
118[global]
119rw=randread
120size=128m
121
122[job1]
123
124[job2]
125
126; -- end job file --
127
128As you can see, the job file sections themselves are empty as all the
129described parameters are shared. As no filename= option is given, fio
Jens Axboec2b1e752006-10-30 09:03:13 +0100130makes up a filename for each of the jobs as it sees fit. On the command
131line, this job would look as follows:
132
133$ fio --name=global --rw=randread --size=128m --name=job1 --name=job2
134
Jens Axboe71bfa162006-10-25 11:08:19 +0200135
136Lets look at an example that have a number of processes writing randomly
137to files.
138
139; -- start job file --
140[random-writers]
141ioengine=libaio
142iodepth=4
143rw=randwrite
144bs=32k
145direct=0
146size=64m
147numjobs=4
148
149; -- end job file --
150
151Here we have no global section, as we only have one job defined anyway.
152We want to use async io here, with a depth of 4 for each file. We also
153increased the buffer size used to 32KiB and define numjobs to 4 to
154fork 4 identical jobs. The result is 4 processes each randomly writing
Jens Axboeb4692822006-10-27 13:43:22 +0200155to their own 64MiB file. Instead of using the above job file, you could
156have given the parameters on the command line. For this case, you would
157specify:
158
159$ fio --name=random-writers --ioengine=libaio --iodepth=4 --rw=randwrite --bs=32k --direct=0 --size=64m --numjobs=4
Jens Axboe71bfa162006-10-25 11:08:19 +0200160
161fio ships with a few example job files, you can also look there for
162inspiration.
163
164
1655.0 Detailed list of parameters
166-------------------------------
167
168This section describes in details each parameter associated with a job.
169Some parameters take an option of a given type, such as an integer or
170a string. The following types are used:
171
172str String. This is a sequence of alpha characters.
173int Integer. A whole number value, may be negative.
174siint SI integer. A whole number value, which may contain a postfix
175 describing the base of the number. Accepted postfixes are k/m/g,
Jens Axboe6c219762006-11-03 15:51:45 +0100176 meaning kilo, mega, and giga. So if you want to specify 4096,
Jens Axboe71bfa162006-10-25 11:08:19 +0200177 you could either write out '4096' or just give 4k. The postfixes
178 signify base 2 values, so 1024 is 1k and 1024k is 1m and so on.
179bool Boolean. Usually parsed as an integer, however only defined for
180 true and false (1 and 0).
181irange Integer range with postfix. Allows value range to be given, such
Jens Axboe0c9baf92007-01-11 15:59:26 +0100182 as 1024-4096. A colon may also be used as the seperator, eg
183 1k:4k. If the option allows two sets of ranges, they can be
184 specified with a ',' or '/' delimiter: 1k-4k/8k-32k. Also see
185 siint.
Jens Axboe71bfa162006-10-25 11:08:19 +0200186
187With the above in mind, here follows the complete list of fio job
188parameters.
189
190name=str ASCII name of the job. This may be used to override the
191 name printed by fio for this job. Otherwise the job
Jens Axboec2b1e752006-10-30 09:03:13 +0100192 name is used. On the command line this parameter has the
Jens Axboe6c219762006-11-03 15:51:45 +0100193 special purpose of also signaling the start of a new
Jens Axboec2b1e752006-10-30 09:03:13 +0100194 job.
Jens Axboe71bfa162006-10-25 11:08:19 +0200195
Jens Axboe61697c32007-02-05 15:04:46 +0100196description=str Text description of the job. Doesn't do anything except
197 dump this text description when this job is run. It's
198 not parsed.
199
Jens Axboe71bfa162006-10-25 11:08:19 +0200200directory=str Prefix filenames with this directory. Used to places files
201 in a different location than "./".
202
203filename=str Fio normally makes up a filename based on the job name,
204 thread number, and file number. If you want to share
205 files between threads in a job or several jobs, specify
Jens Axboeed92ac02007-02-06 14:43:52 +0100206 a filename for each of them to override the default. If
207 the ioengine used is 'net', the filename is the host and
208 port to connect to in the format of =host:port.
Jens Axboe71bfa162006-10-25 11:08:19 +0200209
210rw=str Type of io pattern. Accepted values are:
211
212 read Sequential reads
213 write Sequential writes
214 randwrite Random writes
215 randread Random reads
216 rw Sequential mixed reads and writes
217 randrw Random mixed reads and writes
218
219 For the mixed io types, the default is to split them 50/50.
220 For certain types of io the result may still be skewed a bit,
221 since the speed may be different.
222
Jens Axboeee738492007-01-10 11:23:16 +0100223randrepeat=bool For random IO workloads, seed the generator in a predictable
224 way so that results are repeatable across repetitions.
225
Jens Axboe71bfa162006-10-25 11:08:19 +0200226size=siint The total size of file io for this job. This may describe
227 the size of the single file the job uses, or it may be
228 divided between the number of files in the job. If the
229 file already exists, the file size will be adjusted to this
230 size if larger than the current file size. If this parameter
231 is not given and the file exists, the file size will be used.
232
Jens Axboef90eff52006-11-06 11:08:21 +0100233bs=siint The block size used for the io units. Defaults to 4k. Values
234 can be given for both read and writes. If a single siint is
235 given, it will apply to both. If a second siint is specified
236 after a comma, it will apply to writes only. In other words,
237 the format is either bs=read_and_write or bs=read,write.
238 bs=4k,8k will thus use 4k blocks for reads, and 8k blocks
Jens Axboe787f7e92006-11-06 13:26:29 +0100239 for writes. If you only wish to set the write size, you
240 can do so by passing an empty read size - bs=,8k will set
241 8k for writes and leave the read default value.
Jens Axboea00735e2006-11-03 08:58:08 +0100242
Jens Axboe71bfa162006-10-25 11:08:19 +0200243bsrange=irange Instead of giving a single block size, specify a range
244 and fio will mix the issued io block sizes. The issued
245 io unit will always be a multiple of the minimum value
Jens Axboef90eff52006-11-06 11:08:21 +0100246 given (also see bs_unaligned). Applies to both reads and
247 writes, however a second range can be given after a comma.
248 See bs=.
Jens Axboea00735e2006-11-03 08:58:08 +0100249
Jens Axboe690adba2006-10-30 15:25:09 +0100250bs_unaligned If this option is given, any byte size value within bsrange
251 may be used as a block range. This typically wont work with
252 direct IO, as that normally requires sector alignment.
Jens Axboe71bfa162006-10-25 11:08:19 +0200253
254nrfiles=int Number of files to use for this job. Defaults to 1.
255
256ioengine=str Defines how the job issues io to the file. The following
257 types are defined:
258
259 sync Basic read(2) or write(2) io. lseek(2) is
260 used to position the io location.
261
262 libaio Linux native asynchronous io.
263
264 posixaio glibc posix asynchronous io.
265
266 mmap File is memory mapped and data copied
267 to/from using memcpy(3).
268
269 splice splice(2) is used to transfer the data and
270 vmsplice(2) to transfer data from user
271 space to the kernel.
272
Jens Axboed0ff85d2007-02-14 01:19:41 +0100273 syslet-rw Use the syslet system calls to make
274 regular read/write async.
275
Jens Axboe71bfa162006-10-25 11:08:19 +0200276 sg SCSI generic sg v3 io. May either be
Jens Axboe6c219762006-11-03 15:51:45 +0100277 synchronous using the SG_IO ioctl, or if
Jens Axboe71bfa162006-10-25 11:08:19 +0200278 the target is an sg character device
279 we use read(2) and write(2) for asynchronous
280 io.
281
Jens Axboea94ea282006-11-24 12:37:34 +0100282 null Doesn't transfer any data, just pretends
283 to. This is mainly used to exercise fio
284 itself and for debugging/testing purposes.
285
Jens Axboeed92ac02007-02-06 14:43:52 +0100286 net Transfer over the network to given host:port.
287 'filename' must be set appropriately to
288 filename=host:port regardless of send
289 or receive, if the latter only the port
290 argument is used.
291
Jens Axboe71bfa162006-10-25 11:08:19 +0200292iodepth=int This defines how many io units to keep in flight against
293 the file. The default is 1 for each file defined in this
294 job, can be overridden with a larger value for higher
295 concurrency.
296
297direct=bool If value is true, use non-buffered io. This is usually
Jens Axboe76a43db2007-01-11 13:24:44 +0100298 O_DIRECT.
299
300buffered=bool If value is true, use buffered io. This is the opposite
301 of the 'direct' option. Defaults to true.
Jens Axboe71bfa162006-10-25 11:08:19 +0200302
303offset=siint Start io at the given offset in the file. The data before
304 the given offset will not be touched. This effectively
305 caps the file size at real_size - offset.
306
307fsync=int If writing to a file, issue a sync of the dirty data
308 for every number of blocks given. For example, if you give
309 32 as a parameter, fio will sync the file for every 32
310 writes issued. If fio is using non-buffered io, we may
311 not sync the file. The exception is the sg io engine, which
Jens Axboe6c219762006-11-03 15:51:45 +0100312 synchronizes the disk cache anyway.
Jens Axboe71bfa162006-10-25 11:08:19 +0200313
314overwrite=bool If writing to a file, setup the file first and do overwrites.
315
316end_fsync=bool If true, fsync file contents when the job exits.
317
Jens Axboe6c219762006-11-03 15:51:45 +0100318rwmixcycle=int Value in milliseconds describing how often to switch between
Jens Axboe71bfa162006-10-25 11:08:19 +0200319 reads and writes for a mixed workload. The default is
320 500 msecs.
321
322rwmixread=int How large a percentage of the mix should be reads.
323
324rwmixwrite=int How large a percentage of the mix should be writes. If both
325 rwmixread and rwmixwrite is given and the values do not add
326 up to 100%, the latter of the two will be used to override
327 the first.
328
Jens Axboebb8895e2006-10-30 15:14:48 +0100329norandommap Normally fio will cover every block of the file when doing
330 random IO. If this option is given, fio will just get a
331 new random offset without looking at past io history. This
332 means that some blocks may not be read or written, and that
333 some blocks may be read/written more than once. This option
334 is mutually exclusive with verify= for that reason.
335
Jens Axboe71bfa162006-10-25 11:08:19 +0200336nice=int Run the job with the given nice value. See man nice(2).
337
338prio=int Set the io priority value of this job. Linux limits us to
339 a positive value between 0 and 7, with 0 being the highest.
340 See man ionice(1).
341
342prioclass=int Set the io priority class. See man ionice(1).
343
344thinktime=int Stall the job x microseconds after an io has completed before
345 issuing the next. May be used to simulate processing being
Jens Axboe48097d52007-02-17 06:30:44 +0100346 done by an application. See thinktime_blocks and
347 thinktime_spin.
348
349thinktime_spin=int
350 Only valid if thinktime is set - pretend to spend CPU time
351 doing something with the data received, before falling back
352 to sleeping for the rest of the period specified by
353 thinktime.
Jens Axboe9c1f7432007-01-03 20:43:19 +0100354
355thinktime_blocks
356 Only valid if thinktime is set - control how many blocks
357 to issue, before waiting 'thinktime' usecs. If not set,
358 defaults to 1 which will make fio wait 'thinktime' usecs
359 after every block.
Jens Axboe71bfa162006-10-25 11:08:19 +0200360
361rate=int Cap the bandwidth used by this job to this number of KiB/sec.
362
363ratemin=int Tell fio to do whatever it can to maintain at least this
364 bandwidth.
365
366ratecycle=int Average bandwidth for 'rate' and 'ratemin' over this number
Jens Axboe6c219762006-11-03 15:51:45 +0100367 of milliseconds.
Jens Axboe71bfa162006-10-25 11:08:19 +0200368
369cpumask=int Set the CPU affinity of this job. The parameter given is a
370 bitmask of allowed CPU's the job may run on. See man
371 sched_setaffinity(2).
372
373startdelay=int Start this job the specified number of seconds after fio
374 has started. Only useful if the job file contains several
375 jobs, and you want to delay starting some jobs to a certain
376 time.
377
Jens Axboe03b74b32007-01-11 11:04:31 +0100378runtime=int Tell fio to terminate processing after the specified number
Jens Axboe71bfa162006-10-25 11:08:19 +0200379 of seconds. It can be quite hard to determine for how long
380 a specified job will run, so this parameter is handy to
381 cap the total runtime to a given time.
382
383invalidate=bool Invalidate the buffer/page cache parts for this file prior
384 to starting io. Defaults to true.
385
386sync=bool Use sync io for buffered writes. For the majority of the
387 io engines, this means using O_SYNC.
388
389mem=str Fio can use various types of memory as the io unit buffer.
390 The allowed values are:
391
392 malloc Use memory from malloc(3) as the buffers.
393
394 shm Use shared memory as the buffers. Allocated
395 through shmget(2).
396
Jens Axboe74b025b2006-12-19 15:18:14 +0100397 shmhuge Same as shm, but use huge pages as backing.
398
Jens Axboe313cb202006-12-21 09:50:00 +0100399 mmap Use mmap to allocate buffers. May either be
400 anonymous memory, or can be file backed if
401 a filename is given after the option. The
402 format is mem=mmap:/path/to/file.
Jens Axboe71bfa162006-10-25 11:08:19 +0200403
Jens Axboed0bdaf42006-12-20 14:40:44 +0100404 mmaphuge Use a memory mapped huge file as the buffer
405 backing. Append filename after mmaphuge, ala
406 mem=mmaphuge:/hugetlbfs/file
407
Jens Axboe71bfa162006-10-25 11:08:19 +0200408 The area allocated is a function of the maximum allowed
Jens Axboe5394ae52006-12-20 20:15:41 +0100409 bs size for the job, multiplied by the io depth given. Note
410 that for shmhuge and mmaphuge to work, the system must have
411 free huge pages allocated. This can normally be checked
412 and set by reading/writing /proc/sys/vm/nr_hugepages on a
413 Linux system. Fio assumes a huge page is 4MiB in size. So
414 to calculate the number of huge pages you need for a given
415 job file, add up the io depth of all jobs (normally one unless
416 iodepth= is used) and multiply by the maximum bs set. Then
417 divide that number by the huge page size. You can see the
418 size of the huge pages in /proc/meminfo. If no huge pages
419 are allocated by having a non-zero number in nr_hugepages,
Jens Axboe56bb17f2006-12-20 20:27:36 +0100420 using mmaphuge or shmhuge will fail. Also see hugepage-size.
Jens Axboe5394ae52006-12-20 20:15:41 +0100421
422 mmaphuge also needs to have hugetlbfs mounted and the file
423 location should point there. So if it's mounted in /huge,
424 you would use mem=mmaphuge:/huge/somefile.
Jens Axboe71bfa162006-10-25 11:08:19 +0200425
Jens Axboe56bb17f2006-12-20 20:27:36 +0100426hugepage-size=siint
427 Defines the size of a huge page. Must at least be equal
428 to the system setting, see /proc/meminfo. Defaults to 4MiB.
Jens Axboec51074e2006-12-20 20:28:33 +0100429 Should probably always be a multiple of megabytes, so using
430 hugepage-size=Xm is the preferred way to set this to avoid
431 setting a non-pow-2 bad value.
Jens Axboe56bb17f2006-12-20 20:27:36 +0100432
Jens Axboe71bfa162006-10-25 11:08:19 +0200433exitall When one job finishes, terminate the rest. The default is
434 to wait for each job to finish, sometimes that is not the
435 desired action.
436
437bwavgtime=int Average the calculated bandwidth over the given time. Value
Jens Axboe6c219762006-11-03 15:51:45 +0100438 is specified in milliseconds.
Jens Axboe71bfa162006-10-25 11:08:19 +0200439
440create_serialize=bool If true, serialize the file creating for the jobs.
441 This may be handy to avoid interleaving of data
442 files, which may greatly depend on the filesystem
443 used and even the number of processors in the system.
444
445create_fsync=bool fsync the data file after creation. This is the
446 default.
447
Jens Axboee545a6c2007-01-14 00:00:29 +0100448unlink=bool Unlink the job files when done. Not the default, as repeated
449 runs of that job would then waste time recreating the fileset
450 again and again.
Jens Axboe71bfa162006-10-25 11:08:19 +0200451
452loops=int Run the specified number of iterations of this job. Used
453 to repeat the same workload a given number of times. Defaults
454 to 1.
455
456verify=str If writing to a file, fio can verify the file contents
457 after each iteration of the job. The allowed values are:
458
459 md5 Use an md5 sum of the data area and store
460 it in the header of each block.
461
462 crc32 Use a crc32 sum of the data area and store
463 it in the header of each block.
464
Jens Axboe6c219762006-11-03 15:51:45 +0100465 This option can be used for repeated burn-in tests of a
Jens Axboe71bfa162006-10-25 11:08:19 +0200466 system to make sure that the written data is also
467 correctly read back.
468
469stonewall Wait for preceeding jobs in the job file to exit, before
470 starting this one. Can be used to insert serialization
471 points in the job file.
472
473numjobs=int Create the specified number of clones of this job. May be
474 used to setup a larger number of threads/processes doing
475 the same thing.
476
477thread fio defaults to forking jobs, however if this option is
478 given, fio will use pthread_create(3) to create threads
479 instead.
480
481zonesize=siint Divide a file into zones of the specified size. See zoneskip.
482
483zoneskip=siint Skip the specified number of bytes when zonesize data has
484 been read. The two zone options can be used to only do
485 io on zones of a file.
486
Jens Axboe076efc72006-10-27 11:24:25 +0200487write_iolog=str Write the issued io patterns to the specified file. See
488 read_iolog.
Jens Axboe71bfa162006-10-25 11:08:19 +0200489
Jens Axboe076efc72006-10-27 11:24:25 +0200490read_iolog=str Open an iolog with the specified file name and replay the
Jens Axboe71bfa162006-10-25 11:08:19 +0200491 io patterns it contains. This can be used to store a
492 workload and replay it sometime later.
493
494write_bw_log If given, write a bandwidth log of the jobs in this job
495 file. Can be used to store data of the bandwidth of the
Jens Axboee0da9bc2006-10-25 13:08:57 +0200496 jobs in their lifetime. The included fio_generate_plots
497 script uses gnuplot to turn these text files into nice
498 graphs.
Jens Axboe71bfa162006-10-25 11:08:19 +0200499
500write_lat_log Same as write_bw_log, except that this option stores io
501 completion latencies instead.
502
503lockmem=siint Pin down the specified amount of memory with mlock(2). Can
504 potentially be used instead of removing memory or booting
505 with less memory to simulate a smaller amount of memory.
506
507exec_prerun=str Before running this job, issue the command specified
508 through system(3).
509
510exec_postrun=str After the job completes, issue the command specified
511 though system(3).
512
513ioscheduler=str Attempt to switch the device hosting the file to the specified
514 io scheduler before running.
515
516cpuload=int If the job is a CPU cycle eater, attempt to use the specified
517 percentage of CPU cycles.
518
519cpuchunks=int If the job is a CPU cycle eater, split the load into
Jens Axboe6c219762006-11-03 15:51:45 +0100520 cycles of the given time. In milliseconds.
Jens Axboe71bfa162006-10-25 11:08:19 +0200521
522
5236.0 Interpreting the output
524---------------------------
525
526fio spits out a lot of output. While running, fio will display the
527status of the jobs created. An example of that would be:
528
Jens Axboe73c8b082007-01-11 19:25:52 +0100529Threads: 1: [_r] [24.8% done] [ 13509/ 8334 kb/s] [eta 00h:01m:31s]
Jens Axboe71bfa162006-10-25 11:08:19 +0200530
531The characters inside the square brackets denote the current status of
532each thread. The possible values (in typical life cycle order) are:
533
534Idle Run
535---- ---
536P Thread setup, but not started.
537C Thread created.
538I Thread initialized, waiting.
539 R Running, doing sequential reads.
540 r Running, doing random reads.
541 W Running, doing sequential writes.
542 w Running, doing random writes.
543 M Running, doing mixed sequential reads/writes.
544 m Running, doing mixed random reads/writes.
545 F Running, currently waiting for fsync()
546V Running, doing verification of written data.
547E Thread exited, not reaped by main thread yet.
548_ Thread reaped.
549
550The other values are fairly self explanatory - number of threads
Jens Axboe6043c572006-11-03 11:37:47 +0100551currently running and doing io, rate of io since last check, and the estimated
552completion percentage and time for the running group. It's impossible to
553estimate runtime of the following groups (if any).
Jens Axboe71bfa162006-10-25 11:08:19 +0200554
555When fio is done (or interrupted by ctrl-c), it will show the data for
556each thread, group of threads, and disks in that order. For each data
557direction, the output looks like:
558
559Client1 (g=0): err= 0:
560 write: io= 32MiB, bw= 666KiB/s, runt= 50320msec
Jens Axboe6104ddb2007-01-11 14:24:29 +0100561 slat (msec): min= 0, max= 136, avg= 0.03, stdev= 1.92
562 clat (msec): min= 0, max= 631, avg=48.50, stdev=86.82
563 bw (KiB/s) : min= 0, max= 1196, per=51.00%, avg=664.02, stdev=681.68
Jens Axboe71bfa162006-10-25 11:08:19 +0200564 cpu : usr=1.49%, sys=0.25%, ctx=7969
Jens Axboe71619dc2007-01-13 23:56:33 +0100565 IO depths : 1=0.1%, 2=0.3%, 4=0.5%, 8=99.0%, 16=0.0%, 32=0.0%, >32=0.0%
Jens Axboeec118302007-02-17 04:38:20 +0100566 lat (msec): 2=1.6%, 4=0.0%, 8=3.2%, 16=12.8%, 32=38.4%, 64=24.8%, 128=15.2%
567 lat (msec): 256=4.0%, 512=0.0%, 1024=0.0%, >=2048=0.0%
Jens Axboe71bfa162006-10-25 11:08:19 +0200568
569The client number is printed, along with the group id and error of that
570thread. Below is the io statistics, here for writes. In the order listed,
571they denote:
572
573io= Number of megabytes io performed
574bw= Average bandwidth rate
575runt= The runtime of that thread
576 slat= Submission latency (avg being the average, dev being the
577 standard deviation). This is the time it took to submit
578 the io. For sync io, the slat is really the completion
579 latency, since queue/complete is one operation there.
580 clat= Completion latency. Same names as slat, this denotes the
581 time from submission to completion of the io pieces. For
582 sync io, clat will usually be equal (or very close) to 0,
583 as the time from submit to complete is basically just
584 CPU time (io has already been done, see slat explanation).
585 bw= Bandwidth. Same names as the xlat stats, but also includes
586 an approximate percentage of total aggregate bandwidth
587 this thread received in this group. This last value is
588 only really useful if the threads in this group are on the
589 same disk, since they are then competing for disk access.
590cpu= CPU usage. User and system time, along with the number
591 of context switches this thread went through.
Jens Axboe71619dc2007-01-13 23:56:33 +0100592IO depths= The distribution of io depths over the job life time. The
593 numbers are divided into powers of 2, so for example the
594 16= entries includes depths up to that value but higher
595 than the previous entry. In other words, it covers the
596 range from 16 to 31.
Jens Axboeec118302007-02-17 04:38:20 +0100597IO latencies= The distribution of IO completion latencies. This is the
598 time from when IO leaves fio and when it gets completed.
599 The numbers follow the same pattern as the IO depths,
600 meaning that 2=1.6% means that 1.6% of the IO completed
601 within 2 msecs, 16=12.8% means that 12.8% of the IO
602 took more than 8 msecs, but less than (or equal to) 16 msecs.
Jens Axboe71bfa162006-10-25 11:08:19 +0200603
604After each client has been listed, the group statistics are printed. They
605will look like this:
606
607Run status group 0 (all jobs):
608 READ: io=64MiB, aggrb=22178, minb=11355, maxb=11814, mint=2840msec, maxt=2955msec
609 WRITE: io=64MiB, aggrb=1302, minb=666, maxb=669, mint=50093msec, maxt=50320msec
610
611For each data direction, it prints:
612
613io= Number of megabytes io performed.
614aggrb= Aggregate bandwidth of threads in this group.
615minb= The minimum average bandwidth a thread saw.
616maxb= The maximum average bandwidth a thread saw.
617mint= The smallest runtime of the threads in that group.
618maxt= The longest runtime of the threads in that group.
619
620And finally, the disk statistics are printed. They will look like this:
621
622Disk stats (read/write):
623 sda: ios=16398/16511, merge=30/162, ticks=6853/819634, in_queue=826487, util=100.00%
624
625Each value is printed for both reads and writes, with reads first. The
626numbers denote:
627
628ios= Number of ios performed by all groups.
629merge= Number of merges io the io scheduler.
630ticks= Number of ticks we kept the disk busy.
631io_queue= Total time spent in the disk queue.
632util= The disk utilization. A value of 100% means we kept the disk
633 busy constantly, 50% would be a disk idling half of the time.
634
635
6367.0 Terse output
637----------------
638
639For scripted usage where you typically want to generate tables or graphs
Jens Axboe6c219762006-11-03 15:51:45 +0100640of the results, fio can output the results in a comma separated format.
Jens Axboe71bfa162006-10-25 11:08:19 +0200641The format is one long line of values, such as:
642
643client1,0,0,936,331,2894,0,0,0.000000,0.000000,1,170,22.115385,34.290410,16,714,84.252874%,366.500000,566.417819,3496,1237,2894,0,0,0.000000,0.000000,0,246,6.671625,21.436952,0,2534,55.465300%,1406.600000,2008.044216,0.000000%,0.431928%,1109
644
645Split up, the format is as follows:
646
647 jobname, groupid, error
648 READ status:
649 KiB IO, bandwidth (KiB/sec), runtime (msec)
650 Submission latency: min, max, mean, deviation
651 Completion latency: min, max, mean, deviation
Jens Axboe6c219762006-11-03 15:51:45 +0100652 Bw: min, max, aggregate percentage of total, mean, deviation
Jens Axboe71bfa162006-10-25 11:08:19 +0200653 WRITE status:
654 KiB IO, bandwidth (KiB/sec), runtime (msec)
655 Submission latency: min, max, mean, deviation
656 Completion latency: min, max, mean, deviation
Jens Axboe6c219762006-11-03 15:51:45 +0100657 Bw: min, max, aggregate percentage of total, mean, deviation
Jens Axboe71bfa162006-10-25 11:08:19 +0200658 CPU usage: user, system, context switches
659