Flexible I/O Tester
Clone or download
axboe stat: print the right percentile variant for json output
We always show the clat percentiles for the json output, regardless
of whether lat_percentiles or clat_percentiles was defined in the
job. Correct that so we show the right output depending on the
job setting.

Fixes: #691
Signed-off-by: Jens Axboe <axboe@kernel.dk>
Latest commit 9f2cd5e Sep 22, 2018
Permalink
Failed to load latest commit information.
arch arch: fix build breakage on armv6 Aug 12, 2018
compiler replace typeof with __typeof__ Jul 25, 2018
crc xxhash: fix function definition and declaration mismatch Aug 9, 2018
doc design document for tools/hist/fio-histo-log-pctiles.py Jul 25, 2018
engines engines/http: work-around crash in certain libssl versions Sep 21, 2018
examples Kill fusion atomic write engine Sep 8, 2018
exp fio: update FSF address Oct 29, 2017
lib Random distribution 32-bit fixes Sep 17, 2018
os windows: make win_to_posix_error() more resilient Sep 12, 2018
oslib asprintf: fix indentation Aug 13, 2018
profiles Rename fio_mutex into fio_sem Mar 15, 2018
t t/axmap: use a 64-bit type (not size_t) for axmap tests Sep 17, 2018
tools Merge branch 'epoch-time-hist-logs' of https://github.com/parallel-fs… Sep 19, 2018
.appveyor.yml Rename appveyor.yml into .appveyor.yml Jun 5, 2018
.gitignore .gitignore: ignore tags files and additional output binaries Dec 14, 2017
.travis.yml travis: include new xcode 9.4 Aug 12, 2018
COPYING COPYING: update license file Oct 29, 2017
FIO-VERSION-GEN Fio 3.10 Sep 11, 2018
GFIO-TODO gfio: update TODO Mar 13, 2012
HOWTO docs: clarify usage of steadystate detection feature Sep 21, 2018
MORAL-LICENSE Moral license update Feb 6, 2015
Makefile build: change where we set -static for Windows Sep 15, 2018
README doc: add Windows processor group behaviour and Windows target option Mar 27, 2018
REPORTING-BUGS Update REPORTING-BUGS Oct 14, 2016
SERVER-TODO Add disk utilization to terse format output Oct 13, 2011
STEADYSTATE-TODO steadystate: rename TODO to STEADYSTATE-TODO Dec 7, 2016
backend.c log: remember to free output buffer when done Sep 7, 2018
blktrace.c blktrace: fix leak of 'merge_buf' Sep 20, 2018
blktrace.h blktrace: provide empty merge_blktrace_iologs() Sep 20, 2018
blktrace_api.h blktrace: change barrier to a flush Apr 26, 2018
cairo_text_helpers.c cairo_text_helpers: fix left justified text Mar 28, 2012
cairo_text_helpers.h White space spring cleaning Mar 27, 2012
cconv.c blktrace: add option to iterate over a trace multiple times Sep 20, 2018
cgroup.c fio: work with cgroup2 as well Jun 29, 2018
cgroup.h Fix compilation without cgroups Jun 29, 2018
client.c client: cleanup output types Sep 7, 2018
client.h client: switch to per-client buffer Sep 7, 2018
configure build: change where we set -static for Windows Sep 15, 2018
debug.c Refactor #includes and headers Mar 21, 2018
debug.h Add the 'zbd' debug level Aug 24, 2018
diskutil.c init: add semantics for all types of backends running Aug 23, 2018
diskutil.h Refactor #includes and headers Mar 21, 2018
err.h Make err.h a bit more Windows friendly Feb 12, 2014
eta.c eta: clean up ETA string printing Aug 10, 2018
fifo.c Refactor #includes and headers Mar 21, 2018
fifo.h Refactor #includes and headers Mar 21, 2018
file.h Add support for zoned block devices Aug 24, 2018
filehash.c Rename fio_mutex into fio_sem Mar 15, 2018
filehash.h filehash: move to separate allocation Sep 26, 2016
filelock.c Rename fio_mutex into fio_sem Mar 15, 2018
filelock.h filelock: bool conversion Aug 29, 2016
filesetup.c filesetup: use 64-bit type for file size generation Sep 17, 2018
fio.1 docs: clarify usage of steadystate detection feature Sep 21, 2018
fio.c Refactor #includes and headers Mar 21, 2018
fio.h Make td_io_u_lock/unlock() explicit Aug 25, 2018
fio_sem.c Refactor #includes and headers Mar 21, 2018
fio_sem.h Rename fio_mutex into fio_sem Mar 15, 2018
fio_time.h Add include-what-you-use pragmas Mar 21, 2018
flist.h replace typeof with __typeof__ Jul 25, 2018
flow.c Rename fio_mutex into fio_sem Mar 15, 2018
flow.h Token-based flow control Feb 20, 2012
gclient.c gclient: bump output time buf size Aug 13, 2018
gclient.h gfio: add and colorize graphs on main page, too Sep 25, 2012
gcompat.c gcompat: gtk_widget_set_can_focus() for below 2.18 Mar 26, 2012
gcompat.h White space spring cleaning Mar 27, 2012
gerror.c Use stdlib.h instead of malloc.h Jul 23, 2018
gerror.h gfio: split some parts into gclient.c Mar 21, 2012
gettime-thread.c smalloc: oom cleanups Mar 22, 2018
gettime.c gettime: remove 'is_thread' variable to local clock init Jun 5, 2018
gettime.h gettime: remove 'is_thread' variable to local clock init Jun 5, 2018
gfio.c gfio: cleanup includes Jul 23, 2018
gfio.h gfio: add trim UI support Sep 24, 2012
ghelpers.c gfio: add and colorize graphs on main page, too Sep 25, 2012
ghelpers.h gfio: add and colorize graphs on main page, too Sep 25, 2012
goptions.c Use stdlib.h instead of malloc.h Jul 23, 2018
goptions.h gfio: add per-job option view Mar 24, 2012
graph.c Use stdlib.h instead of malloc.h Jul 23, 2018
graph.h gfio: clear graphs for repeated runs on same connection Sep 26, 2012
hash.h hash: make 64-bit even on 32-bit May 25, 2016
helper_thread.c Suppress uninteresting data race reports Mar 15, 2018
helper_thread.h Rename fio_mutex into fio_sem Mar 15, 2018
helpers.c Refactor #includes and headers Mar 21, 2018
helpers.h Refactor #includes and headers Mar 21, 2018
idletime.c idle-prof: Fix segment fault issue when run with '--idle-prof' and mu… Jun 8, 2018
idletime.h idle-prof: Fix segment fault issue when run with '--idle-prof' and mu… Jun 8, 2018
init.c blktrace: add support to interleave blktrace files Sep 20, 2018
io_ddir.h io_ddir: revert separate ddir count change Jan 25, 2018
io_u.c Make td_io_u_lock/unlock() explicit Aug 25, 2018
io_u.h Introduce the io_u.post_submit callback function pointer Aug 24, 2018
io_u_queue.c io_u_queue: convert rings to bool Nov 2, 2017
io_u_queue.h Refactor #includes and headers Mar 21, 2018
ioengines.c Add support for zoned block devices Aug 24, 2018
ioengines.h Introduce enum fio_q_status Apr 18, 2018
iolog.c iolog: Ensure that sockaddr_un.sun_path is '\0'-terminated Sep 7, 2018
iolog.h iolog replay: Realloc io_u buffers to adapt to operation size. Aug 9, 2018
json.c Refactor #includes and headers Mar 21, 2018
json.h Refactor #includes and headers Mar 21, 2018
libfio.c Fix issue with rate_process=poisson and ramp time Jun 4, 2018
log.c log: fix signedness issue Jun 5, 2018
log.h Fix compilation on centos 7 Aug 15, 2018
memory.c Refactor #includes and headers Mar 21, 2018
minmax.h replace typeof with __typeof__ Jul 25, 2018
optgroup.c optgroup: move debug code into function Mar 20, 2018
optgroup.h engines/http: Add support for WebDAV and S3 Aug 14, 2018
options.c blktrace: add option to iterate over a trace multiple times Sep 20, 2018
options.h options: rename name string operations for more general use Sep 20, 2018
parse.c Fix the typehelp[] array Aug 25, 2018
parse.h Add support for >= 4G block sizes Jul 23, 2018
printing.c printing: use bigger on-stack buffer Aug 16, 2017
printing.h gfio: Add "print" option for results page. Mar 27, 2012
profile.c parse: get rid of raw option offsets Feb 11, 2014
profile.h Remove prof_io_ops.fill_io_u_off(), .fill_io_u_size() and .get_next_f… Mar 9, 2018
pshared.c Split mutex.c and .h each into three files Mar 15, 2018
pshared.h Split mutex.c and .h each into three files Mar 15, 2018
rate-submit.c rate_submit: synchronize accesses to io_u_queue->nr Sep 11, 2018
rate-submit.h Fixup and improve per-thread data Dec 11, 2015
rwlock.c Improve Valgrind instrumentation of memory allocations Mar 15, 2018
rwlock.h Split mutex.c and .h each into three files Mar 15, 2018
server.c Add support for >= 4G block sizes Jul 23, 2018
server.h blktrace: add option to iterate over a trace multiple times Sep 20, 2018
smalloc.c smalloc: Remove Valgrind instrumentation Mar 23, 2018
smalloc.h Refactor #includes and headers Mar 21, 2018
stat.c stat: print the right percentile variant for json output Sep 22, 2018
stat.h Collect and show zone reset statistics Aug 24, 2018
steadystate.c Make td_io_u_lock/unlock() explicit Aug 25, 2018
steadystate.h Refactor #includes and headers Mar 21, 2018
td_error.c use ARRAY_SIZE() for ignore_error_nr[etype] Jun 7, 2017
td_error.h Refactor #includes and headers Mar 21, 2018
thread_options.h blktrace: add option to iterate over a trace multiple times Sep 20, 2018
tickmarks.c Use stdlib.h instead of malloc.h Jul 23, 2018
tickmarks.h gfio: graphing updates Mar 14, 2012
time.c time: use bool for ramp time Sep 13, 2017
trim.c Refactor #includes and headers Mar 21, 2018
trim.h Refactor #includes and headers Mar 21, 2018
verify-state.h Move nowarn_snprintf.h to lib/ Jun 5, 2018
verify.c Merge branch 'fio-c++-engine' of https://github.com/tchaikov/fio Jul 25, 2018
verify.h Refactor #includes and headers Mar 21, 2018
workqueue.c Split mutex.c and .h each into three files Mar 15, 2018
workqueue.h Refactor #includes and headers Mar 21, 2018
zbd.c zbd: fix various 32-bit compilation warnings Sep 17, 2018
zbd.h zbd: Remove inexistent functions declaration Sep 6, 2018
zone-dist.c Fix double free of zone cache data Aug 14, 2018
zone-dist.h Fix double free of zone cache data Aug 14, 2018

