X-Git-Url: https://git.kernel.dk/?p=fio.git;a=blobdiff_plain;f=fio.1;h=5c11d963d93dc02d0bf5fd34a3ac6dd633784acb;hp=3b961193e9ed0bcc61686fe2f568bcd2e74db094;hb=97e41ee4267f798bd7a5453259cc518addbf9db2;hpb=7b865a2f23d22f82ffcc25756b1eeea55e57f1e3 diff --git a/fio.1 b/fio.1 index 3b961193..5c11d963 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 @@ -93,7 +96,10 @@ the value is interpreted in seconds. Force a full status dump of cumulative (from job start) values at \fItime\fR intervals. This option does *not* provide per-period measurements. So values such as bandwidth are running averages. When the time unit is omitted, -\fItime\fR is interpreted in seconds. +\fItime\fR is interpreted in seconds. Note that using this option with +`\-\-output-format=json' will yield output that technically isn't valid json, +since the output will be collated sets of valid json. It will need to be split +into valid sets of json after the run. .TP .BI \-\-section \fR=\fPname Only run specified section \fIname\fR in job file. Multiple sections can be specified. @@ -762,6 +768,42 @@ For \fBzonemode\fR=strided, the number of bytes to skip after \fBzonesize\fR bytes of data have been transferred. This parameter must be zero for \fBzonemode\fR=zbd. +.TP +.BI read_beyond_wp \fR=\fPbool +This parameter applies to \fBzonemode=zbd\fR only. + +Zoned block devices are block devices that consist of multiple zones. Each +zone has a type, e.g. conventional or sequential. A conventional zone can be +written at any offset that is a multiple of the block size. Sequential zones +must be written sequentially. The position at which a write must occur is +called the write pointer. A zoned block device can be either drive +managed, host managed or host aware. For host managed devices the host must +ensure that writes happen sequentially. Fio recognizes host managed devices +and serializes writes to sequential zones for these devices. + +If a read occurs in a sequential zone beyond the write pointer then the zoned +block device will complete the read without reading any data from the storage +medium. Since such reads lead to unrealistically high bandwidth and IOPS +numbers fio only reads beyond the write pointer if explicitly told to do +so. Default: false. +.TP +.BI max_open_zones \fR=\fPint +When running a random write test across an entire drive many more zones will be +open than in a typical application workload. Hence this command line option +that allows to limit the number of open zones. The number of open zones is +defined as the number of zones to which write commands are issued. +.TP +.BI zone_reset_threshold \fR=\fPfloat +A number between zero and one that indicates the ratio of logical blocks with +data to the total number of logical blocks in the test above which zones +should be reset periodically. +.TP +.BI zone_reset_frequency \fR=\fPfloat +A number between zero and one that indicates how often a zone reset should be +issued if the zone reset threshold has been exceeded. A zone reset is +submitted after each (1 / zone_reset_frequency) write requests. This and the +previous parameter can be used to simulate garbage collection activity. + .SS "I/O type" .TP .BI direct \fR=\fPbool @@ -2159,6 +2201,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 @@ -2605,6 +2671,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 @@ -3492,6 +3564,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.