X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=HOWTO;h=044b57221f3d18c431e4840bfcbdb21bbab31b2e;hp=14417342761f9e2c39abb7f512a4e60a96c453f9;hb=3e260a46ea9a8de224c3d0a29a608da3440f284a;hpb=9db01ef976006c002b05fa4e4ec589eb029aac5b diff --git a/HOWTO b/HOWTO index 14417342..044b5722 100644 --- a/HOWTO +++ b/HOWTO @@ -9,6 +9,7 @@ Table of contents 6. Normal output 7. Terse output 8. Trace file format +9. CPU idleness profiling 1.0 Overview and history ------------------------ @@ -284,6 +285,32 @@ filename=str Fio normally makes up a filename based on the job name, stdin or stdout. Which of the two depends on the read/write direction set. +filename_format=str + If sharing multiple files between jobs, it is usually necessary + to have fio generate the exact names that you want. By default, + fio will name a file based on the default file format + specification of jobname.jobnumber.filenumber. With this + option, that can be customized. Fio will recognize and replace + the following keywords in this string: + + $jobname + The name of the worker thread or process. + + $jobnum + The incremental number of the worker thread or + process. + + $filenum + The incremental number of the file for that worker + thread or process. + + To have dependent jobs share a set of files, this option can + be set to have fio generate filenames that are shared between + the two. For instance, if testfiles.$filenum is specified, + file number 4 for any job will be named testfiles.4. The + default of $jobname.$jobnum.$filenum will be used if + no other format specifier is given. + opendir=str Tell fio to recursively add any file it can find in this directory and down the file system tree. @@ -301,11 +328,6 @@ lockfile=str Fio defaults to not locking any files before it does same time, but writes get exclusive access. - The option may be post-fixed with a lock batch number. If - set, then each thread/process may do that amount of IOs to - the file before giving up the lock. Since lock acquisition is - expensive, batching the lock/unlocks will speed up IO. - readwrite=str rw=str Type of io pattern. Accepted values are: @@ -409,7 +431,7 @@ filesize=int Individual file sizes. May be a range, in which case fio fill_device=bool fill_fs=bool Sets size to something really large and waits for ENOSPC (no space left on device) as the terminating condition. Only makes - sense with sequential write. For a read workload, the mount + sense with sequential write. For a read workload, the mount point will be filled first then IO started on the result. This option doesn't make sense if operating on a raw device node, since the size of that is already known by the file system. @@ -421,9 +443,11 @@ bs=int The block size used for the io units. Defaults to 4k. Values can be given for both read and writes. If a single int is given, it will apply to both. If a second int is specified after a comma, it will apply to writes only. In other words, - the format is either bs=read_and_write or bs=read,write. - bs=4k,8k will thus use 4k blocks for reads, and 8k blocks - for writes. If you only wish to set the write size, you + the format is either bs=read_and_write or bs=read,write,trim. + bs=4k,8k will thus use 4k blocks for reads, 8k blocks for + writes, and 8k for trims. You can terminate the list with + a trailing comma. bs=4k,8k, would use the default value for + trims.. If you only wish to set the write size, you can do so by passing an empty read size - bs=,8k will set 8k for writes and leave the read default value. @@ -481,6 +505,11 @@ bs_unaligned If this option is given, any byte size value within bsrange may be used as a block range. This typically wont work with direct IO, as that normally requires sector alignment. +bs_is_seq_rand If this option is set, fio will use the normal read,write + blocksize settings as sequential,random instead. Any random + read or write will use the WRITE blocksize settings, and any + sequential read or write will use the READ blocksize setting. + zero_buffers If this option is given, fio will init the IO buffers to all zeroes. The default is to fill them with random data. @@ -546,6 +575,8 @@ ioengine=str Defines how the job issues io to the file. The following vsync Basic readv(2) or writev(2) IO. + psyncv Basic preadv(2) or pwritev(2) IO. + libaio Linux native asynchronous io. Note that Linux may only support queued behaviour with non-buffered IO (set direct=1 or buffered=0). @@ -664,6 +695,11 @@ direct=bool If value is true, use non-buffered io. This is usually O_DIRECT. Note that ZFS on Solaris doesn't support direct io. On Windows the synchronous ioengines don't support direct io. +atomic=bool If value is true, attempt to use atomic direct IO. Atomic + writes are guaranteed to be stable once acknowledged by + the operating system. Only Linux supports O_ATOMIC right + now. + buffered=bool If value is true, use buffered io. This is the opposite of the 'direct' option. Defaults to true. @@ -678,6 +714,13 @@ offset_increment=int If this is provided, then the real offset becomes which are intended to operate on a file in parallel in disjoint segments, with even spacing between the starting points. +number_ios=int Fio will normally perform IOs until it has exhausted the size + of the region set by size=, or if it exhaust the allocated + time (or hits an error condition). With this setting, the + range/size can be set independently of the number of IOs to + perform. When fio reaches this number, it will exit normally + and report status. + fsync=int If writing to a file, issue a sync of the dirty data for every number of blocks given. For example, if you give 32 as a parameter, fio will sync the file for every 32 @@ -744,6 +787,15 @@ random_distribution=str:float By default, fio will use a completely uniform random_distribution=zipf:1.2 as the option. If a non-uniform model is used, fio will disable use of the random map. +percentage_random=int For a random workload, set how big a percentage should + be random. This defaults to 100%, in which case the workload + is fully random. It can be set from anywhere from 0 to 100. + Setting it to 0 would make the workload fully sequential. Any + setting in between will result in a random mix of sequential + and random IO, at the given percentages. It is possible to + set different values for reads, writes, and trim. To do so, + simply use a comma separated list. See blocksize. + norandommap Normally fio will cover every block of the file when doing random IO. If this option is given, fio will just get a new random offset without looking at past io history. This @@ -775,7 +827,7 @@ random_generator=str Fio supports the following engines for generating block sizes, not with workloads that use multiple block sizes. If used with such a workload, fio may read or write some blocks multiple times. - + nice=int Run the job with the given nice value. See man nice(2). prio=int Set the io priority value of this job. Linux limits us to @@ -795,11 +847,15 @@ thinktime_spin=int to sleeping for the rest of the period specified by thinktime. -thinktime_blocks +thinktime_blocks=int Only valid if thinktime is set - control how many blocks to issue, before waiting 'thinktime' usecs. If not set, defaults to 1 which will make fio wait 'thinktime' usecs - after every block. + after every block. This effectively makes any queue depth + setting redundant, since no more than 1 IO will be queued + before we have to complete it and do our thinktime. In + other words, this setting effectively caps the queue depth + if the latter is larger. rate=int Cap the bandwidth used by this job. The number is in bytes/sec, the normal suffix rules apply. You can use rate=500k to limit @@ -819,11 +875,25 @@ rate_iops=int Cap the bandwidth to this number of IOPS. Basically the same as rate, just specified independently of bandwidth. If the job is given a block size range instead of a fixed value, the smallest block size is used as the metric. The same format - as rate is used for read vs write seperation. + as rate is used for read vs write separation. rate_iops_min=int If fio doesn't meet this rate of IO, it will cause the job to exit. The same format as rate is used for read vs - write seperation. + write separation. + +latency_target=int If set, fio will attempt to find the max performance + point that the given workload will run at while maintaining a + latency below this target. The values is given in microseconds. + See latency_window and latency_percentile + +latency_window=int Used with latency_target to specify the sample window + that the job is run at varying queue depths to test the + performance. The value is given in microseconds. + +latency_percentile=float The percentage of IOs that must fall within the + criteria specified by latency_target and latency_window. If not + set, this defaults to 100.0, meaning that all IOs must be equal + or below to the value set by latency_target. max_latency=int If set, fio will exit the job if it exceeds this maximum latency. It will exit with an ETIME error. @@ -1100,9 +1170,6 @@ verify_backlog=int Fio will normally verify the written contents of a holding this meta data. If this option is enabled, fio will write only N blocks before verifying these blocks. - will verify the previously written blocks before continuing - to write new ones. - verify_backlog_batch=int Control how many blocks fio will verify if verify_backlog is set. If not set, will default to the value of verify_backlog (meaning the entire queue @@ -1112,7 +1179,7 @@ verify_backlog_batch=int Control how many blocks fio will verify blocks will be verified more than once. stonewall -wait_for_previous Wait for preceeding jobs in the job file to exit, before +wait_for_previous Wait for preceding jobs in the job file to exit, before starting this one. Can be used to insert serialization points in the job file. A stone wall also implies starting a new reporting group. @@ -1168,7 +1235,7 @@ replay_no_stall=int When replaying I/O with read_iolog the default behavior replay_redirect=str While replaying I/O patterns using read_iolog the default behavior is to replay the IOPS onto the major/minor device that each IOP was recorded from. This is sometimes - undesireable because on a different machine those major/minor + undesirable because on a different machine those major/minor numbers can map to a different device. Changing hardware on the same system can also result in a different major/minor mapping. Replay_redirect causes all IOPS to be replayed onto @@ -1197,13 +1264,10 @@ write_lat_log=str Same as write_bw_log, except that this option stores io write_lat_log=foo - The actual log names will be foo_slat.log, foo_slat.log, + The actual log names will be foo_slat.log, foo_clat.log, and foo_lat.log. This helps fio_generate_plot fine the logs automatically. -write_bw_log=str If given, write an IOPS log of the jobs in this job - file. See write_bw_log. - write_iops_log=str Same as write_bw_log, but writes IOPS. If no filename is given with this option, the default filename of "jobname_type.log" is used. Even if the filename is given, @@ -1219,12 +1283,15 @@ log_avg_msec=int By default, fio will log an entry in the iops, latency, lockmem=int Pin down the specified amount of memory with mlock(2). Can potentially be used instead of removing memory or booting with less memory to simulate a smaller amount of memory. + The amount specified is per worker. exec_prerun=str Before running this job, issue the command specified - through system(3). + through system(3). Output is redirected in a file called + jobname.prerun.txt. exec_postrun=str After the job completes, issue the command specified - though system(3). + though system(3). Output is redirected in a file called + jobname.postrun.txt. ioscheduler=str Attempt to switch the device hosting the file to the specified io scheduler before running. @@ -1396,11 +1463,20 @@ that defines them is selected. [netsplice] hostname=str [net] hostname=str The host name or IP address to use for TCP or UDP based IO. If the job is a TCP listener or UDP reader, the hostname is not - used and must be omitted. + used and must be omitted unless it is a valid UDP multicast + address. [netsplice] port=int [net] port=int The TCP or UDP port to bind to or connect to. +[netsplice] interface=str +[net] interface=str The IP address of the network interface used to send or + receive UDP multicast + +[netsplice] ttl=int +[net] ttl=int Time-to-live value for outgoing UDP multicast packets. + Default: 1 + [netsplice] nodelay=bool [net] nodelay=bool Set TCP_NODELAY on TCP connections. @@ -1421,7 +1497,7 @@ that defines them is selected. [net] listen For TCP network connections, tell fio to listen for incoming connections rather than initiating an outgoing connection. The hostname must be omitted if this option is used. -[net] pingpong Normal a network writer will just continue writing data, and +[net] pingpong Normaly a network writer will just continue writing data, and a network reader will just consume packages. If pingpong=1 is set, a writer will send its normal payload to the reader, then wait for the reader to send the same payload back. This @@ -1429,6 +1505,9 @@ that defines them is selected. and completion latencies then measure local time spent sending or receiving, and the completion latency measures how long it took for the other end to receive and send back. + For UDP multicast traffic pingpong=1 should only be set for a + single reader when multiple readers are listening to the same + address. [e4defrag] donorname=str File will be used as a block donor(swap extents between files) @@ -1577,6 +1656,9 @@ util= The disk utilization. A value of 100% means we kept the disk It is also possible to get fio to dump the current output while it is running, without terminating the job. To do that, send fio the USR1 signal. +You can also get regularly timed dumps by using the --status-interval +parameter, or by creating a file in /tmp named fio-dump-status. If fio +sees this file, it will unlink it and dump the current output status. 7.0 Terse output @@ -1621,9 +1703,9 @@ Split up, the format is as follows: Read merges, write merges, Read ticks, write ticks, Time spent in queue, disk utilization percentage - Additional Info (dependant on continue_on_error, default off): total # errors, first error code + Additional Info (dependent on continue_on_error, default off): total # errors, first error code - Additional Info (dependant on description being set): Text description + Additional Info (dependent on description being set): Text description Completion latency percentiles can be a grouping of up to 20 sets, so for the terse output fio writes all of them. Each field will look like this: @@ -1698,7 +1780,7 @@ trim trim the given file from the given 'offset' for 'length' bytes 9.0 CPU idleness profiling - +-------------------------- In some cases, we want to understand CPU overhead in a test. For example, we test patches for the specific goodness of whether they reduce CPU usage. fio implements a balloon approach to create a thread per CPU that runs at