README

Overview and history
--------------------

Fio was originally written to save me the hassle of writing special test case
programs when I wanted to test a specific workload, either for performance
reasons or to find/reproduce a bug. The process of writing such a test app can
be tiresome, especially if you have to do it often.  Hence I needed a tool that
would be able to simulate a given I/O workload without resorting to writing a
tailored test case again and again.

A test work load is difficult to define, though. There can be any number of
processes or threads involved, and they can each be using their own way of
generating I/O. You could have someone dirtying large amounts of memory in an
memory mapped file, or maybe several threads issuing reads using asynchronous
I/O. fio needed to be flexible enough to simulate both of these cases, and many
more.

Fio spawns a number of threads or processes doing a particular type of I/O
action as specified by the user. fio takes a number of global parameters, each
inherited by the thread unless otherwise parameters given to them overriding
that setting is given.  The typical use of fio is to write a job file matching
the I/O load one wants to simulate.


Source
------

Fio resides in a git repo, the canonical place is:

	git://git.kernel.dk/fio.git

When inside a corporate firewall, git:// URL sometimes does not work.
If git:// does not work, use the http protocol instead:

	http://git.kernel.dk/fio.git

Snapshots are frequently generated and :file:`fio-git-*.tar.gz` include the git
meta data as well. Other tarballs are archives of official fio releases.
Snapshots can download from:

	http://brick.kernel.dk/snaps/

