From 1378cc68af81d2160ba1603b1724aac6c01f3a7f Mon Sep 17 00:00:00 2001 From: Erwan Velu Date: Wed, 7 Aug 2013 16:02:25 +0200 Subject: [PATCH] fio2gnuplot: Adding manpage As requested by users, let's add a manpage to make things easier to understand. I'm providing here the raw file used to generate the manpage. It can be converted to a real manpage by using txt2man. I'm also providing the manpage file to avoid dependencies at build time, anyway the makefile target can be easily used to rebuild it if necessary. --- Makefile | 6 +- tools/plot/fio2gnuplot.1 | 161 +++++++++++++++++++++++++++++++++ tools/plot/fio2gnuplot.manpage | 117 ++++++++++++++++++++++++ 3 files changed, 283 insertions(+), 1 deletion(-) create mode 100644 tools/plot/fio2gnuplot.1 create mode 100644 tools/plot/fio2gnuplot.manpage diff --git a/Makefile b/Makefile index 31cd371c..eb0e892a 100644 --- a/Makefile +++ b/Makefile @@ -275,11 +275,15 @@ distclean: clean FORCE cscope: @cscope -b -R -install: $(PROGS) $(SCRIPTS) FORCE +tools/plot/fio2gnuplot.1: + @cat tools/plot/fio2gnuplot.manpage | txt2man -t fio2gnuplot > tools/plot/fio2gnuplot.1 + +install: $(PROGS) $(SCRIPTS) tools/plot/fio2gnuplot.1 FORCE $(INSTALL) -m 755 -d $(DESTDIR)$(bindir) $(INSTALL) $(PROGS) $(SCRIPTS) $(DESTDIR)$(bindir) $(INSTALL) -m 755 -d $(DESTDIR)$(mandir)/man1 $(INSTALL) -m 644 fio.1 $(DESTDIR)$(mandir)/man1 $(INSTALL) -m 644 tools/fio_generate_plots.1 $(DESTDIR)$(mandir)/man1 + $(INSTALL) -m 644 tools/plot/fio2gnuplot.1 $(DESTDIR)$(mandir)/man1 $(INSTALL) -m 755 -d $(DESTDIR)$(sharedir) $(INSTALL) -m 644 tools/plot/*gpm $(DESTDIR)$(sharedir)/ diff --git a/tools/plot/fio2gnuplot.1 b/tools/plot/fio2gnuplot.1 new file mode 100644 index 00000000..1a33167b --- /dev/null +++ b/tools/plot/fio2gnuplot.1 @@ -0,0 +1,161 @@ +.\" Text automatically generated by txt2man +.TH fio2gnuplot "07 août 2013" "" "" +.SH NAME +\fBfio2gnuplot \fP- Render fio's output files with gnuplot +.SH SYNOPSIS +.nf +.fam C +\fBfio2gnuplot\fP [\fB-ghbiodvk\fP] [\fB-t\fP \fItitle\fP] [\fB-o\fP \fIoutputfile\fP] + [\fB-d\fP \fIoutput_dir\fP] [\fB-p\fP \fIpattern\fP] + [\fB-G\fP \fItype\fP] [\fB-m\fP \fImin_time\fP] [\fB-M\fP \fImax_time\fP] + +.fam T +.fi +.fam T +.fi +.SH DESCRIPTION +\fBfio2gnuplot\fP analyze a set of fio's log files to turn them into a set of graphical traces using gnuplot tool. +Several flavor of plotting are produced +.TP +.B +Individual 2D Graph +Each file is plotted in a separate image file with several option +.RS +.IP \(bu 3 +raw : Plot the exact reported performance. This plotting could be difficult to read +.IP \(bu 3 +smooth :a smoother version of the raw print +Using csplines option of gnuplot, the rendering is +filtered to get an easier to read graph. +.IP \(bu 3 +trend : an even smoother version of the raw print to get trends +Bezier's curves makes much more filtered plots +The resulting graph helps at understanding trends. +.RE +.TP +.B +Grouped 2D graph +All files are plotted in a single image to ease the comparaison. The same rendering options as per the individual 2D graph are used : +.RS +.IP \(bu 3 +raw +.IP \(bu 3 +smooth +.IP \(bu 3 +trend +.RE +.TP +.B +Grouped 3D graph +All files are plotted into a single 3D graph. +The 3D plotting generates a 'surface' to estimate how close were +the performance. +A flat surface means a good coherency between traces. +A rugged surface means a lack of coherency between traces +.TP +.B +Mathemical Plotting +.RS +.TP +.B +Average graph +A bar graph to show the average performance of each file. +A green line is added to show the global average performance. +This green line helps at understanding how far from the average is +every individual file. +.TP +.B +Min graph +A green line is added to show the global average of minimal performance. +This green line helps at understanding how far from the average is +every individual file. +.TP +.B +Max graph +A bar graph to show the maximum performance of each file. +A green line is added to show the global average of maximal performance. +This green line helps at understanding how far from the average is +every individual file. +.TP +.B +Standard Deviation +A bar graph to show the standard deviation of each file. +A green line is added to show the global average of standard deviation. +This green line helps at understanding how far from the average is +every individual file. +.SH OPTIONS +.TP +.B +\fB-h\fP or \fB--help\fP +The option \fB-h\fP displays help +.TP +.B +\fB-p\fP '\fIpattern\fP' or --\fIpattern\fP '\fIpattern\fP' +A \fIpattern\fP in regexp to select fio input files. +Don't forget the simple quotes to avoid shell's interactions +.TP +.B +\fB-b\fP or \fB--bandwidth\fP +A predefined \fIpattern\fP for selecting *_bw.log files +.TP +.B +\fB-i\fP or \fB--iops\fP +A predefined \fIpattern\fP for selecting *_iops.log files +.TP +.B +\fB-g\fP or \fB--gnuplot\fP +Render gnuplot traces before exiting +.TP +.B +\fB-o\fP file or --\fIoutputfile\fP file +The basename for gnuplot traces (set with the \fIpattern\fP if defined) +.TP +.B +\fB-d\fP dir or \fB--outputdir\fP dir +The directory where gnuplot shall render files. +.TP +.B +\fB-t\fP \fItitle\fP or --\fItitle\fP \fItitle\fP +The \fItitle\fP of the gnuplot traces. +Title is set with the block size detected in fio trace +.TP +.B +\fB-G\fP \fItype\fP or \fB--Global\fP \fItype\fP +Search for '\fItype\fP' in .global files match by a \fIpattern\fP. +Available types are : min, max, avg, stddev. +The .global extension is added automatically to the \fIpattern\fP +.TP +.B +\fB-m\fP time or --\fImin_time\fP time +Only consider data starting from 'time' seconds. Default is 0 +.TP +.B +\fB-M\fP time or --\fImax_time\fP time +Only consider data ending before 'time' seconds. Default is \fB-1\fP aka nolimit +.TP +.B +\fB-v\fP or \fB--verbose\fP +Increasing verbosity +.TP +.B +\fB-k\fP or \fB--keep\fP +Keep all temporary files from gnuplot's output dir +.SH EXAMPLE +.TP +.B +To plot all the traces named like 'host*_read_4k_iops.log' +$ \fBfio2gnuplot\fP \fB-p\fP 'host*_read_4k_iops.log' \fB-g\fP +.TP +.B +To plot all IO oriented log files from the current directory +$ \fBfio2gnuplot\fP \fB-g\fP \fB-i\fP +.TP +.B +To plot all Bandwidth oriented log files from the current directory +$ \fBfio2gnuplot\fP \fB-g\fP \fB-b\fP +.TP +.B +To plot all Bandwidth oriented log files in a directory name 'outdir' +$ \fBfio2gnuplot\fP \fB-g\fP \fB-b\fP \fB-d\fP outdir +.SH AUTHOR +Erwan Velu diff --git a/tools/plot/fio2gnuplot.manpage b/tools/plot/fio2gnuplot.manpage new file mode 100644 index 00000000..6a12cf81 --- /dev/null +++ b/tools/plot/fio2gnuplot.manpage @@ -0,0 +1,117 @@ +NAME +fio2gnuplot - Render fio's output files with gnuplot +SYNOPSIS +fio2gnuplot [-ghbiodvk] [-t title] [-o outputfile] + [-d output_dir] [-p pattern] + [-G type] [-m min_time] [-M max_time] + +DESCRIPTION + fio2gnuplot analyze a set of fio's log files to turn them into a set of graphical traces using gnuplot tool. + Several flavor of plotting are produced + + Individual 2D Graph + Each file is plotted in a separate image file with several option + - raw : Plot the exact reported performance. This plotting could be difficult to read + - smooth :a smoother version of the raw print + Using csplines option of gnuplot, the rendering is + filtered to get an easier to read graph. + - trend : an even smoother version of the raw print to get trends + Bezier's curves makes much more filtered plots + The resulting graph helps at understanding trends. + + Grouped 2D graph + All files are plotted in a single image to ease the comparaison. The same rendering options as per the individual 2D graph are used : + - raw + - smooth + - trend + + Grouped 3D graph + All files are plotted into a single 3D graph. + The 3D plotting generates a 'surface' to estimate how close were + the performance. + A flat surface means a good coherency between traces. + A rugged surface means a lack of coherency between traces + + Mathemical Plotting + Average graph + A bar graph to show the average performance of each file. + A green line is added to show the global average performance. + This green line helps at understanding how far from the average is + every individual file. + + Min graph + A green line is added to show the global average of minimal performance. + This green line helps at understanding how far from the average is + every individual file. + + Max graph + A bar graph to show the maximum performance of each file. + A green line is added to show the global average of maximal performance. + This green line helps at understanding how far from the average is + every individual file. + + Standard Deviation + A bar graph to show the standard deviation of each file. + A green line is added to show the global average of standard deviation. + This green line helps at understanding how far from the average is + every individual file. + +OPTIONS + -h or --help + The option -h displays help + + -p 'pattern' or --pattern 'pattern' + A pattern in regexp to select fio input files. + Don't forget the simple quotes to avoid shell's interactions + + -b or --bandwidth + A predefined pattern for selecting *_bw.log files + + -i or --iops + A predefined pattern for selecting *_iops.log files + + -g or --gnuplot + Render gnuplot traces before exiting + + -o file or --outputfile file + The basename for gnuplot traces (set with the pattern if defined) + + -d dir or --outputdir dir + The directory where gnuplot shall render files. + + -t title or --title title + The title of the gnuplot traces. + Title is set with the block size detected in fio trace + + -G type or --Global type + Search for 'type' in .global files match by a pattern. + Available types are : min, max, avg, stddev. + The .global extension is added automatically to the pattern + + -m time or --min_time time + Only consider data starting from 'time' seconds. Default is 0 + + -M time or --max_time time + Only consider data ending before 'time' seconds. Default is -1 aka nolimit + + -v or --verbose + Increasing verbosity + + -k or --keep + Keep all temporary files from gnuplot's output dir + +EXAMPLE +To plot all the traces named like 'host*_read_4k_iops.log' + $ fio2gnuplot -p 'host*_read_4k_iops.log' -g + +To plot all IO oriented log files from the current directory + $ fio2gnuplot -g -i + +To plot all Bandwidth oriented log files from the current directory + $ fio2gnuplot -g -b + +To plot all Bandwidth oriented log files in a directory name 'outdir' + $ fio2gnuplot -g -b -d outdir + +AUTHOR + Erwan Velu -- 2.25.1