X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=fio.1;h=ed492682fde0a1a3a9f3498a80a46959879454b8;hp=593f4db1cdcfd86550c12eea6c18c97774ff1dab;hb=e3970057d236837b2b6712517b5807800cd93065;hpb=c1f4de8ab8a558a1b302091e97259875f2595b48 diff --git a/fio.1 b/fio.1 index 593f4db1..ed492682 100644 --- a/fio.1 +++ b/fio.1 @@ -20,6 +20,9 @@ file and memory debugging). `help' will list all available tracing options. .BI \-\-parse\-only Parse options only, don't start any I/O. .TP +.BI \-\-merge\-blktrace\-only +Merge blktraces only, don't start any I/O. +.TP .BI \-\-output \fR=\fPfilename Write output to \fIfilename\fR. .TP @@ -2067,8 +2070,15 @@ changing data and the overlapping region has a non-zero size. Setting \fBserialize_overlap\fR tells fio to avoid provoking this behavior by explicitly serializing in-flight I/Os that have a non-zero overlap. Note that setting this option can reduce both performance and the \fBiodepth\fR achieved. -Additionally this option does not work when \fBio_submit_mode\fR is set to -offload. Default: false. +.RS +.P +This option only applies to I/Os issued for a single job except when it is +enabled along with \fBio_submit_mode\fR=offload. In offload mode, fio +will check for overlap among all I/Os submitted by offload jobs with \fBserialize_overlap\fR +enabled. +.P +Default: false. +.RE .TP .BI io_submit_mode \fR=\fPstr This option controls how fio submits the I/O to the I/O engine. The default @@ -2198,6 +2208,30 @@ Determines how iolog is read. If false (default) entire \fBread_iolog\fR will be read at once. If selected true, input from iolog will be read gradually. Useful when iolog is very large, or it is generated. .TP +.BI merge_blktrace_file \fR=\fPstr +When specified, rather than replaying the logs passed to \fBread_iolog\fR, +the logs go through a merge phase which aggregates them into a single blktrace. +The resulting file is then passed on as the \fBread_iolog\fR parameter. The +intention here is to make the order of events consistent. This limits the +influence of the scheduler compared to replaying multiple blktraces via +concurrent jobs. +.TP +.BI merge_blktrace_scalars \fR=\fPfloat_list +This is a percentage based option that is index paired with the list of files +passed to \fBread_iolog\fR. When merging is performed, scale the time of each +event by the corresponding amount. For example, +`\-\-merge_blktrace_scalars="50:100"' runs the first trace in halftime and the +second trace in realtime. This knob is separately tunable from +\fBreplay_time_scale\fR which scales the trace during runtime and will not +change the output of the merge unlike this option. +.TP +.BI merge_blktrace_iters \fR=\fPfloat_list +This is a whole number option that is index paired with the list of files +passed to \fBread_iolog\fR. When merging is performed, run each trace for +the specified number of iterations. For example, +`\-\-merge_blktrace_iters="2:1"' runs the first trace for two iterations +and the second trace for one iteration. +.TP .BI replay_no_stall \fR=\fPbool When replaying I/O with \fBread_iolog\fR the default behavior is to attempt to respect the timestamps within the log and replay them with the @@ -2230,11 +2264,12 @@ Unfortunately this also breaks the strict time ordering between multiple device accesses. .TP .BI replay_align \fR=\fPint -Force alignment of I/O offsets and lengths in a trace to this power of 2 -value. +Force alignment of the byte offsets in a trace to this value. The value +must be a power of 2. .TP .BI replay_scale \fR=\fPint -Scale sector offsets down by this factor when replaying traces. +Scale bye offsets down by this factor when replaying traces. Should most +likely use \fBreplay_align\fR as well. .SS "Threads, processes and job synchronization" .TP .BI replay_skip \fR=\fPstr @@ -2644,6 +2679,12 @@ steady state assessment criteria. All assessments are carried out using only data from the rolling collection window. Threshold limits can be expressed as a fixed value or as a percentage of the mean in the collection window. .RS +.P +When using this feature, most jobs should include the \fBtime_based\fR +and \fBruntime\fR options or the \fBloops\fR option so that fio does not +stop running after it has covered the full size of the specified file(s) +or device(s). +.RS .RS .TP .B iops @@ -3531,6 +3572,45 @@ Write `length' bytes beginning from `offset'. Trim the given file from the given `offset' for `length' bytes. .RE .RE +.SH I/O REPLAY \- MERGING TRACES +Colocation is a common practice used to get the most out of a machine. +Knowing which workloads play nicely with each other and which ones don't is +a much harder task. While fio can replay workloads concurrently via multiple +jobs, it leaves some variability up to the scheduler making results harder to +reproduce. Merging is a way to make the order of events consistent. +.P +Merging is integrated into I/O replay and done when a \fBmerge_blktrace_file\fR +is specified. The list of files passed to \fBread_iolog\fR go through the merge +process and output a single file stored to the specified file. The output file is +passed on as if it were the only file passed to \fBread_iolog\fR. An example would +look like: +.RS +.P +$ fio \-\-read_iolog=":" \-\-merge_blktrace_file="" +.RE +.P +Creating only the merged file can be done by passing the command line argument +\fBmerge-blktrace-only\fR. +.P +Scaling traces can be done to see the relative impact of any particular trace +being slowed down or sped up. \fBmerge_blktrace_scalars\fR takes in a colon +separated list of percentage scalars. It is index paired with the files passed +to \fBread_iolog\fR. +.P +With scaling, it may be desirable to match the running time of all traces. +This can be done with \fBmerge_blktrace_iters\fR. It is index paired with +\fBread_iolog\fR just like \fBmerge_blktrace_scalars\fR. +.P +In an example, given two traces, A and B, each 60s long. If we want to see +the impact of trace A issuing IOs twice as fast and repeat trace A over the +runtime of trace B, the following can be done: +.RS +.P +$ fio \-\-read_iolog=":"" \-\-merge_blktrace_file"" \-\-merge_blktrace_scalars="50:100" \-\-merge_blktrace_iters="2:1" +.RE +.P +This runs trace A at 2x the speed twice for approximately the same runtime as +a single run of trace B. .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.