There are also two official mirrors. Both of these are automatically synced with
the main repository, when changes are pushed. If the main repo is down for some
reason, either one of these is safe to use as a backup:

	git://git.kernel.org/pub/scm/linux/kernel/git/axboe/fio.git

	https://git.kernel.org/pub/scm/linux/kernel/git/axboe/fio.git

or

	git://github.com/axboe/fio.git

	https://github.com/axboe/fio.git


Mailing list
------------

The fio project mailing list is meant for anything related to fio including
general discussion, bug reporting, questions, and development. For bug reporting,
see REPORTING-BUGS.

An automated mail detailing recent commits is automatically sent to the list at
most daily. The list address is fio@vger.kernel.org, subscribe by sending an
email to majordomo@vger.kernel.org with

	subscribe fio

in the body of the email. Archives can be found here:

	http://www.spinics.net/lists/fio/

and archives for the old list can be found here:

	http://maillist.kernel.dk/fio-devel/


Author
------

Fio was written by Jens Axboe <axboe@kernel.dk> to enable flexible testing of
the Linux I/O subsystem and schedulers. He got tired of writing specific test
applications to simulate a given workload, and found that the existing I/O
benchmark/test tools out there weren't flexible enough to do what he wanted.

Jens Axboe <axboe@kernel.dk> 20060905


