X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=fio.1;h=df140cfe4ee0a06deaf5c81cc3349be7b00e9d6c;hp=246bcd25d22c050e3a8c7054fba3a4277105035d;hb=dedb88eb2e4f074fd969133dbdc38ef3be64800b;hpb=e6989e10964f5ae30e0ba8f0cd27a663baf5617b diff --git a/fio.1 b/fio.1 index 246bcd25..df140cfe 100644 --- a/fio.1 +++ b/fio.1 @@ -591,6 +591,9 @@ coalescing adjacent IOs into a single submission. .B pvsync Basic \fBpreadv\fR\|(2) or \fBpwritev\fR\|(2) I/O. .TP +.B pvsync2 +Basic \fBpreadv2\fR\|(2) or \fBpwritev2\fR\|(2) I/O. +.TP .B libaio Linux native asynchronous I/O. This ioengine defines engine specific options. .TP @@ -871,15 +874,51 @@ Zipf distribution .B pareto Pareto distribution .TP +.B gauss +Normal (gaussian) distribution +.TP +.B zoned +Zoned random distribution +.TP .RE -.P -When using a zipf or pareto distribution, an input value is also needed to -define the access pattern. For zipf, this is the zipf theta. For pareto, -it's the pareto power. Fio includes a test program, genzipf, that can be -used visualize what the given input values will yield in terms of hit rates. -If you wanted to use zipf with a theta of 1.2, you would use +When using a \fBzipf\fR or \fBpareto\fR distribution, an input value is also +needed to define the access pattern. For \fBzipf\fR, this is the zipf theta. +For \fBpareto\fR, it's the pareto power. Fio includes a test program, genzipf, +that can be used visualize what the given input values will yield in terms of +hit rates. If you wanted to use \fBzipf\fR with a theta of 1.2, you would use random_distribution=zipf:1.2 as the option. If a non-uniform model is used, -fio will disable use of the random map. +fio will disable use of the random map. For the \fBgauss\fR distribution, a +normal deviation is supplied as a value between 0 and 100. +.P +.RS +For a \fBzoned\fR distribution, fio supports specifying percentages of IO +access that should fall within what range of the file or device. For example, +given a criteria of: +.P +.RS +60% of accesses should be to the first 10% +.RE +.RS +30% of accesses should be to the next 20% +.RE +.RS +8% of accesses should be to to the next 30% +.RE +.RS +2% of accesses should be to the next 40% +.RE +.P +we can define that through zoning of the random accesses. For the above +example, the user would do: +.P +.RS +.B random_distribution=zoned:60/10:30/20:8/30:2/40 +.RE +.P +similarly to how \fBbssplit\fR works for setting ranges and percentages of block +sizes. Like \fBbssplit\fR, it's possible to specify separate zones for reads, +writes, and trims. If just one set is given, it'll apply to all of them. +.RE .TP .BI percentage_random \fR=\fPint For a random workload, set how big a percentage should be random. This defaults @@ -1402,7 +1441,8 @@ fio_generate_plots script uses gnuplot to turn these text files into nice graphs. See \fBwrite_lat_log\fR for behaviour of given filename. For this option, the postfix is _bw.x.log, where x is the index of the job (1..N, where N is the number of jobs). If \fBper_job_logs\fR is false, then the -filename will not include the job index. +filename will not include the job index. See the \fBLOG FILE FORMATS\fR +section. .TP .BI write_lat_log \fR=\fPstr Same as \fBwrite_bw_log\fR, but writes I/O completion latencies. If no @@ -1410,14 +1450,15 @@ filename is given with this option, the default filename of "jobname_type.x.log" is used, where x is the index of the job (1..N, where N is the number of jobs). Even if the filename is given, fio will still append the type of log. If \fBper_job_logs\fR is false, then the filename will -not include the job index. +not include the job index. See the \fBLOG FILE FORMATS\fR section. .TP .BI write_iops_log \fR=\fPstr Same as \fBwrite_bw_log\fR, but writes IOPS. If no filename is given with this option, the default filename of "jobname_type.x.log" is used, where x is the index of the job (1..N, where N is the number of jobs). Even if the filename is given, fio will still append the type of log. If \fBper_job_logs\fR is false, -then the filename will not include the job index. +then the filename will not include the job index. See the \fBLOG FILE FORMATS\fR +section. .TP .BI log_avg_msec \fR=\fPint By default, fio will log an entry in the iops, latency, or bw log for every @@ -1647,6 +1688,10 @@ from user-space to reap events. The reaping mode is only enabled when polling for a minimum of 0 events (eg when iodepth_batch_complete=0). .TP +.BI (psyncv2)hipri +Set RWF_HIPRI on IO, indicating to the kernel that it's of +higher priority than normal. +.TP .BI (net,netsplice)hostname \fR=\fPstr 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 @@ -1988,6 +2033,246 @@ Error Info (dependent on continue_on_error, default off): .P .B text description (if provided in config - appears on newline) .RE +.SH TRACE FILE FORMAT +There are two trace file format that you can encounter. The older (v1) format +is unsupported since version 1.20-rc3 (March 2008). It will still be described +below in case that you get an old trace and want to understand it. + +In any case the trace is a simple text file with a single action per line. + +.P +.B Trace file format v1 +.RS +Each line represents a single io action in the following format: + +rw, offset, length + +where rw=0/1 for read/write, and the offset and length entries being in bytes. + +This format is not supported in Fio versions => 1.20-rc3. + +.RE +.P +.B Trace file format v2 +.RS +The second version of the trace file format was added in Fio version 1.17. +It allows to access more then one file per trace and has a bigger set of +possible file actions. + +The first line of the trace file has to be: + +\fBfio version 2 iolog\fR + +Following this can be lines in two different formats, which are described below. +The file management format: + +\fBfilename action\fR + +The filename is given as an absolute path. The action can be one of these: + +.P +.PD 0 +.RS +.TP +.B add +Add the given filename to the trace +.TP +.B open +Open the file with the given filename. The filename has to have been previously +added with the \fBadd\fR action. +.TP +.B close +Close the file with the given filename. The file must have previously been +opened. +.RE +.PD +.P + +The file io action format: + +\fBfilename action offset length\fR + +The filename is given as an absolute path, and has to have been added and opened +before it can be used with this format. The offset and length are given in +bytes. The action can be one of these: + +.P +.PD 0 +.RS +.TP +.B wait +Wait for 'offset' microseconds. Everything below 100 is discarded. The time is +relative to the previous wait statement. +.TP +.B read +Read \fBlength\fR bytes beginning from \fBoffset\fR +.TP +.B write +Write \fBlength\fR bytes beginning from \fBoffset\fR +.TP +.B sync +fsync() the file +.TP +.B datasync +fdatasync() the file +.TP +.B trim +trim the given file from the given \fBoffset\fR for \fBlength\fR bytes +.RE +.PD +.P + +.SH 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 +idle priority, meaning that it only runs when nobody else needs the cpu. +By measuring the amount of work completed by the thread, idleness of each +CPU can be derived accordingly. + +An unit work is defined as touching a full page of unsigned characters. Mean +and standard deviation of time to complete an unit work is reported in "unit +work" section. Options can be chosen to report detailed percpu idleness or +overall system idleness by aggregating percpu stats. + +.SH VERIFICATION AND TRIGGERS +Fio is usually run in one of two ways, when data verification is done. The +first is a normal write job of some sort with verify enabled. When the +write phase has completed, fio switches to reads and verifies everything +it wrote. The second model is running just the write phase, and then later +on running the same job (but with reads instead of writes) to repeat the +same IO patterns and verify the contents. Both of these methods depend +on the write phase being completed, as fio otherwise has no idea how much +data was written. + +With verification triggers, fio supports dumping the current write state +to local files. Then a subsequent read verify workload can load this state +and know exactly where to stop. This is useful for testing cases where +power is cut to a server in a managed fashion, for instance. + +A verification trigger consists of two things: + +.RS +Storing the write state of each job +.LP +Executing a trigger command +.RE + +The write state is relatively small, on the order of hundreds of bytes +to single kilobytes. It contains information on the number of completions +done, the last X completions, etc. + +A trigger is invoked either through creation (\fBtouch\fR) of a specified +file in the system, or through a timeout setting. If fio is run with +\fB\-\-trigger\-file=/tmp/trigger-file\fR, then it will continually check for +the existence of /tmp/trigger-file. When it sees this file, it will +fire off the trigger (thus saving state, and executing the trigger +command). + +For client/server runs, there's both a local and remote trigger. If +fio is running as a server backend, it will send the job states back +to the client for safe storage, then execute the remote trigger, if +specified. If a local trigger is specified, the server will still send +back the write state, but the client will then execute the trigger. + +.RE +.P +.B Verification trigger example +.RS + +Lets say we want to run a powercut test on the remote machine 'server'. +Our write workload is in write-test.fio. We want to cut power to 'server' +at some point during the run, and we'll run this test from the safety +or our local machine, 'localbox'. On the server, we'll start the fio +backend normally: + +server# \fBfio \-\-server\fR + +and on the client, we'll fire off the workload: + +localbox$ \fBfio \-\-client=server \-\-trigger\-file=/tmp/my\-trigger \-\-trigger-remote="bash \-c "echo b > /proc/sysrq-triger""\fR + +We set \fB/tmp/my-trigger\fR as the trigger file, and we tell fio to execute + +\fBecho b > /proc/sysrq-trigger\fR + +on the server once it has received the trigger and sent us the write +state. This will work, but it's not \fIreally\fR cutting power to the server, +it's merely abruptly rebooting it. If we have a remote way of cutting +power to the server through IPMI or similar, we could do that through +a local trigger command instead. Lets assume we have a script that does +IPMI reboot of a given hostname, ipmi-reboot. On localbox, we could +then have run fio with a local trigger instead: + +localbox$ \fBfio \-\-client=server \-\-trigger\-file=/tmp/my\-trigger \-\-trigger="ipmi-reboot server"\fR + +For this case, fio would wait for the server to send us the write state, +then execute 'ipmi-reboot server' when that happened. + +.RE +.P +.B Loading verify state +.RS +To load store write state, read verification job file must contain +the verify_state_load option. If that is set, fio will load the previously +stored state. For a local fio run this is done by loading the files directly, +and on a client/server run, the server backend will ask the client to send +the files over and load them from there. + +.RE + +.SH LOG FILE FORMATS + +Fio supports a variety of log file formats, for logging latencies, bandwidth, +and IOPS. The logs share a common format, which looks like this: + +.B time (msec), value, data direction, offset + +Time for the log entry is always in milliseconds. The value logged depends +on the type of log, it will be one of the following: + +.P +.PD 0 +.TP +.B Latency log +Value is in latency in usecs +.TP +.B Bandwidth log +Value is in KB/sec +.TP +.B IOPS log +Value is in IOPS +.PD +.P + +Data direction is one of the following: + +.P +.PD 0 +.TP +.B 0 +IO is a READ +.TP +.B 1 +IO is a WRITE +.TP +.B 2 +IO is a TRIM +.PD +.P + +The \fIoffset\fR is the offset, in bytes, from the start of the file, for that +particular IO. The logging of the offset can be toggled with \fBlog_offset\fR. + +If windowed logging is enabled though \fBlog_avg_msec\fR, then fio doesn't log +individual IOs. Instead of logs the average values over the specified +period of time. Since \fIdata direction\fR and \fIoffset\fR are per-IO values, +they aren't applicable if windowed logging is enabled. If windowed logging +is enabled and \fBlog_max_value\fR is set, then fio logs maximum values in +that window instead of averages. + +.RE + .SH CLIENT / SERVER Normally you would run fio as a stand-alone application on the machine where the IO workload should be generated. However, it is also possible to @@ -2005,34 +2290,34 @@ for TCP/IP v4, 'ip6' for TCP/IP v6, or 'sock' for a local unix domain socket. 'hostname' is either a hostname or IP address, and 'port' is the port to listen to (only valid for TCP/IP, not a local socket). Some examples: -1) fio \-\-server +1) \fBfio \-\-server\fR Start a fio server, listening on all interfaces on the default port (8765). -2) fio \-\-server=ip:hostname,4444 +2) \fBfio \-\-server=ip:hostname,4444\fR Start a fio server, listening on IP belonging to hostname and on port 4444. -3) fio \-\-server=ip6:::1,4444 +3) \fBfio \-\-server=ip6:::1,4444\fR Start a fio server, listening on IPv6 localhost ::1 and on port 4444. -4) fio \-\-server=,4444 +4) \fBfio \-\-server=,4444\fR Start a fio server, listening on all interfaces on port 4444. -5) fio \-\-server=1.2.3.4 +5) \fBfio \-\-server=1.2.3.4\fR Start a fio server, listening on IP 1.2.3.4 on the default port. -6) fio \-\-server=sock:/tmp/fio.sock +6) \fBfio \-\-server=sock:/tmp/fio.sock\fR Start a fio server, listening on the local socket /tmp/fio.sock. When a server is running, you can connect to it from a client. The client is run with: -fio \-\-local-args \-\-client=server \-\-remote-args +\fBfio \-\-local-args \-\-client=server \-\-remote-args \fR where \-\-local-args are arguments that are local to the client where it is running, 'server' is the connect string, and \-\-remote-args and @@ -2040,12 +2325,12 @@ are sent to the server. The 'server' string follows the same format as it does on the server side, to allow IP/hostname/socket and port strings. You can connect to multiple clients as well, to do that you could run: -fio \-\-client=server2 \-\-client=server2 +\fBfio \-\-client=server2 \-\-client=server2 \fR If the job file is located on the fio server, then you can tell the server to load a local file as well. This is done by using \-\-remote-config: -fio \-\-client=server \-\-remote-config /path/to/file.fio +\fBfio \-\-client=server \-\-remote-config /path/to/file.fio\fR Then fio will open this local (to the server) job file instead of being passed one from the client. @@ -2060,7 +2345,7 @@ host2.your.dns.domain The fio command would then be: -fio \-\-client=host.list +\fBfio \-\-client=host.list \fR In this mode, you cannot input server-specific parameters or job files, and all servers receive the same job file.