Binary packages
---------------

Debian:
	Starting with Debian "Squeeze", fio packages are part of the official
	Debian repository. http://packages.debian.org/search?keywords=fio .

Ubuntu:
	Starting with Ubuntu 10.04 LTS (aka "Lucid Lynx"), fio packages are part
	of the Ubuntu "universe" repository.
	http://packages.ubuntu.com/search?keywords=fio .

Red Hat, Fedora, CentOS & Co:
	Starting with Fedora 9/Extra Packages for Enterprise Linux 4, fio
	packages are part of the Fedora/EPEL repositories.
	https://apps.fedoraproject.org/packages/fio .

Mandriva:
	Mandriva has integrated fio into their package repository, so installing
	on that distro should be as easy as typing ``urpmi fio``.

Arch Linux:
        An Arch Linux package is provided under the Community sub-repository:
        https://www.archlinux.org/packages/?sort=&q=fio

Solaris:
	Packages for Solaris are available from OpenCSW. Install their pkgutil
	tool (http://www.opencsw.org/get-it/pkgutil/) and then install fio via
	``pkgutil -i fio``.

Windows:
	Rebecca Cran <rebecca+fio@bluestop.org> has fio packages for Windows at
	https://www.bluestop.org/fio/ . The latest builds for Windows can also
	be grabbed from https://ci.appveyor.com/project/axboe/fio by clicking
	the latest x86 or x64 build, then selecting the ARTIFACTS tab.

BSDs:
	Packages for BSDs may be available from their binary package repositories.
	Look for a package "fio" using their binary package managers.


Building
--------

Just type::

 $ ./configure
 $ make
 $ make install

Note that GNU make is required. On BSDs it's available from devel/gmake within
ports directory; on Solaris it's in the SUNWgmake package.  On platforms where
GNU make isn't the default, type ``gmake`` instead of ``make``.

Configure will print the enabled options. Note that on Linux based platforms,
the libaio development packages must be installed to use the libaio
engine. Depending on distro, it is usually called libaio-devel or libaio-dev.

For gfio, gtk 2.18 (or newer), associated glib threads, and cairo are required
to be installed.  gfio isn't built automatically and can be enabled with a
``--enable-gfio`` option to configure.

To build fio with a cross-compiler::

 $ make clean
 $ make CROSS_COMPILE=/path/to/toolchain/prefix

Configure will attempt to determine the target platform automatically.

It's possible to build fio for ESX as well, use the ``--esx`` switch to
configure.


Windows
~~~~~~~

On Windows, Cygwin (http://www.cygwin.com/) is required in order to build
fio. To create an MSI installer package install WiX 3.8 from
http://wixtoolset.org and run :file:`dobuild.cmd` from the :file:`os/windows`
directory.

How to compile fio on 64-bit Windows:

 1. Install Cygwin (http://www.cygwin.com/). Install **make** and all
    packages starting with **mingw64-x86_64**. Ensure
    **mingw64-x86_64-zlib** are installed if you wish
    to enable fio's log compression functionality.
 2. Open the Cygwin Terminal.
 3. Go to the fio directory (source files).
 4. Run ``make clean && make -j``.

To build fio for 32-bit Windows, ensure the -i686 versions of the previously
mentioned -x86_64 packages are installed and run ``./configure
--build-32bit-win`` before ``make``. To build an fio that supports versions of
Windows below Windows 7/Windows Server 2008 R2 also add ``--target-win-ver=xp``
to the end of the configure line that you run before doing ``make``.

It's recommended that once built or installed, fio be run in a Command Prompt or
other 'native' console such as console2, since there are known to be display and
signal issues when running it under a Cygwin shell (see
https://github.com/mintty/mintty/issues/56 and
https://github.com/mintty/mintty/wiki/Tips#inputoutput-interaction-with-alien-programs
for details).


Documentation
~~~~~~~~~~~~~

Fio uses Sphinx_ to generate documentation from the reStructuredText_ files.
To build HTML formatted documentation run ``make -C doc html`` and direct your
browser to :file:`./doc/output/html/index.html`.  To build manual page run
``make -C doc man`` and then ``man doc/output/man/fio.1``.  To see what other
output formats are supported run ``make -C doc help``.

.. _reStructuredText: http://www.sphinx-doc.org/rest.html
.. _Sphinx: http://www.sphinx-doc.org


Platforms
---------

Fio works on (at least) Linux, Solaris, AIX, HP-UX, OSX, NetBSD, OpenBSD,
Windows, FreeBSD, and DragonFly. Some features and/or options may only be
available on some of the platforms, typically because those features only apply
to that platform (like the solarisaio engine, or the splice engine on Linux).

Some features are not available on FreeBSD/Solaris even if they could be
implemented, I'd be happy to take patches for that. An example of that is disk
utility statistics and (I think) huge page support, support for that does exist
in FreeBSD/Solaris.

Fio uses pthread mutexes for signalling and locking and some platforms do not
support process shared pthread mutexes. As a result, on such platforms only
threads are supported. This could be fixed with sysv ipc locking or other
locking alternatives.

Other \*BSD platforms are untested, but fio should work there almost out of the
box. Since I don't do test runs or even compiles on those platforms, your
mileage may vary. Sending me patches for other platforms is greatly
appreciated. There's a lot of value in having the same test/benchmark tool
available on all platforms.

Note that POSIX aio is not enabled by default on AIX. Messages like these::

    Symbol resolution failed for /usr/lib/libc.a(posix_aio.o) because:
        Symbol _posix_kaio_rdwr (number 2) is not exported from dependent module /unix.

indicate one needs to enable POSIX aio. Run the following commands as root::

    # lsdev -C -l posix_aio0
        posix_aio0 Defined  Posix Asynchronous I/O
    # cfgmgr -l posix_aio0
    # lsdev -C -l posix_aio0
        posix_aio0 Available  Posix Asynchronous I/O

POSIX aio should work now. To make the change permanent::

    # chdev -l posix_aio0 -P -a autoconfig='available'
        posix_aio0 changed


Running fio
-----------

Running fio is normally the easiest part - you just give it the job file
(or job files) as parameters::

	$ fio [options] [jobfile] ...

and it will start doing what the *jobfile* tells it to do. You can give more
than one job file on the command line, fio will serialize the running of those
files. Internally that is the same as using the :option:`stonewall` parameter
described in the parameter section.

If the job file contains only one job, you may as well just give the parameters
on the command line. The command line parameters are identical to the job
parameters, with a few extra that control global parameters.  For example, for
the job file parameter :option:`iodepth=2 <iodepth>`, the mirror command line
option would be :option:`--iodepth 2 <iodepth>` or :option:`--iodepth=2
<iodepth>`. You can also use the command line for giving more than one job
entry. For each :option:`--name <name>` option that fio sees, it will start a
new job with that name.  Command line entries following a
:option:`--name <name>` entry will apply to that job, until there are no more
entries or a new :option:`--name <name>` entry is seen. This is similar to the
job file options, where each option applies to the current job until a new []
job entry is seen.

fio does not need to run as root, except if the files or devices specified in
the job section requires that. Some other options may also be restricted, such
as memory locking, I/O scheduler switching, and decreasing the nice value.

If *jobfile* is specified as ``-``, the job file will be read from standard
input.