From: oetiker Date: Wed, 7 Mar 2001 21:21:54 +0000 (+0000) Subject: complete rewrite of rrdgraph documentation. This also includs info X-Git-Url: https://git.tokkee.org/?a=commitdiff_plain;h=b7c278771851b0dfad0daf1c817fbc93316ef96e;p=rrdtool.git complete rewrite of rrdgraph documentation. This also includs info on upcomming/planned changes to the rrdgraph interface and functionality -- Alex van den Bogaerdt git-svn-id: svn://svn.oetiker.ch/rrdtool/trunk/program@30 a5681a0c-68f1-0310-ab6d-d61299d08faa --- diff --git a/NEWS b/NEWS index 85f8ae7..7adfad0 100644 --- a/NEWS +++ b/NEWS @@ -1,10 +1,17 @@ RRDTOOL NEWS ============ +x + In this file I am noting the Major changes to rrdtool for details check the cvs ChangeLog -2001/03/21 Tobias Oetiker +2001/03/07 Tobias Oetiker + Integrated complete rewrite of rrdgraph documentation by + Alex van den Bogaerdt . THis also contains + info on his planned changes to the rrdgraph module + +2001/03/02 Tobias Oetiker Added Aberrant Patch from Jake Brutlag From now one, new rrd files use version tag 0002. They can NOT be read by the old 1.0.x rrdtools diff --git a/doc/.cvsignore b/doc/.cvsignore index 622a97e..4144680 100644 --- a/doc/.cvsignore +++ b/doc/.cvsignore @@ -1,3 +1,7 @@ +rrdgraph_examples.pod +rrdgraph_rpn.pod +rrdgraph_data.pod +rrdgraph_graph.pod Makefile Makefile.in *.txt diff --git a/doc/Makefile.am b/doc/Makefile.am index 64a33ee..1515f18 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,6 @@ ## Process this file with automake to produce Makefile.in -SUFFIXES = .pod .1 .man .html .txt .pm .pdf +SUFFIXES = .pod .1 .man .html .txt .pm .pdf .src .inc #AUTOMAKE_OPTIONS = foreign @@ -8,10 +8,13 @@ SUFFIXES = .pod .1 .man .html .txt .pm .pdf CLEANFILES = *.1 *.html *.txt *-dircache *.pm *.pdf *~ core *itemcache *.rej *.orig +SRC = rrdgraph.src rrdgraph_examples.src rrdgraph_rpn.src \ + rrdgraph_data.src rrdgraph_graph.src + POD = rrdtool.pod rrdlast.pod rrdcreate.pod rrdupdate.pod rrdtutorial.es.pod \ - cdeftutorial.pod rpntutorial.pod rrdgraph.pod bin_dec_hex.pod \ + cdeftutorial.pod rpntutorial.pod rrdgraph-old.pod bin_dec_hex.pod \ rrdfetch.pod rrdrestore.pod rrddump.pod rrdtune.pod rrdresize.pod \ - rrdcgi.pod rrdtutorial.pod rrdinfo.pod + rrdcgi.pod rrdtutorial.pod rrdinfo.pod $(SRC:.src=.pod) PMP = RRDs.pm RRDp.pm @@ -33,6 +36,9 @@ iman_DATA = $(MAN) all-local: link txt man html +.src.pod: + perl -n -e 'if (/^=include\s+(\S+)/){open F,"$$1.inc" || die $$?;print ; close F} else {print}' $< > $@ + .pod.1 .pm.1 .pl.1: pod2man --release=$(VERSION) --center=rrdtool $< > $@ diff --git a/doc/name.inc b/doc/name.inc new file mode 100644 index 0000000..97754e0 --- /dev/null +++ b/doc/name.inc @@ -0,0 +1,12 @@ +=head1 NAME + +rrdtool graph - Round Robin Database tool grapher functions + +WARNING: This is for version 1.1.x which is B> software. +The software may contain serious bugs. Some of the items +described in here may not yet exist (although this should +be mentioned) or still be in the alpha stage. As with every +other RRDtool release: use at your own risk. In contrast with +the stable version of RRDtool, this release may contain bugs +known to the authors. It is highly recommended that you subscribe +to the mailing list. diff --git a/doc/rrdgraph-old.pod b/doc/rrdgraph-old.pod new file mode 100644 index 0000000..8e8038e --- /dev/null +++ b/doc/rrdgraph-old.pod @@ -0,0 +1,660 @@ +=head1 NAME + +rrdtool graph - Create a graph based on data from one or several RRD + +=for html
PDF version.
+ +=head1 SYNOPSIS + +B B I +S<[B<-s>|B<--start> I]> +S<[B<-e>|B<--end> I]> +S<[B<-x>|B<--x-grid> I]> +S<[B<-y>|B<--y-grid> I]> +S<[B<--alt-y-grid>]> +S<[B<--alt-autoscale>]> +S<[B<--alt-autoscale-max>]> +S<[B<--units-exponent>]> I]> +S<[B<-v>|B<--vertical-label> I]> +S<[B<-w>|B<--width> I]> +S<[B<-h>|B<--height> I]> +S<[B<-i>|B<--interlaced>]> +S<[B<-f>|B<--imginfo> I]> +S<[B<-a>|B<--imgformat> B|B]> +S<[B<-z>|B<--lazy>]> +S<[B<-o>|B<--logarithmic>]> +S<[B<-u>|B<--upper-limit> I]> +S<[B<-l>|B<--lower-limit> I]> +S<[B<-g>|B<--no-legend>]> +S<[B<-r>|B<--rigid>]> +S<[B<--step> I]> +S<[B<-b>|B<--base> I]> +S<[B<-c>|B<--color> IB<#>I]> +S<[B<-t>|B<--title> I]> +S<[B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>]> +S<[B<CDEF:>I<vname>B<=>I<rpn-expression>]> +S<[B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>]> +S<[B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>]> +S<[B<COMMENT:>I<text>]> +S<[B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]]> +S<[B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]]> +S<[B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]> +S<[B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]> +S<[B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]> +S<[B<TICK:>I<vname>B<#>I<rrggbb>[B<:>I<axis-fraction>[B<:>I<legend>]]]> + +=head1 DESCRIPTION + +The B<graph> functions main purpose is to create graphical +representations of the data stored in one or several B<RRD>s. Apart +from generating graphs, it can also extract numerical reports. + +=over + +=item I<filename> + +The name of the graph to generate. Since B<rrdtool> outputs +GIFs and PNGs, it's recommended that the filename end in either +F<.gif> or F<.png>. B<rrdtool> does not enforce this, however. +If the I<filename> is set to '-' the image file will be written +to standard out. All other output will get suppressed. + +PNG output is recommended, since it takes up to 40% less disk space +and 20-30% less time to generate than a GIF file. + +If no graph functions are called, the graph will not be created. + +=item B<-s>|B<--start> I<seconds> (default end-1day) + +The time when the graph should begin. Time in seconds since +epoch (1970-01-01) is required. Negative numbers are relative to the +current time. By default one day worth of data will be graphed. +See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch> +documentation for a detailed explanation on how to specify time. + +=item B<-e>|B<--end> I<seconds> (default now) + +The time when the graph should end. Time in seconds since epoch. +See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch> +documentation for a detailed explanation of ways to specify time. + +=item B<-x>|B<--x-grid> I<x-axis grid and label> (default autoconfigure) + +The x-axis label is quite complex to configure. So if you don't have +very special needs, you can rely on the autoconfiguration to get this +right. + +If you want no x-grid at all, use the magic setting B<none>. + +The x-axis label and grid can be configured, using the following format: + +I<GTM>B<:>I<GST>B<:>I<MTM>B<:>I<MST>B<:>I<LTM>:I<LST>B<:>I<LPR>B<:>I<LFM> + +You have to configure three elements making up the x-axis labels and +grid. The base grid (I<G??>), the major grid (I<M??>) and the labels +(I<L??>). The configuration is based on the idea that you first +specify a well known amount of time (I<?TM>) and then say how many +times it has to pass between each grid line or label (I<?ST>). For the +label you have to define two additional items: The precision of the +label in seconds (I<LPR>) and the strftime format used to generate the +text of the label (I<LFM>). + +The I<?TM> elements must be one of the following keywords: B<SECOND>, +B<MINUTE>, B<HOUR>, B<DAY>, B<WEEK>, B<MONTH> or B<YEAR>. + +If you wanted a graph with a base grid every 10 minutes and a major +one every hour, with labels every hour you would use the following +x-axis definition. + +C<MINUTE:10:HOUR:1:HOUR:1:0:%X> + +The precision in this example is 0 because the %X format is exact. If +the label was the name of the day, we would have had a precision of 24 +hours, because when you say something like 'Monday' you mean the whole +day and not Monday morning 00:00. Thus the label should be positioned +at noon. By defining a precision of 24 hours or rather 86400 seconds, +you make sure that this happens. + +=item B<-y>|B<--y-grid> I<grid step>:I<label factor> (default autoconfigure) + +Makes vertical grid lines appear at I<grid step> interval. Every +I<label factor> gridstep, a major grid line is printed, along with +label showing the value of the grid line. + +If you want no y-grid at all set specify the magic word B<none>. + +=item B<--alt-y-grid> + +Place Y grid dynamically based on graph Y range. Algorithm ensures +that you always have grid, that there are enough but not too many +grid lines and the grid is metric. That is grid lines are placed +every 1, 2, 5 or 10 units. (contributed by Sasha Mikheev) + + +=item B<--alt-autoscale> + +Compute Y range based on function absolute minimum and +maximum values. Default algorithm uses predefined set of ranges. +This is good in many cases but it fails miserably when you need +to graph something like 260 + 0.001 * sin(x). Default algorithm +will use Y range from 250 to 300 and on the graph you will see +almost straight line. With --alt-autoscale Y range will be +from slightly less the 260 - 0.001 to slightly more then 260 + 0.001 +and periodic behavior will be seen. (contributed by Sasha Mikheev) + +=item B<--alt-autoscale-max> + +Where --alt-autoscale will modify both the absolute maximum AND minimum +values, this option will only affect the maximum value. The minimum +value, if not defined on the command line, will be 0. This option can +be useful when graphing router traffic when the WAN line uses compression, +and thus the throughput may be higher than the WAN line speed. + +=item B<--units-exponent> I<value> (default autoconfigure) + +This sets the 10**exponent scaling of the y-axis values. Normally +values will be scaled to the appropriate units (k, M, etc.). However +you may wish to display units always in k (Kilo, 10e3) even if the data +is in the M (Mega, 10e6) range for instance. Value should be an +integer which is a multiple of 3 between -18 and 18 inclusive. It is +the exponent on the units you which to use. For example, use 3 to +display the y-axis values in k (Kilo, 10e3, thousands), use -6 to +display the y-axis values in u (Micro, 10e-6, millionths). Use a value +of 0 to prevent any scaling of the y-axis values. + +=item B<-v>|B<--vertical-label> I<text> + +vertical label on the left side of the graph. This is normally used to +specify the units used. + +=item B<-w>|B<--width> I<pixels> (default 400 pixel) + +Width of the drawing area within the graph. This affects the size of the +gif. + +=item B<-h>|B<--height> I<pixels> (default 100 pixel) + +Width of the drawing area within the graph. This affects the size of the +gif. + +=item B<-i>|B<--interlaced> (default: false) + +If you set this option, then the resulting GIF will be interlaced. +Most web browsers display these incrementally as they load. If +you do not use this option, the GIFs default to being progressive +scanned. The only effect of this option is to control the format +of the GIF on disk. It makes no changes to the layout or contents +of the graph. + +=item B<-f>|B<--imginfo> I<formatstring> + +After the image has been created, the graph function uses printf +together with this format string to create output similar to the PRINT +function, only that the printf is supplied with the parameters +I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag +suitable for including the graph into a web page, the command line +would look like this: + + --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">' + +=item B<-a>|B<--imgformat> B<GIF>|B<PNG> (default: GIF) + +Allows you to produce PNG output from rrdtool. + +=item B<-z>|B<--lazy> (default: false) + +Only generate the graph, if the current gif is out of date or not +existent. + +=item B<-u>|B<--upper-limit> I<value> (default autoconfigure) + +Defines the value normally located at the upper border of the +graph. If the graph contains higher values, the upper border will +move upwards to accomodate these values as well. + +If you want to define an upper-limit which will not move in any +event you have to set the B<--rigid> option as well. + +=item B<-l>|B<--lower-limit> I<value> (default autoconfigure) + +This is not the lower limit of a graph. But rather, this is the +maximum lower bound of a graph. For example, the value -100 will +result in a graph that has a lower limit of -100 or less. Use this +keyword to expand graphs down. + +=item B<-r>|B<--rigid> + +rigid boundaries mode. Normally rrdgraph will automatically expand the +lower and upper limit if the graph contains a value outside the valid +range. With the r option you can disable this behavior + +=item B<-b>|B<--base> I<value> + +if you are graphing memory (and NOT network traffic) this switch +should be set to 1024 so that one Kb is 1024 byte. For traffic +measurement, 1 kb/s is 1000 b/s. + +=item B<-o>|B<--logarithmic> + +logarithmic y-axis scaling + +=item B<-c>|B<--color> I<COLORTAG>B<#>I<rrggbb> (default colors) + +override the colors for the standard elements of the graph. The I<COLORTAG> +must be one of the following symbolic names: B<BACK> ground, B<CANVAS>, +B<SHADEA> left/top border, B<SHADEB> right/bottom border, B<GRID>, B<MGRID> +major grid, B<FONT>, B<FRAME> and axis of the graph or B<ARROW>. This option +can be called multiple times to set several colors. + +=item B<-g>|B<--no-legend> + +Suppress generation of legend; only render the graph. + +=item B<-t>|B<--title> I<text> (default no title) + +Define a title to be written into the graph + +=item B<--step> I<value> (default automatic) + +By default rrdgraph calculates the width of one pixle in the time domain and +tries to get data at that resolution from the RRD. With this switch you can +override this behaviour. If you want rrdgraph to get data at 1 hour +resolution from the RRD, then you can set the step to 3600 seconds. Note, +that a step smaller than 1 pixle will be silently ignored. + +=item B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF> + +Define virtual name for a data source. This name can then be used +in the functions explained below. The +DEF call automatically chooses an B<RRA> which contains I<CF> consolidated data in a +resolution appropriate for the size of the graph to be drawn. Ideally +this means that one data point from the B<RRA> should be represented +by one pixel in the graph. If the resolution of the B<RRA> is higher +than the resolution of the graph, the data in the RRA will be further +consolidated according to the consolidation function (I<CF>) chosen. + +=item B<CDEF:>I<vname>B<=>I<rpn-expression> + +Create a new virtual data source by evaluating a mathematical expression, +specified in Reverse Polish Notation (RPN). If you have ever used a traditional +HP calculator you already know RPN. The idea behind RPN notation is, +that you have a stack and push your data onto this stack. When ever +you execute an operation, it takes as many data values from the stack +as needed. The pushing of data is implicit, so when ever you specify a number +or a variable, it gets pushed automatically. + +If this is all a big load of incomprehensible words for you, maybe an +example helps (a more complete explanation is given in [1]): The +expression I<vname+3/2> becomes C<vname,3,2,/,+> in RPN. First the three +values get pushed onto the stack (which now contains (the current +value of) vname, a 3 and a 2). Then the / operator pops two values +from the stack (3 and 2), divides the first argument by the second +(3/2) and pushes the result (1.5) back onto the stack. Then the + +operator pops two values (vname and 1.5) from the stack; both values +are added up and the result gets pushes back onto the stack. In the +end there is only one value left on the stack: The result of the +expression. + +The I<rpn-expression> in the B<CDEF> function takes both, constant values +as well as I<vname> variables. The following operators can be used on these +values: + +=over + +=item +, -, *, /, % + +pops two values from the stack applies the selected operator and pushes +the result back onto the stack. The % operator stands for the modulo +operation. + +=item SIN, COS, LOG, EXP, FLOOR, CEIL + +pops one value from the stack, applies the selected function and pushes +the result back onto the stack. + +=item LT, LE, GT, GE, EQ + +pops two values from the stack, compares them according to the selected +condition and pushes either 1 back onto the stack if the condition is true +and 0 if the condition was not true. + +=item IF + +pops three values from the stack. If the last value is not 0, the +second value will be pushed back onto the stack, otherwise the +first value is pushed back. + +If the stack contains the values A, B, C, D, E are presently on the +stack, the IF operator will pop the values E D and C of the stack. It will +look at C and if it is not 0 it will push D back onto the stack, otherwise +E will be sent back to the stack. + +=item MIN, MAX + +selects the lesser or larger of the two top stack values respectively + +=item LIMIT + +replaces the value with I<*UNKNOWN*> if it is outside the limits specified +by the two values above it on the stack. + + CDEF:a=alpha,0,100,LIMIT + +=item DUP, EXC, POP + +These manipulate the stack directly. DUP will duplicate the top of the +stack, pushing the result back onto the stack. EXC will exchange the top +two elements of the stack, and POP will pop off the top element of the +stack. Having insufficient elements on the stack for these operations is +an error. + +=item UN + +Pops one value off the stack, if it is I<*UNKNOWN*>, 1 will be pushed +back otherwise 0. + +=item UNKN + +Push an I<*UNKNOWN*> value onto the stack. + +=item PREV + +Push I<*UNKNOWN*> if its at the first value of a data set or otherwise +the value of this CDEF at the previous time step. This allows you to +perform calculations across the data. + +=item INF, NEGINF + +Push a positive or negative infinite (oo) value onto the stack. When +drawing an infinite number it appears right at the top or bottom edge of the +graph, depending whether you have a positive or negative infinite number. + +=item NOW + +Push the current (real world) time onto the stack. + +=item TIME + +Push the time the current sample was taken onto the stack. This is the +number of non-skip seconds since 0:00:00 January 1, 1970. + +=item LTIME + +This is like TIME B<+ current timezone offset in seconds>. The current +offset takes daylight saving time into account, given your OS supports +this. If you were looking at a sample, in Zurich, in summer, the +offset would be 2*3600 seconds, as Zurich at that time of year is 2 +hours ahead of UTC. + +Note that the timezone offset is always calculated for the time the +current sample was taken at. It has nuthing todo with the time you are +doing the calculation. + +=back + +Please note that you may only use I<vname> variables that you +previously defined by either B<DEF> or B<CDEF>. Furthermore, as of +this writing (version 0.99.25), you must use at least one I<vname> +per expression, that is "CDEF:fourtytwo=2,40,+" will yield an error +message but not a I<vname> fourtytwo that's always equal to 42. + +=item B<PRINT:>I<vname>B<:>I<CF>B<:>I<format> + +Calculate the chosen consolidation function I<CF> over the data-source +variable I<vname> and C<printf> the result to stdout using I<format>. +In the I<format> string there should be a '%lf' or '%le' marker in the +place where the number should be printed. + +If an additional '%s' is found AFTER the marker, the value will be scaled +and an appropriate SI magnitude unit will be printed in place of the '%s' +marker. The scaling will take the '--base' argument into consideration! + +If a '%S' is used instead of a '%s', then instead of calculating the +appropriate SI magnitude unit for this value, the previously calculated +SI magnitude unit will be used. This is useful if you want all the values +in a PRINT statement to have the same SI magnitude unit. If there was +no previous SI magnitude calculation made, then '%S' behaves like a '%s', +unless the value is 0, in which case it does not remember a SI magnitude +unit and a SI magnitude unit will only be calculated when the next '%s' is +seen or the next '%S' for a non-zero value. + +If you want to put a '%' into your PRINT string, use '%%' instead. + +=item B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format> + +Same as B<PRINT> but the result is printed into the graph below the legend. + +=back + +B<Caveat:> When using the B<PRINT> and B<GRPRINT> functions to +calculate data summaries over time periods bounded by the current +time, it is important to note that the last sample will almost always +yield a value of UNKNOWN as it lies after the last update time. This +can result in slight data skewing, particularly with the B<AVERAGE> +function. In order to avoid this, make sure that your end time is at +least one heartbeat prior to the current time. + +=over + + +=item B<COMMENT:>I<text> + +Like B<GPRINT> but the I<text> is simply printed into the graph. + +=item B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>] + +Draw a horizontal rule into the graph and optionally add a legend + +=item B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>] + +Draw a vertical rule into the graph and optionally add a legend + +=item B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]] + +Plot for the requested data, using the color specified. Write a legend +into the graph. The 3 possible keywords B<LINE1>, B<LINE2>, and B<LINE3> +generate increasingly wide lines. If no color is defined, +the drawing is done 'blind' this is useful in connection with the +B<STACK> function when you want to ADD the values of two +data-sources without showing it in the graph. + +=item B<AREA>:I<vname>[B<#>I<rrggbb>[B<:>I<legend>]] + +Does the same as B<LINE?>, but the area between 0 and +the graph will be filled with the color specified. + +=item B<STACK>:I<vname>[B<#>I<rrggbb>[B<:>I<legend>]] + +Does the same as B<LINE?>, but the graph gets stacked on top of the previous +B<LINE?>, B<AREA> or B<STACK> graph. Depending on the type of the +previous graph, the B<STACK> will be either a B<LINE?> or an B<AREA>. +This obviously implies that the first B<STACK> must be preceded by an +B<AREA> or B<LINE?> -- you need something to stack something onto in +the first place ;) + +Note, that when you STACK onto *UNKNOWN* data, rrdtool will not draw +any graphics ... *UNKNOWN* is not zero ... if you want it to be zero +then you might want to use a CDEF argument with IF and UN functions to +turn *UNKNOWN* into zero ... + +=item B<TICK:>I<vname>B<#>I<rrggbb>[B<:>I<axis-fraction>[B<:>I<legend>]] + +Plot a tick mark (a vertical line) for each value of I<vname> that is +non-zero and not *UNKNOWN*. The I<axis-fraction> argument specifies the +length of the tick mark as a fraction of the y-axis; the default value +is 0.1 (10% of the axis). Note that the color specification is not +optional. + +=back + +=head1 NOTES on legend arguments + +=head2 Escaping the colon + +In a ':' in a I<legend> argument will mark the end of the legend. To +enter a ':' into a legend, the colon must be escaped with a backslash '\:'. +Beware, that many environments look for backslashes themselves, so it may +be necessary to write two backslashes so that one is passed onto rrd_graph. + +=head2 String Formatting + +The text printed below the actual graph can be formated by appending special +escaped characters at the end of a text. When ever such a character occurs, +all pending text is pushed onto the graph according to the character +specified. + +Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for +right aligned and B<\c> for centered. In the next section there is an +example showing how to use centered formating. + +Normally there are two space characters inserted between every two items +printed into the graph. The space following a string can be suppressed by +putting a B<\g> at the end of the string. The B<\g> also squshes any space +inside the string if it is at the very end of the string. This can be used +in connection with B<%s> to supress empty unit strings. + + GPRINT:a:MAX:%lf%s\g + +A special case is COMMENT:B<\s> this inserts some additional vertical space +before placing the next row of legends. + +=head1 NOTE on Return Values + +Whenever rrd_graph gets called, it prints a line telling the size of +the gif it has just created to STDOUT. This line looks like this: XSIZExYSIZE. + +=head1 EXAMPLE 1 + + rrdtool graph demo.gif --title="Demo Graph" \ + DEF:cel=demo.rrd:exhaust:AVERAGE \ + "CDEF:far=cel,1.8,*,32,+"" \ + LINE2:cel#00a000:"D. Celsius" \ + LINE2:far#ff0000:"D. Fahrenheit\c" + +=head1 EXAMPLE 2 + +This example demonstrates the syntax for using IF and UN to set +I<*UNKNOWN*> values to 0. This technique is useful if you are +aggregating interface data where the start dates of the data sets +doesn't match. + + rrdtool graph demo.gif --title="Demo Graph" \ + DEF:idat1=interface1.rrd:ds0:AVERAGE \ + DEF:idat2=interface2.rrd:ds0:AVERAGE \ + DEF:odat1=interface1.rrd:ds1:AVERAGE \ + DEF:odat2=interface2.rrd:ds1:AVERAGE \ + CDEF:agginput=idat1,UN,0,idat1,IF,idat2,UN,0,idat2,IF,+,8,* \ + CDEF:aggoutput=odat1,UN,0,odat1,IF,odat2,UN,0,odat2,IF,+,8,* \ + AREA:agginput#00cc00:Input Aggregate \ + LINE1:agginput#0000FF:Output Aggregate + +Assuming that idat1 has a data value of I<*UNKNOWN*>, the CDEF expression + + idat1,UN,0,idat1,IF + +leaves us with a stack with contents of 1,0,NaN and the IF function +will pop off the 3 values and replace them with 0. If idat1 had a +real value like 7942099, then the stack would have 0,0,7942099 and the +real value would be the replacement. + +=head1 EXAMPLE 3 + +This example shows two ways to use the INF function. First it makes +the background change color during half of the hours. Then, it uses +AREA and STACK to draw a picture. If one of the inputs was UNKNOWN, +all inputs are overlaid with another AREA. + + rrdtool graph example.png --title="INF demo" \ + DEF:val1=some.rrd:ds0:AVERAGE \ + DEF:val2=some.rrd:ds1:AVERAGE \ + DEF:val3=some.rrd:ds2:AVERAGE \ + DEF:val4=other.rrd:ds0:AVERAGE \ + CDEF:background=val4,POP,TIME,7200,%,3600,LE,INF,UNKN,IF \ + CDEF:wipeout=val1,val2,val3,val4,+,+,+,UN,INF,UNKN,IF \ + AREA:background#F0F0F0 \ + AREA:val1#0000FF:Value1 \ + STACK:val2#00C000:Value2 \ + STACK:val3#FFFF00:Value3 \ + STACK:val4#FFC000:Value4 \ + AREA:wipeout#FF0000:Unknown + +The first CDEF uses val4 as a dummy value. It's value is removed immediately +from the stack. Then a decision is made based on the time that a sample was +taken. If it is an even hour (UTC time !) then the area will be filled. If +it is not, the value is set to UNKN and is not plotted. + +The second CDEF looks if any of val1,val2,val3,val4 is unknown. It does so by +checking the outcome of sum(val1,val2,val3,val4). Again, INF is returned when +the condition is true, UNKN is used to not plot the data. + +The different items are plotted in a particular order. First do the background, then use a +normal area to overlay it with data. Stack the other data until they are all plotted. Last but +not least, overlay everything with eye-hurting red +to signal any unknown data. + +Note that this example assumes that your data is in the positive half of the y-axis +otherwhise you would would have to add NEGINF in order to extend the coverage +of the rea to whole graph. + +=head1 EXAMPLE 4 + +If the specialized function B<RRAs> exist for aberrant behavior detection, they +can be used to generate the graph of a time series with confidence bands and +failures. + + rrdtool graph example.gif \ + DEF:obs=monitor.rrd:ifOutOctets:AVERAGE \ + DEF:pred=monitor.rrd:ifOutOctets:HWPREDICT \ + DEF:dev=monitor.rrd:ifOutOctets:DEVPREDICT \ + DEF:fail=monitor.rrd:ifOutOctets:FAILURES \ + TICK:fail#ffffa0:1.0:"Failures\: Average bits out" \ + CDEF:scaledobs=obs,8,* \ + CDEF:upper=pred,dev,2,*,+ \ + CDEF:lower=pred,dev,2,*,- \ + CDEF:scaledupper=upper,8,* \ + CDEF:scaledlower=lower,8,* \ + LINE2:scaledobs#0000ff:"Average bits out" \ + LINE1:scaledupper#ff0000:"Upper Confidence Bound: Average bits out" \ + LINE1:scaledlower#ff0000:"Lower Confidence Bound: Average bits out" + +This example generates a graph of the data series in blue (LINE2 with the scaledobs +virtual data source), confidence bounds in red (scaledupper and scaledlower virtual +data sources), and potential failures (i.e. potential aberrant aberrant behavior) +marked by vertical yellow lines (the fail data source). + +The raw data comes from an AVERAGE B<RRA>, the finest resolution of the observed +time series (one consolidated data point per primary data point). The predicted +(or smoothed) values are stored in the HWPREDICT B<RRA>. The predicted deviations +(think standard deviation) values are stored in the DEVPREDICT B<RRA>. Finally, +the FAILURES B<RRA> contains indicators, with 1 denoting a potential failure. + +All of the data is rescaled to bits (instead of Octets) by multiplying by 8. +The confidence bounds are computed by an offset of 2 deviations both above +and below the predicted values (the CDEFs upper and lower). Vertical lines +indicated potential failures are graphed via the TICK graph element, which +converts non-zero values in an B<RRA> into tick marks. Here an axis-fraction +argument of 1.0 means the tick marks span the entire y-axis, and hence become +vertical lines on the graph. + +The choice of 2 deviations (a scaling factor) matches the default used internally +by the FAILURES B<RRA>. If the internal value is changed (see L<rrdtune>), this +graphing command should be changed to be consistent. + +=head2 A note on data reduction: + +The B<rrdtool> I<graph> command is designed to plot data at a specified temporal +resolution, regardless of the actually resolution of the data in the RRD file. +This can present a problem for the specialized consolidation functions which +maintain a one-to-one mapping between primary data points and consolidated +data points. If a graph insists on viewing the contents of these B<RRAs> on a +coarser temporal scale, the I<graph> command tries to do something intelligent, +but the confidence bands and failures no longer have the same meaning and may +be misleading. + +=head1 AUTHOR + +Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt> + +=head1 REFERENCES + +[1] http://www.dotpoint.com/xnumber/rpn_or_adl.htm diff --git a/doc/rrdgraph.pod b/doc/rrdgraph.pod index 8e8038e..eeab6bb 100644 --- a/doc/rrdgraph.pod +++ b/doc/rrdgraph.pod @@ -1,660 +1,349 @@ =head1 NAME -rrdtool graph - Create a graph based on data from one or several RRD - -=for html <div align="right"><a href="rrdgraph.pdf">PDF</a> version.</div> - -=head1 SYNOPSIS - -B<rrdtool> B<graph> I<filename> -S<[B<-s>|B<--start> I<seconds>]> -S<[B<-e>|B<--end> I<seconds>]> -S<[B<-x>|B<--x-grid> I<x-axis grid and label>]> -S<[B<-y>|B<--y-grid> I<y-axis grid and label>]> -S<[B<--alt-y-grid>]> -S<[B<--alt-autoscale>]> -S<[B<--alt-autoscale-max>]> -S<[B<--units-exponent>]> I<value>]> -S<[B<-v>|B<--vertical-label> I<text>]> -S<[B<-w>|B<--width> I<pixels>]> -S<[B<-h>|B<--height> I<pixels>]> -S<[B<-i>|B<--interlaced>]> -S<[B<-f>|B<--imginfo> I<formatstring>]> -S<[B<-a>|B<--imgformat> B<GIF>|B<PNG>]> -S<[B<-z>|B<--lazy>]> -S<[B<-o>|B<--logarithmic>]> -S<[B<-u>|B<--upper-limit> I<value>]> -S<[B<-l>|B<--lower-limit> I<value>]> -S<[B<-g>|B<--no-legend>]> -S<[B<-r>|B<--rigid>]> -S<[B<--step> I<value>]> -S<[B<-b>|B<--base> I<value>]> -S<[B<-c>|B<--color> I<COLORTAG>B<#>I<rrggbb>]> -S<[B<-t>|B<--title> I<title>]> -S<[B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF>]> -S<[B<CDEF:>I<vname>B<=>I<rpn-expression>]> -S<[B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>]> -S<[B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>]> -S<[B<COMMENT:>I<text>]> -S<[B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]]> -S<[B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]]> -S<[B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]> -S<[B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]> -S<[B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]> -S<[B<TICK:>I<vname>B<#>I<rrggbb>[B<:>I<axis-fraction>[B<:>I<legend>]]]> +rrdtool graph - Round Robin Database tool grapher functions + +WARNING: This is for version 1.1.x which is B<I<BETA>> software. +The software may contain serious bugs. Some of the items +described in here may not yet exist (although this should +be mentioned) or still be in the alpha stage. As with every +other RRDtool release: use at your own risk. In contrast with +the stable version of RRDtool, this release may contain bugs +known to the authors. It is highly recommended that you subscribe +to the mailing list. + +=head1 SYNOPSYS + +B<rrdtool graph> I<filename> +[E<lt>B<L<option|rrdgraph/OPTIONS>>E<gt> ...] +E<lt>B<L<data definition|rrdgraph_data/DEF>>E<gt> +[E<lt>B<L<data definition|rrdgraph_data/DEF>>E<gt> ...] +[E<lt>B<L<data calculation|rrdgraph_data/CDEF>>E<gt> ...] +[E<lt>B<L<variable definition|rrdgraph_data/VDEF>>E<gt> ...] +[E<lt>B<L<graph element|rrdgraph_graph/GRAPH>>E<gt> ...] +[E<lt>B<L<print element|rrdgraph_graph/PRINT>>E<gt> ...] =head1 DESCRIPTION -The B<graph> functions main purpose is to create graphical -representations of the data stored in one or several B<RRD>s. Apart -from generating graphs, it can also extract numerical reports. +The B<graph> function of B<RRDtool> is used to represent the +data from an B<RRD> to a human viewer. Its main purpose is to +create a nice graphical representation but it can also generate +a numerical report. -=over +=head1 OVERVIEW -=item I<filename> +B<rrdtool graph> needs data to work with, use one or more +B<L<data definition|rrdgraph_data/DEF>> statements to collect this +data. You are not limited to one database, it's perfectly legal to +collect data from two or more databases (one per statement though). -The name of the graph to generate. Since B<rrdtool> outputs -GIFs and PNGs, it's recommended that the filename end in either -F<.gif> or F<.png>. B<rrdtool> does not enforce this, however. -If the I<filename> is set to '-' the image file will be written -to standard out. All other output will get suppressed. +If you want to display averages, maxima, percentiles etcetera +it is best to collect them now using the +B<L<variable definition|rrdgraph_data/VDEF>> statement. At this +stage, this command works at the unprocessed data from the B<RRD>. +I<(Note: this is not yet true; it works on consolidated information +right now)> -PNG output is recommended, since it takes up to 40% less disk space -and 20-30% less time to generate than a GIF file. +The data fetched from the B<RRA> is then B<consolidated> so that +there is exactly one datapoint per pixel in the graph. If you do +not take care yourself, B<RRDtool> will expand the range slightly +if necessary (in that case the first pixel may very well become +unknown!). -If no graph functions are called, the graph will not be created. +Sometimes data is not exactly as you would like to display it. For +instance, you might be collecting B<bytes> per second but want to +display B<bits> per second. This is where the +B<L<data calculation|rrdgraph_data/CDEF>> command is designed for. +After B<consolidating> the data, a copy is made and this copy is +modified using a rather flexible B<L<RPN|rrdgraph_rpn/>> command +set. If you use B<L<variable definition|rrdgraph_data/VDEF>> +statements after this, they work on the consolidated data and may +return other values for maximum, minimum etcetera! + +When you are done fetching and processing the data, it is time to +graph it (or print it). This ends the B<rrdtool graph> sequence. -=item B<-s>|B<--start> I<seconds> (default end-1day) +=head1 OPTIONS -The time when the graph should begin. Time in seconds since -epoch (1970-01-01) is required. Negative numbers are relative to the -current time. By default one day worth of data will be graphed. -See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch> -documentation for a detailed explanation on how to specify time. +It is expected that most options will move to the graph definition +statements (after all, most of them do define graph elements...). -=item B<-e>|B<--end> I<seconds> (default now) +=over 4 -The time when the graph should end. Time in seconds since epoch. -See also AT-STYLE TIME SPECIFICATION section in the I<rrdfetch> -documentation for a detailed explanation of ways to specify time. +=item filename -=item B<-x>|B<--x-grid> I<x-axis grid and label> (default autoconfigure) +The name and path of the graph to generate. It is recommended to +end this in C<.png> or C<.gif> but B<rrdtool> does not enforce this. -The x-axis label is quite complex to configure. So if you don't have -very special needs, you can rely on the autoconfiguration to get this -right. +I<filename> can be 'C<->' to send the image to C<stdout>. In +that case, no other output is generated. -If you want no x-grid at all, use the magic setting B<none>. +Z<> -The x-axis label and grid can be configured, using the following format: +=item Time range -I<GTM>B<:>I<GST>B<:>I<MTM>B<:>I<MST>B<:>I<LTM>:I<LST>B<:>I<LPR>B<:>I<LFM> +B<[-s|--start E<lt>timeE<gt>]> +B<[-e|--end E<lt>timeE<gt>]> +B<[--step E<lt>secondsE<gt>]> -You have to configure three elements making up the x-axis labels and -grid. The base grid (I<G??>), the major grid (I<M??>) and the labels -(I<L??>). The configuration is based on the idea that you first -specify a well known amount of time (I<?TM>) and then say how many -times it has to pass between each grid line or label (I<?ST>). For the -label you have to define two additional items: The precision of the -label in seconds (I<LPR>) and the strftime format used to generate the -text of the label (I<LFM>). +The start and end of what you would like to display, and which +B<RRA> the data should come from. Defaults are: 1 day ago until +now, with the best possible resolution. B<Start> and B<end> can +be specified in several formats, see +L<AT-STYLE TIME SPECIFICATION|rrdfetch/> and L<rrdgraph_examples>. +By default, B<rrdtool graph> calculates the width of one pixel in +the time domain and tries to get data from an B<RRA> with that +resolution. With the B<step> option you can alter this behaviour. +If you want B<rrdtool graph> to get data at a one-hour resolution +from the B<RRD>, set B<step> to 3600. Note: a step smaller than +one pixel will silently be ignored. -The I<?TM> elements must be one of the following keywords: B<SECOND>, -B<MINUTE>, B<HOUR>, B<DAY>, B<WEEK>, B<MONTH> or B<YEAR>. +Z<> -If you wanted a graph with a base grid every 10 minutes and a major -one every hour, with labels every hour you would use the following -x-axis definition. +=item Labels -C<MINUTE:10:HOUR:1:HOUR:1:0:%X> +B<[-t|--title E<lt>stringE<gt>]> +B<[-v|--vertical-label E<lt>stringE<gt>]> -The precision in this example is 0 because the %X format is exact. If -the label was the name of the day, we would have had a precision of 24 -hours, because when you say something like 'Monday' you mean the whole -day and not Monday morning 00:00. Thus the label should be positioned -at noon. By defining a precision of 24 hours or rather 86400 seconds, -you make sure that this happens. +A horizontal string at the top of the graph and/or a vertically +placed string at the left hand side of the graph. I<New: (not +yet implemented)> The string can contain formatter options that +are used to include variables (from B<VDEF>s) and newlines. -=item B<-y>|B<--y-grid> I<grid step>:I<label factor> (default autoconfigure) +Z<> -Makes vertical grid lines appear at I<grid step> interval. Every -I<label factor> gridstep, a major grid line is printed, along with -label showing the value of the grid line. +=item Size -If you want no y-grid at all set specify the magic word B<none>. +B<[-w|--width E<lt>pixelsE<gt>]> +B<[-h|--heigth E<lt>pixelsE<gt>]> -=item B<--alt-y-grid> +The width and height of the B<canvas> (the part of the graph with +the actual lines and such). Defaults are 400 pixels by 100 pixels. -Place Y grid dynamically based on graph Y range. Algorithm ensures -that you always have grid, that there are enough but not too many -grid lines and the grid is metric. That is grid lines are placed -every 1, 2, 5 or 10 units. (contributed by Sasha Mikheev) - - -=item B<--alt-autoscale> - -Compute Y range based on function absolute minimum and -maximum values. Default algorithm uses predefined set of ranges. -This is good in many cases but it fails miserably when you need -to graph something like 260 + 0.001 * sin(x). Default algorithm -will use Y range from 250 to 300 and on the graph you will see -almost straight line. With --alt-autoscale Y range will be -from slightly less the 260 - 0.001 to slightly more then 260 + 0.001 -and periodic behavior will be seen. (contributed by Sasha Mikheev) - -=item B<--alt-autoscale-max> - -Where --alt-autoscale will modify both the absolute maximum AND minimum -values, this option will only affect the maximum value. The minimum -value, if not defined on the command line, will be 0. This option can -be useful when graphing router traffic when the WAN line uses compression, -and thus the throughput may be higher than the WAN line speed. - -=item B<--units-exponent> I<value> (default autoconfigure) - -This sets the 10**exponent scaling of the y-axis values. Normally -values will be scaled to the appropriate units (k, M, etc.). However -you may wish to display units always in k (Kilo, 10e3) even if the data -is in the M (Mega, 10e6) range for instance. Value should be an -integer which is a multiple of 3 between -18 and 18 inclusive. It is -the exponent on the units you which to use. For example, use 3 to -display the y-axis values in k (Kilo, 10e3, thousands), use -6 to -display the y-axis values in u (Micro, 10e-6, millionths). Use a value -of 0 to prevent any scaling of the y-axis values. - -=item B<-v>|B<--vertical-label> I<text> - -vertical label on the left side of the graph. This is normally used to -specify the units used. - -=item B<-w>|B<--width> I<pixels> (default 400 pixel) - -Width of the drawing area within the graph. This affects the size of the -gif. - -=item B<-h>|B<--height> I<pixels> (default 100 pixel) - -Width of the drawing area within the graph. This affects the size of the -gif. - -=item B<-i>|B<--interlaced> (default: false) - -If you set this option, then the resulting GIF will be interlaced. -Most web browsers display these incrementally as they load. If -you do not use this option, the GIFs default to being progressive -scanned. The only effect of this option is to control the format -of the GIF on disk. It makes no changes to the layout or contents -of the graph. - -=item B<-f>|B<--imginfo> I<formatstring> - -After the image has been created, the graph function uses printf -together with this format string to create output similar to the PRINT -function, only that the printf is supplied with the parameters -I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag -suitable for including the graph into a web page, the command line -would look like this: - - --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">' - -=item B<-a>|B<--imgformat> B<GIF>|B<PNG> (default: GIF) - -Allows you to produce PNG output from rrdtool. - -=item B<-z>|B<--lazy> (default: false) - -Only generate the graph, if the current gif is out of date or not -existent. - -=item B<-u>|B<--upper-limit> I<value> (default autoconfigure) - -Defines the value normally located at the upper border of the -graph. If the graph contains higher values, the upper border will -move upwards to accomodate these values as well. - -If you want to define an upper-limit which will not move in any -event you have to set the B<--rigid> option as well. - -=item B<-l>|B<--lower-limit> I<value> (default autoconfigure) - -This is not the lower limit of a graph. But rather, this is the -maximum lower bound of a graph. For example, the value -100 will -result in a graph that has a lower limit of -100 or less. Use this -keyword to expand graphs down. +Z<> -=item B<-r>|B<--rigid> +=item Limits -rigid boundaries mode. Normally rrdgraph will automatically expand the -lower and upper limit if the graph contains a value outside the valid -range. With the r option you can disable this behavior +I<Old behaviour, until the new options are implemented> +B<[-u|--upper-limit E<lt>valueE<gt>]> +B<[-l|--lower-limit E<lt>valueE<gt>]> +B<[-r|--rigid]> -=item B<-b>|B<--base> I<value> +By default the graph will be autoscaling so that it displays the +portion of the y-axis that is actually used. You can change this +behaviour by setting the limits. The displayed y-axis will show +at least from B<lower-limit> to B<upper-limit>. Autoscaling will +still permit those boundaries to be stretched unless the B<rigid> +option is set. -if you are graphing memory (and NOT network traffic) this switch -should be set to 1024 so that one Kb is 1024 byte. For traffic -measurement, 1 kb/s is 1000 b/s. - -=item B<-o>|B<--logarithmic> - -logarithmic y-axis scaling - -=item B<-c>|B<--color> I<COLORTAG>B<#>I<rrggbb> (default colors) - -override the colors for the standard elements of the graph. The I<COLORTAG> -must be one of the following symbolic names: B<BACK> ground, B<CANVAS>, -B<SHADEA> left/top border, B<SHADEB> right/bottom border, B<GRID>, B<MGRID> -major grid, B<FONT>, B<FRAME> and axis of the graph or B<ARROW>. This option -can be called multiple times to set several colors. - -=item B<-g>|B<--no-legend> - -Suppress generation of legend; only render the graph. - -=item B<-t>|B<--title> I<text> (default no title) - -Define a title to be written into the graph - -=item B<--step> I<value> (default automatic) - -By default rrdgraph calculates the width of one pixle in the time domain and -tries to get data at that resolution from the RRD. With this switch you can -override this behaviour. If you want rrdgraph to get data at 1 hour -resolution from the RRD, then you can set the step to 3600 seconds. Note, -that a step smaller than 1 pixle will be silently ignored. +I<New behaviour, after the new options are implemented> +B<[--maximum-upper-limit E<lt>valueE<gt>]> +B<[--minimum-upper-limit E<lt>valueE<gt>]> +B<[--maximum-lower-limit E<lt>valueE<gt>]> +B<[--minimum-lower-limit E<lt>valueE<gt>]> -=item B<DEF:>I<vname>B<=>I<rrd>B<:>I<ds-name>B<:>I<CF> +By default the graph will be autoscaling so that it displays the +portion of the y-axis that is actually used. You can change this +behaviour by setting the limits. The displayed y-axis will show +at most B<maximum-upper-limit> and at least B<minimum-upper-limit> +at the top, and similarily at least B<maximum-lower-limit> and +at most B<minimum-lower-limit> at the bottom. The default is to +display at most B<infinity> (so: no limit) and at least +B<negative infinity> (no minimal value) at the top. The bottom of +the graph has similar defaults. Note that the minimum lower limit +is the lowest one so you should compare this with maximum upper +limit when you try to figure out what you should set. -Define virtual name for a data source. This name can then be used -in the functions explained below. The -DEF call automatically chooses an B<RRA> which contains I<CF> consolidated data in a -resolution appropriate for the size of the graph to be drawn. Ideally -this means that one data point from the B<RRA> should be represented -by one pixel in the graph. If the resolution of the B<RRA> is higher -than the resolution of the graph, the data in the RRA will be further -consolidated according to the consolidation function (I<CF>) chosen. +To make sure the graph shows the range of I<-1000> to I<2000>, +optionally expanding to no more than I<-3000> to I<4000>, +set the following options: -=item B<CDEF:>I<vname>B<=>I<rpn-expression> +--maximum-upper-limit 4000 --minimum-upper-limit 2000 +--maximum-lower-limit -1000 --minimum-lower-limit -3000 -Create a new virtual data source by evaluating a mathematical expression, -specified in Reverse Polish Notation (RPN). If you have ever used a traditional -HP calculator you already know RPN. The idea behind RPN notation is, -that you have a stack and push your data onto this stack. When ever -you execute an operation, it takes as many data values from the stack -as needed. The pushing of data is implicit, so when ever you specify a number -or a variable, it gets pushed automatically. +To mimic the old B<rigid> option, you can do: -If this is all a big load of incomprehensible words for you, maybe an -example helps (a more complete explanation is given in [1]): The -expression I<vname+3/2> becomes C<vname,3,2,/,+> in RPN. First the three -values get pushed onto the stack (which now contains (the current -value of) vname, a 3 and a 2). Then the / operator pops two values -from the stack (3 and 2), divides the first argument by the second -(3/2) and pushes the result (1.5) back onto the stack. Then the + -operator pops two values (vname and 1.5) from the stack; both values -are added up and the result gets pushes back onto the stack. In the -end there is only one value left on the stack: The result of the -expression. +--maximum-upper-limit 4000 --minimum-upper-limit 4000 +--maximum-lower-limit -3000 --minimum-lower-limit -3000 -The I<rpn-expression> in the B<CDEF> function takes both, constant values -as well as I<vname> variables. The following operators can be used on these -values: +B<[--alt-autoscale]> -=over +Sometimes the default algorithm for selecting the y-axis scale is not +performing very well. Normally the scale is selected from a predefined +set of ranges and this fails miserably when you need to graph something +like C<260 + 0.001 * sin(x)>. This option calculates the minimum and +maximum y-axis from the actual minimum and maximum values. Our example +would display slightly less than C<260-0.001> to slightly more than +C<260+0.001> (Contributed by Sasha Mikheev). -=item +, -, *, /, % +B<[--alt-autoscale-max]> -pops two values from the stack applies the selected operator and pushes -the result back onto the stack. The % operator stands for the modulo -operation. - -=item SIN, COS, LOG, EXP, FLOOR, CEIL - -pops one value from the stack, applies the selected function and pushes -the result back onto the stack. - -=item LT, LE, GT, GE, EQ - -pops two values from the stack, compares them according to the selected -condition and pushes either 1 back onto the stack if the condition is true -and 0 if the condition was not true. - -=item IF - -pops three values from the stack. If the last value is not 0, the -second value will be pushed back onto the stack, otherwise the -first value is pushed back. - -If the stack contains the values A, B, C, D, E are presently on the -stack, the IF operator will pop the values E D and C of the stack. It will -look at C and if it is not 0 it will push D back onto the stack, otherwise -E will be sent back to the stack. +Where C<--alt-autoscale> will modify both the absolute maximum AND minimum +values, this option will only affect the maximum value. The minimum +value, if not defined on the command line, will be 0. This option can +be useful when graphing router traffic when the WAN line uses compression, +and thus the throughput may be higher than the WAN line speed. -=item MIN, MAX +Z<> -selects the lesser or larger of the two top stack values respectively +=item Grid -=item LIMIT +=over 4 -replaces the value with I<*UNKNOWN*> if it is outside the limits specified -by the two values above it on the stack. +=item X-Axis - CDEF:a=alpha,0,100,LIMIT +B<[-x|--x-grid E<lt>I<GTMC<:>GSTC<:>MTMC<:>MSTC<:>LTMC<:>LSTC<:>LPRC<:>LFM>E<gt>|C<none>]> -=item DUP, EXC, POP +The x-axis label is quite complex to configure, if you don't have +very special needs it is probably best to rely on the autoconfiguration +to get this right. You can specify the string C<none> to skip the grid +and labels altogether. -These manipulate the stack directly. DUP will duplicate the top of the -stack, pushing the result back onto the stack. EXC will exchange the top -two elements of the stack, and POP will pop off the top element of the -stack. Having insufficient elements on the stack for these operations is -an error. +The grid is defined by specifying a certain amount of time in the I<?TM> +positions. You can choose from C<SECOND>, C<MINUTE>, C<HOUR>, C<DAY>, +C<WEEK>, C<MONTH> or C<YEAR>. Then you define how many of these should +pass between each line or label. This pair (I<?TM:?ST>) needs to be +specified for the base grid (I<G??>), the major grid (I<M??>) and the +labels (I<L??>). For the labels you also need to define a precision +in I<LPR> and a I<strftime> format string in I<LFM>. I<LPR> defines +where each label will be placed. If it is zero, the label will be +placed right under the corresponding line (useful for hours, dates +etcetera). If you specify a number of seconds here the label is +centered in this interval (useful for monday, januari etcetera). -=item UN +Example: C<--x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X> -Pops one value off the stack, if it is I<*UNKNOWN*>, 1 will be pushed -back otherwise 0. +This places grid lines every 10 minutes, major grid lines every hour +and labels every 4 hours. The labels are placed under the major grid +lines as they specify exactly that time. -=item UNKN +Example: C<--x-grid HOUR:8:DAY:1:DAY:1:0:%A> -Push an I<*UNKNOWN*> value onto the stack. +This places grid lines every 8 hours, major grid lines and labels +each day. The labels are placed exactly between two major grid lines +as they specify the complete day and not just midnight. -=item PREV +Z<> -Push I<*UNKNOWN*> if its at the first value of a data set or otherwise -the value of this CDEF at the previous time step. This allows you to -perform calculations across the data. +=item Y-Axis -=item INF, NEGINF +B<[-y|--y-grid I<E<lt>grid stepE<gt>:E<lt>label factorE<gt>>|C<none>]> -Push a positive or negative infinite (oo) value onto the stack. When -drawing an infinite number it appears right at the top or bottom edge of the -graph, depending whether you have a positive or negative infinite number. +Y-axis grid lines appear at each I<grid step> interval. Labels are +placed every I<label factor> lines. You can specify C<-y none> to +skip the grid and labels altogether. The default for this option is +to automatically select sensible values. -=item NOW +B<[--alt-y-grid]> -Push the current (real world) time onto the stack. +Place Y grid dynamically based on graph Y range. Algorithm ensures +that you always have grid, that there are enough but not too many +grid lines and the grid is metric. That is grid lines are placed +every 1, 2, 5 or 10 units. (contributed by Sasha Mikheev) -=item TIME +B<[-o|--logarithmic]> -Push the time the current sample was taken onto the stack. This is the -number of non-skip seconds since 0:00:00 January 1, 1970. +Logarithmic y-axis scaling. -=item LTIME +B<[--units-exponent E<lt>valueE<gt>]> -This is like TIME B<+ current timezone offset in seconds>. The current -offset takes daylight saving time into account, given your OS supports -this. If you were looking at a sample, in Zurich, in summer, the -offset would be 2*3600 seconds, as Zurich at that time of year is 2 -hours ahead of UTC. +This sets the 10**exponent scaling of the y-axis values. Normally +values will be scaled to the appropriate units (k, M, etc.). However +you may wish to display units always in k (Kilo, 10e3) even if the data +is in the M (Mega, 10e6) range for instance. Value should be an +integer which is a multiple of 3 between -18 and 18 inclusive. It is +the exponent on the units you which to use. For example, use 3 to +display the y-axis values in k (Kilo, 10e3, thousands), use -6 to +display the y-axis values in u (Micro, 10e-6, millionths). Use a value +of 0 to prevent any scaling of the y-axis values. -Note that the timezone offset is always calculated for the time the -current sample was taken at. It has nuthing todo with the time you are -doing the calculation. +Z<> =back -Please note that you may only use I<vname> variables that you -previously defined by either B<DEF> or B<CDEF>. Furthermore, as of -this writing (version 0.99.25), you must use at least one I<vname> -per expression, that is "CDEF:fourtytwo=2,40,+" will yield an error -message but not a I<vname> fourtytwo that's always equal to 42. +Z<> -=item B<PRINT:>I<vname>B<:>I<CF>B<:>I<format> +=item Miscellaneous -Calculate the chosen consolidation function I<CF> over the data-source -variable I<vname> and C<printf> the result to stdout using I<format>. -In the I<format> string there should be a '%lf' or '%le' marker in the -place where the number should be printed. +B<[-z|--lazy]> -If an additional '%s' is found AFTER the marker, the value will be scaled -and an appropriate SI magnitude unit will be printed in place of the '%s' -marker. The scaling will take the '--base' argument into consideration! +Only generate the graph, if the current graph is out of date or not +existent. -If a '%S' is used instead of a '%s', then instead of calculating the -appropriate SI magnitude unit for this value, the previously calculated -SI magnitude unit will be used. This is useful if you want all the values -in a PRINT statement to have the same SI magnitude unit. If there was -no previous SI magnitude calculation made, then '%S' behaves like a '%s', -unless the value is 0, in which case it does not remember a SI magnitude -unit and a SI magnitude unit will only be calculated when the next '%s' is -seen or the next '%S' for a non-zero value. +B<[-f|--imginfo E<lt>printfstrE<gt>]> -If you want to put a '%' into your PRINT string, use '%%' instead. +After the image has been created, the graph function uses printf +together with this format string to create output similar to the PRINT +function, only that the printf is supplied with the parameters +I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag +suitable for including the graph into a web page, the command line +would look like this: -=item B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format> + --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">' -Same as B<PRINT> but the result is printed into the graph below the legend. +B<[-c|--color I<COLORTAG#rrggbb>]> -=back +Override the default colors for the standard elements of the graph. +The I<COLORTAG> is one of C<BACK> ground, C<CANVAS>, C<SHADEA> for the +left and top border, C<SHADEB> for the right and bottom border, C<GRID>, +C<MGRID> for the major grid, C<FONT>, C<FRAME> and axis, C<ARROW>. +Each color is composed out of three hexadecimal numbers specifying +its color component (00 is off, FF is maximum) of red, green and blue. +You may set this option several times to alter multiple defaults. -B<Caveat:> When using the B<PRINT> and B<GRPRINT> functions to -calculate data summaries over time periods bounded by the current -time, it is important to note that the last sample will almost always -yield a value of UNKNOWN as it lies after the last update time. This -can result in slight data skewing, particularly with the B<AVERAGE> -function. In order to avoid this, make sure that your end time is at -least one heartbeat prior to the current time. +A green arrow is made by: C<--color ARROW:00FF00> -=over +B<[-a|--imgformat C<GIF>|C<PNG>]> +B<[-i|--interlaced]> +The default is to generate a non-interlaced GIF image. It is recommended +to generate PNG graphics as they take up to 40% less disk space and +20-30% less time to generate. -=item B<COMMENT:>I<text> +B<[-g|--no-legend]> -Like B<GPRINT> but the I<text> is simply printed into the graph. +Suppress generation of legend; only render the graph. -=item B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>] +B<[-b|--base E<lt>valueE<gt>]> -Draw a horizontal rule into the graph and optionally add a legend +If you are graphing memory (and NOT network traffic) this switch +should be set to 1024 so that one Kb is 1024 byte. For traffic +measurement, 1 kb/s is 1000 b/s. -=item B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>] +Z<> -Draw a vertical rule into the graph and optionally add a legend +=item Data and variables -=item B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]] +B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:[I<E<lt>time rangeE<gt>>][:I<E<lt>step timeE<gt>>]] -Plot for the requested data, using the color specified. Write a legend -into the graph. The 3 possible keywords B<LINE1>, B<LINE2>, and B<LINE3> -generate increasingly wide lines. If no color is defined, -the drawing is done 'blind' this is useful in connection with the -B<STACK> function when you want to ADD the values of two -data-sources without showing it in the graph. +B<CDEF:>I<E<lt>vnameE<gt>>=I<E<lt>RPN expressionE<gt>> -=item B<AREA>:I<vname>[B<#>I<rrggbb>[B<:>I<legend>]] +B<VDEF:>I<E<lt>vnameE<gt>>=I<E<lt>RPN expressionE<gt>> -Does the same as B<LINE?>, but the area between 0 and -the graph will be filled with the color specified. +You need at least one B<DEF> statement to generate anything. The +other statements are useful but optional. +See L<rrdgraph_data> and L<rrdgraph_rpn> for exact format. -=item B<STACK>:I<vname>[B<#>I<rrggbb>[B<:>I<legend>]] +Z<> -Does the same as B<LINE?>, but the graph gets stacked on top of the previous -B<LINE?>, B<AREA> or B<STACK> graph. Depending on the type of the -previous graph, the B<STACK> will be either a B<LINE?> or an B<AREA>. -This obviously implies that the first B<STACK> must be preceded by an -B<AREA> or B<LINE?> -- you need something to stack something onto in -the first place ;) +=item Graph and print elements -Note, that when you STACK onto *UNKNOWN* data, rrdtool will not draw -any graphics ... *UNKNOWN* is not zero ... if you want it to be zero -then you might want to use a CDEF argument with IF and UN functions to -turn *UNKNOWN* into zero ... +You need at least one graph element to generate an image and/or +at least one print statement to generate a report. +See L<rrdgraph_graph> for exact format. -=item B<TICK:>I<vname>B<#>I<rrggbb>[B<:>I<axis-fraction>[B<:>I<legend>]] +=back -Plot a tick mark (a vertical line) for each value of I<vname> that is -non-zero and not *UNKNOWN*. The I<axis-fraction> argument specifies the -length of the tick mark as a fraction of the y-axis; the default value -is 0.1 (10% of the axis). Note that the color specification is not -optional. +=head1 SEE ALSO -=back +L<rrdgraph> gives an overview of how B<rrdtool graph> works. +L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail, +L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements, +L<rrdgraph_graph> page describes all of the graph and print functions. -=head1 NOTES on legend arguments - -=head2 Escaping the colon - -In a ':' in a I<legend> argument will mark the end of the legend. To -enter a ':' into a legend, the colon must be escaped with a backslash '\:'. -Beware, that many environments look for backslashes themselves, so it may -be necessary to write two backslashes so that one is passed onto rrd_graph. - -=head2 String Formatting - -The text printed below the actual graph can be formated by appending special -escaped characters at the end of a text. When ever such a character occurs, -all pending text is pushed onto the graph according to the character -specified. - -Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for -right aligned and B<\c> for centered. In the next section there is an -example showing how to use centered formating. - -Normally there are two space characters inserted between every two items -printed into the graph. The space following a string can be suppressed by -putting a B<\g> at the end of the string. The B<\g> also squshes any space -inside the string if it is at the very end of the string. This can be used -in connection with B<%s> to supress empty unit strings. - - GPRINT:a:MAX:%lf%s\g - -A special case is COMMENT:B<\s> this inserts some additional vertical space -before placing the next row of legends. - -=head1 NOTE on Return Values - -Whenever rrd_graph gets called, it prints a line telling the size of -the gif it has just created to STDOUT. This line looks like this: XSIZExYSIZE. - -=head1 EXAMPLE 1 - - rrdtool graph demo.gif --title="Demo Graph" \ - DEF:cel=demo.rrd:exhaust:AVERAGE \ - "CDEF:far=cel,1.8,*,32,+"" \ - LINE2:cel#00a000:"D. Celsius" \ - LINE2:far#ff0000:"D. Fahrenheit\c" - -=head1 EXAMPLE 2 - -This example demonstrates the syntax for using IF and UN to set -I<*UNKNOWN*> values to 0. This technique is useful if you are -aggregating interface data where the start dates of the data sets -doesn't match. - - rrdtool graph demo.gif --title="Demo Graph" \ - DEF:idat1=interface1.rrd:ds0:AVERAGE \ - DEF:idat2=interface2.rrd:ds0:AVERAGE \ - DEF:odat1=interface1.rrd:ds1:AVERAGE \ - DEF:odat2=interface2.rrd:ds1:AVERAGE \ - CDEF:agginput=idat1,UN,0,idat1,IF,idat2,UN,0,idat2,IF,+,8,* \ - CDEF:aggoutput=odat1,UN,0,odat1,IF,odat2,UN,0,odat2,IF,+,8,* \ - AREA:agginput#00cc00:Input Aggregate \ - LINE1:agginput#0000FF:Output Aggregate - -Assuming that idat1 has a data value of I<*UNKNOWN*>, the CDEF expression - - idat1,UN,0,idat1,IF - -leaves us with a stack with contents of 1,0,NaN and the IF function -will pop off the 3 values and replace them with 0. If idat1 had a -real value like 7942099, then the stack would have 0,0,7942099 and the -real value would be the replacement. - -=head1 EXAMPLE 3 - -This example shows two ways to use the INF function. First it makes -the background change color during half of the hours. Then, it uses -AREA and STACK to draw a picture. If one of the inputs was UNKNOWN, -all inputs are overlaid with another AREA. - - rrdtool graph example.png --title="INF demo" \ - DEF:val1=some.rrd:ds0:AVERAGE \ - DEF:val2=some.rrd:ds1:AVERAGE \ - DEF:val3=some.rrd:ds2:AVERAGE \ - DEF:val4=other.rrd:ds0:AVERAGE \ - CDEF:background=val4,POP,TIME,7200,%,3600,LE,INF,UNKN,IF \ - CDEF:wipeout=val1,val2,val3,val4,+,+,+,UN,INF,UNKN,IF \ - AREA:background#F0F0F0 \ - AREA:val1#0000FF:Value1 \ - STACK:val2#00C000:Value2 \ - STACK:val3#FFFF00:Value3 \ - STACK:val4#FFC000:Value4 \ - AREA:wipeout#FF0000:Unknown - -The first CDEF uses val4 as a dummy value. It's value is removed immediately -from the stack. Then a decision is made based on the time that a sample was -taken. If it is an even hour (UTC time !) then the area will be filled. If -it is not, the value is set to UNKN and is not plotted. - -The second CDEF looks if any of val1,val2,val3,val4 is unknown. It does so by -checking the outcome of sum(val1,val2,val3,val4). Again, INF is returned when -the condition is true, UNKN is used to not plot the data. - -The different items are plotted in a particular order. First do the background, then use a -normal area to overlay it with data. Stack the other data until they are all plotted. Last but -not least, overlay everything with eye-hurting red -to signal any unknown data. - -Note that this example assumes that your data is in the positive half of the y-axis -otherwhise you would would have to add NEGINF in order to extend the coverage -of the rea to whole graph. - -=head1 EXAMPLE 4 - -If the specialized function B<RRAs> exist for aberrant behavior detection, they -can be used to generate the graph of a time series with confidence bands and -failures. - - rrdtool graph example.gif \ - DEF:obs=monitor.rrd:ifOutOctets:AVERAGE \ - DEF:pred=monitor.rrd:ifOutOctets:HWPREDICT \ - DEF:dev=monitor.rrd:ifOutOctets:DEVPREDICT \ - DEF:fail=monitor.rrd:ifOutOctets:FAILURES \ - TICK:fail#ffffa0:1.0:"Failures\: Average bits out" \ - CDEF:scaledobs=obs,8,* \ - CDEF:upper=pred,dev,2,*,+ \ - CDEF:lower=pred,dev,2,*,- \ - CDEF:scaledupper=upper,8,* \ - CDEF:scaledlower=lower,8,* \ - LINE2:scaledobs#0000ff:"Average bits out" \ - LINE1:scaledupper#ff0000:"Upper Confidence Bound: Average bits out" \ - LINE1:scaledlower#ff0000:"Lower Confidence Bound: Average bits out" - -This example generates a graph of the data series in blue (LINE2 with the scaledobs -virtual data source), confidence bounds in red (scaledupper and scaledlower virtual -data sources), and potential failures (i.e. potential aberrant aberrant behavior) -marked by vertical yellow lines (the fail data source). - -The raw data comes from an AVERAGE B<RRA>, the finest resolution of the observed -time series (one consolidated data point per primary data point). The predicted -(or smoothed) values are stored in the HWPREDICT B<RRA>. The predicted deviations -(think standard deviation) values are stored in the DEVPREDICT B<RRA>. Finally, -the FAILURES B<RRA> contains indicators, with 1 denoting a potential failure. - -All of the data is rescaled to bits (instead of Octets) by multiplying by 8. -The confidence bounds are computed by an offset of 2 deviations both above -and below the predicted values (the CDEFs upper and lower). Vertical lines -indicated potential failures are graphed via the TICK graph element, which -converts non-zero values in an B<RRA> into tick marks. Here an axis-fraction -argument of 1.0 means the tick marks span the entire y-axis, and hence become -vertical lines on the graph. - -The choice of 2 deviations (a scaling factor) matches the default used internally -by the FAILURES B<RRA>. If the internal value is changed (see L<rrdtune>), this -graphing command should be changed to be consistent. - -=head2 A note on data reduction: - -The B<rrdtool> I<graph> command is designed to plot data at a specified temporal -resolution, regardless of the actually resolution of the data in the RRD file. -This can present a problem for the specialized consolidation functions which -maintain a one-to-one mapping between primary data points and consolidated -data points. If a graph insists on viewing the contents of these B<RRAs> on a -coarser temporal scale, the I<graph> command tries to do something intelligent, -but the confidence bands and failures no longer have the same meaning and may -be misleading. +Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks. =head1 AUTHOR -Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt> - -=head1 REFERENCES +Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt> -[1] http://www.dotpoint.com/xnumber/rpn_or_adl.htm +This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt> diff --git a/doc/rrdgraph.src b/doc/rrdgraph.src new file mode 100644 index 0000000..3f9bda8 --- /dev/null +++ b/doc/rrdgraph.src @@ -0,0 +1,325 @@ +=include name + +=head1 SYNOPSYS + +B<rrdtool graph> I<filename> +[E<lt>B<L<option|rrdgraph/OPTIONS>>E<gt> ...] +E<lt>B<L<data definition|rrdgraph_data/DEF>>E<gt> +[E<lt>B<L<data definition|rrdgraph_data/DEF>>E<gt> ...] +[E<lt>B<L<data calculation|rrdgraph_data/CDEF>>E<gt> ...] +[E<lt>B<L<variable definition|rrdgraph_data/VDEF>>E<gt> ...] +[E<lt>B<L<graph element|rrdgraph_graph/GRAPH>>E<gt> ...] +[E<lt>B<L<print element|rrdgraph_graph/PRINT>>E<gt> ...] + +=head1 DESCRIPTION + +The B<graph> function of B<RRDtool> is used to represent the +data from an B<RRD> to a human viewer. Its main purpose is to +create a nice graphical representation but it can also generate +a numerical report. + +=head1 OVERVIEW + +B<rrdtool graph> needs data to work with, use one or more +B<L<data definition|rrdgraph_data/DEF>> statements to collect this +data. You are not limited to one database, it's perfectly legal to +collect data from two or more databases (one per statement though). + +If you want to display averages, maxima, percentiles etcetera +it is best to collect them now using the +B<L<variable definition|rrdgraph_data/VDEF>> statement. At this +stage, this command works at the unprocessed data from the B<RRD>. +I<(Note: this is not yet true; it works on consolidated information +right now)> + +The data fetched from the B<RRA> is then B<consolidated> so that +there is exactly one datapoint per pixel in the graph. If you do +not take care yourself, B<RRDtool> will expand the range slightly +if necessary (in that case the first pixel may very well become +unknown!). + +Sometimes data is not exactly as you would like to display it. For +instance, you might be collecting B<bytes> per second but want to +display B<bits> per second. This is where the +B<L<data calculation|rrdgraph_data/CDEF>> command is designed for. +After B<consolidating> the data, a copy is made and this copy is +modified using a rather flexible B<L<RPN|rrdgraph_rpn/>> command +set. If you use B<L<variable definition|rrdgraph_data/VDEF>> +statements after this, they work on the consolidated data and may +return other values for maximum, minimum etcetera! + +When you are done fetching and processing the data, it is time to +graph it (or print it). This ends the B<rrdtool graph> sequence. + +=head1 OPTIONS + +It is expected that most options will move to the graph definition +statements (after all, most of them do define graph elements...). + +=over 4 + +=item filename + +The name and path of the graph to generate. It is recommended to +end this in C<.png> or C<.gif> but B<rrdtool> does not enforce this. + +I<filename> can be 'C<->' to send the image to C<stdout>. In +that case, no other output is generated. + +Z<> + +=item Time range + +B<[-s|--start E<lt>timeE<gt>]> +B<[-e|--end E<lt>timeE<gt>]> +B<[--step E<lt>secondsE<gt>]> + +The start and end of what you would like to display, and which +B<RRA> the data should come from. Defaults are: 1 day ago until +now, with the best possible resolution. B<Start> and B<end> can +be specified in several formats, see +L<AT-STYLE TIME SPECIFICATION|rrdfetch/> and L<rrdgraph_examples>. +By default, B<rrdtool graph> calculates the width of one pixel in +the time domain and tries to get data from an B<RRA> with that +resolution. With the B<step> option you can alter this behaviour. +If you want B<rrdtool graph> to get data at a one-hour resolution +from the B<RRD>, set B<step> to 3600. Note: a step smaller than +one pixel will silently be ignored. + +Z<> + +=item Labels + +B<[-t|--title E<lt>stringE<gt>]> +B<[-v|--vertical-label E<lt>stringE<gt>]> + +A horizontal string at the top of the graph and/or a vertically +placed string at the left hand side of the graph. I<New: (not +yet implemented)> The string can contain formatter options that +are used to include variables (from B<VDEF>s) and newlines. + +Z<> + +=item Size + +B<[-w|--width E<lt>pixelsE<gt>]> +B<[-h|--heigth E<lt>pixelsE<gt>]> + +The width and height of the B<canvas> (the part of the graph with +the actual lines and such). Defaults are 400 pixels by 100 pixels. + +Z<> + +=item Limits + +I<Old behaviour, until the new options are implemented> +B<[-u|--upper-limit E<lt>valueE<gt>]> +B<[-l|--lower-limit E<lt>valueE<gt>]> +B<[-r|--rigid]> + +By default the graph will be autoscaling so that it displays the +portion of the y-axis that is actually used. You can change this +behaviour by setting the limits. The displayed y-axis will show +at least from B<lower-limit> to B<upper-limit>. Autoscaling will +still permit those boundaries to be stretched unless the B<rigid> +option is set. + +I<New behaviour, after the new options are implemented> +B<[--maximum-upper-limit E<lt>valueE<gt>]> +B<[--minimum-upper-limit E<lt>valueE<gt>]> +B<[--maximum-lower-limit E<lt>valueE<gt>]> +B<[--minimum-lower-limit E<lt>valueE<gt>]> + +By default the graph will be autoscaling so that it displays the +portion of the y-axis that is actually used. You can change this +behaviour by setting the limits. The displayed y-axis will show +at most B<maximum-upper-limit> and at least B<minimum-upper-limit> +at the top, and similarily at least B<maximum-lower-limit> and +at most B<minimum-lower-limit> at the bottom. The default is to +display at most B<infinity> (so: no limit) and at least +B<negative infinity> (no minimal value) at the top. The bottom of +the graph has similar defaults. Note that the minimum lower limit +is the lowest one so you should compare this with maximum upper +limit when you try to figure out what you should set. + +To make sure the graph shows the range of I<-1000> to I<2000>, +optionally expanding to no more than I<-3000> to I<4000>, +set the following options: + +--maximum-upper-limit 4000 --minimum-upper-limit 2000 +--maximum-lower-limit -1000 --minimum-lower-limit -3000 + +To mimic the old B<rigid> option, you can do: + +--maximum-upper-limit 4000 --minimum-upper-limit 4000 +--maximum-lower-limit -3000 --minimum-lower-limit -3000 + +B<[--alt-autoscale]> + +Sometimes the default algorithm for selecting the y-axis scale is not +performing very well. Normally the scale is selected from a predefined +set of ranges and this fails miserably when you need to graph something +like C<260 + 0.001 * sin(x)>. This option calculates the minimum and +maximum y-axis from the actual minimum and maximum values. Our example +would display slightly less than C<260-0.001> to slightly more than +C<260+0.001> (Contributed by Sasha Mikheev). + +B<[--alt-autoscale-max]> + +Where C<--alt-autoscale> will modify both the absolute maximum AND minimum +values, this option will only affect the maximum value. The minimum +value, if not defined on the command line, will be 0. This option can +be useful when graphing router traffic when the WAN line uses compression, +and thus the throughput may be higher than the WAN line speed. + +Z<> + +=item Grid + +=over 4 + +=item X-Axis + +B<[-x|--x-grid E<lt>I<GTMC<:>GSTC<:>MTMC<:>MSTC<:>LTMC<:>LSTC<:>LPRC<:>LFM>E<gt>|C<none>]> + +The x-axis label is quite complex to configure, if you don't have +very special needs it is probably best to rely on the autoconfiguration +to get this right. You can specify the string C<none> to skip the grid +and labels altogether. + +The grid is defined by specifying a certain amount of time in the I<?TM> +positions. You can choose from C<SECOND>, C<MINUTE>, C<HOUR>, C<DAY>, +C<WEEK>, C<MONTH> or C<YEAR>. Then you define how many of these should +pass between each line or label. This pair (I<?TM:?ST>) needs to be +specified for the base grid (I<G??>), the major grid (I<M??>) and the +labels (I<L??>). For the labels you also need to define a precision +in I<LPR> and a I<strftime> format string in I<LFM>. I<LPR> defines +where each label will be placed. If it is zero, the label will be +placed right under the corresponding line (useful for hours, dates +etcetera). If you specify a number of seconds here the label is +centered in this interval (useful for monday, januari etcetera). + +Example: C<--x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X> + +This places grid lines every 10 minutes, major grid lines every hour +and labels every 4 hours. The labels are placed under the major grid +lines as they specify exactly that time. + +Example: C<--x-grid HOUR:8:DAY:1:DAY:1:0:%A> + +This places grid lines every 8 hours, major grid lines and labels +each day. The labels are placed exactly between two major grid lines +as they specify the complete day and not just midnight. + +Z<> + +=item Y-Axis + +B<[-y|--y-grid I<E<lt>grid stepE<gt>:E<lt>label factorE<gt>>|C<none>]> + +Y-axis grid lines appear at each I<grid step> interval. Labels are +placed every I<label factor> lines. You can specify C<-y none> to +skip the grid and labels altogether. The default for this option is +to automatically select sensible values. + +B<[--alt-y-grid]> + +Place Y grid dynamically based on graph Y range. Algorithm ensures +that you always have grid, that there are enough but not too many +grid lines and the grid is metric. That is grid lines are placed +every 1, 2, 5 or 10 units. (contributed by Sasha Mikheev) + +B<[-o|--logarithmic]> + +Logarithmic y-axis scaling. + +B<[--units-exponent E<lt>valueE<gt>]> + +This sets the 10**exponent scaling of the y-axis values. Normally +values will be scaled to the appropriate units (k, M, etc.). However +you may wish to display units always in k (Kilo, 10e3) even if the data +is in the M (Mega, 10e6) range for instance. Value should be an +integer which is a multiple of 3 between -18 and 18 inclusive. It is +the exponent on the units you which to use. For example, use 3 to +display the y-axis values in k (Kilo, 10e3, thousands), use -6 to +display the y-axis values in u (Micro, 10e-6, millionths). Use a value +of 0 to prevent any scaling of the y-axis values. + +Z<> + +=back + +Z<> + +=item Miscellaneous + +B<[-z|--lazy]> + +Only generate the graph, if the current graph is out of date or not +existent. + +B<[-f|--imginfo E<lt>printfstrE<gt>]> + +After the image has been created, the graph function uses printf +together with this format string to create output similar to the PRINT +function, only that the printf is supplied with the parameters +I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag +suitable for including the graph into a web page, the command line +would look like this: + + --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">' + +B<[-c|--color I<COLORTAG#rrggbb>]> + +Override the default colors for the standard elements of the graph. +The I<COLORTAG> is one of C<BACK> ground, C<CANVAS>, C<SHADEA> for the +left and top border, C<SHADEB> for the right and bottom border, C<GRID>, +C<MGRID> for the major grid, C<FONT>, C<FRAME> and axis, C<ARROW>. +Each color is composed out of three hexadecimal numbers specifying +its color component (00 is off, FF is maximum) of red, green and blue. +You may set this option several times to alter multiple defaults. + +A green arrow is made by: C<--color ARROW:00FF00> + +B<[-a|--imgformat C<GIF>|C<PNG>]> +B<[-i|--interlaced]> + +The default is to generate a non-interlaced GIF image. It is recommended +to generate PNG graphics as they take up to 40% less disk space and +20-30% less time to generate. + +B<[-g|--no-legend]> + +Suppress generation of legend; only render the graph. + +B<[-b|--base E<lt>valueE<gt>]> + +If you are graphing memory (and NOT network traffic) this switch +should be set to 1024 so that one Kb is 1024 byte. For traffic +measurement, 1 kb/s is 1000 b/s. + +Z<> + +=item Data and variables + +B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:[I<E<lt>time rangeE<gt>>][:I<E<lt>step timeE<gt>>]] + +B<CDEF:>I<E<lt>vnameE<gt>>=I<E<lt>RPN expressionE<gt>> + +B<VDEF:>I<E<lt>vnameE<gt>>=I<E<lt>RPN expressionE<gt>> + +You need at least one B<DEF> statement to generate anything. The +other statements are useful but optional. +See L<rrdgraph_data> and L<rrdgraph_rpn> for exact format. + +Z<> + +=item Graph and print elements + +You need at least one graph element to generate an image and/or +at least one print statement to generate a report. +See L<rrdgraph_graph> for exact format. + +=back + +=include see_also diff --git a/doc/rrdgraph_data.src b/doc/rrdgraph_data.src new file mode 100644 index 0000000..938fb10 --- /dev/null +++ b/doc/rrdgraph_data.src @@ -0,0 +1,73 @@ +=include name + +=head1 SYNOPSYS + +B<DEF>:I<vname>=I<RRD file>:I<ds name>:I<CF>[:[I<time range>][:I<step size>]] + +B<VDEF>:I<vname>=I<RPN expression> + +B<CDEF>:I<vname>=I<RPN expression> + +=head1 DESCRIPTION + +These three instructions collect the data out of the B<RRD> files, +optionally altering it (think of a bytes to bits conversion) and +if desired you can define variables containing useful information +such as maximum, mininimum etcetera. Two of the instructions use +a language called B<RPN> which is described in its own manual page. + +=head1 DEF + +B<DEF>:I<vname>=I<RRD file>:I<ds name>:I<CF>[:[I<time range>][:I<step size>]] + +This command fetches data from an B<RRD> file. The virtual name +I<vname> can then be used throughout the rest of the script. By +default, an B<RRA> which contains the correct consolidated data +at an appropriate resolution will be chosen. The resolution can +be overriden with the L<--step|rrdgraph/item_Time> option. +I<Not yet implemented:>[ The resolution can be overriden by specifying +the B<step size>.] I<Not yet implemented:> [ The time span of this data +is the same as for the graph by default, you can override this by +specifying the B<time range>. ] + +If the resolution of the data is higher than the resolution of off +graph, the data will be further consolidated. This may result in +a graph that spans slightly more time than requested. +Ideally each point in the graph should correspond with one B<CDP> +from an B<RRA>. For instance, if your B<RRD> has an B<RRA> with +a resolution of 1800 seconds per B<CDP>, you should create an +image with width 400 and time span 400*1800 seconds (use appropriate +start and end times, such as C<--start end-8days8hours>). + +Example: C<DEF:mydata=router.rrd:ds0:AVERAGE> + +Example: C<DEF:januari=router.rrd:ds0:AVERAGE:start=20010101 end=20010201> + +=head1 VDEF + +B<VDEF>:I<vname>=I<RPN expression> + +This command returns a value and/or a time according to the B<RPN> +statements used. The resulting I<vname> will, depending on the +functions used, have a value and a time component. When you use +this I<vname> in another B<RPN> expression, you are effectively +inserting its value just as if you had put a number at that place. +The variable can also be used in the various graph and print +elements. I<Not yet implemented:> [ Everywhere you can insert a +number, you can also use the B<VDEF> (provided that it is set of course) ] + +Example: C<VDEF:avg=mydata,AVERAGE> + +=head1 CDEF + +B<CDEF>:I<vname>=I<RPN expression> + +This command creates a new set of data points (in memory only, not +in the B<RRD> file) out of one or more other data series. The B<RPN> +instructions are used to evaluate a mathematical function on each +data point. The resulting I<vname> can then be used further on in +the script, just as if it were generated by a B<DEF> instruction. + +Example: C<CDEF:mydatabits=mydata,8,*> + +=include see_also diff --git a/doc/rrdgraph_examples.src b/doc/rrdgraph_examples.src new file mode 100644 index 0000000..2c61c40 --- /dev/null +++ b/doc/rrdgraph_examples.src @@ -0,0 +1,111 @@ +=include name + +=head1 SYNOPSYS + +B<rrdtool graph /home/httpd/html/test.png --img-format PNG \> + +followed by any of the examples below + +=head1 DESCRIPTION + +For your convenience some of the commands are explained here +by using detailed examples. They are not always cut-and-paste +ready because comments are intermixed with the examples. + +=head1 EXAMPLES + +=head2 Nicely formatted legend section + + DEF:ds0=/home/rrdtool/data/router1.rrd:ds0:AVERAGE + DEF:ds1=/home/rrdtool/data/router1.rrd:ds1:AVERAGE + VDEF:ds0max=ds0,MAXIMUM,8,* + VDEF:ds0avg=ds0,AVERAGE,8,* + VDEF:ds0min=ds0,MINIMUM,8,* + VDEF:ds0pct=95,ds0,PERCENTILE,8,* + VDEF:ds1max=ds1,MAXIMUM,8,* + VDEF:ds1avg=ds1,AVERAGE,8,* + VDEF:ds1min=ds1,MINIMUM,8,* + VDEF:ds1pct=95,ds1,PERCENTILE,8,* +Note: consolidation occurs here. + CDEF:ds0bits=ds0,8,* + CDEF:ds1bits=ds1,8,* +Note: 10 spaces to move text to the right + COMMENT:" " +Note: three times size == 11 chars, "###.## xBps" + COMMENT:"Maximum " + COMMENT:"Average " + COMMENT:"Minimum " +Note: last line contains new-line character + COMMENT:"95th percentile\n" + AREA:ds0bits#00C000:"Inbound " + GPRINT:ds0max:"%6.2lf %Sbps" + GPRINT:ds0avg:"%6.2lf %Sbps" + GPRINT:ds0min:"%6.2lf %Sbps" + GPRINT:ds0pct:"%6.2lf %Sbps\n" + LINE1:ds1bits#0000FF:"Outbound" + GPRINT:ds1max:"%6.2lf %Sbps" + GPRINT:ds1avg:"%6.2lf %Sbps" + GPRINT:ds1min:"%6.2lf %Sbps" + GPRINT:ds1pct:"%6.2lf %Sbps\n" + +=head2 Offsetting a line on the y-axis + +Depending on your needs you can do this in two ways: + +=over 4 + +=item * + +Offset the data, then graph this + + DEF:mydata=my.rrd:ds:AVERAGE +Note: this will also influence anything that uses "data" + CDEF:data=mydata,100,+ + LINE1:data#FF0000:"Data with offset" + +=item * + +Graph the original data, with an offset + + DEF:mydata=my.rrd:ds:AVERAGE +Note: no color in the first line so it is not visible + LINE1:100 +Note: the second line gets stacked on top of the first one + LINE1:data#FF0000:"Data with offset":STACK + +=back + +=head2 Time ranges + + Last four weeks: --start end-4w --end 00:00 + Januari 2001: --start 200101010000 --end start+31d + Januari 2001: --start 200101010000 --end 200102010000 + Last hour: --start end-1h + Last 24 hours: <nothing at all> + Yesterday: --end 00:00 + +=head2 Viewing Januari+Februari 2000 and 2001 together + +Define a graph area of 31+29 days (!) spanning Jan. and Feb. + --start 20000101 --end 20000301 + DEF:jan2000=router.rrd:ds0:AVERAGE:start 20000101 end start+31d + DEF:jan2001=router.rrd:ds0:AVERAGE:start 20010101 end start+31d +Note: mind the extra day in 2000 ... + DEF:feb2000=router.rrd:ds0:AVERAGE:start 20000201 end start+29d +Note: 29 feb 2001 is *unknown* + DEF:feb2001=router.rrd:ds0:AVERAGE:start 20010201 end start+28d + VDEF:offset=jan2001,FIRST,jan2000,FIRST,-,-1,* + [ more of the usual VDEF and CDEF stuff if you like ] + LINE1:jan2000#00003F:"Januari 2000" + [ gprint stuff ] + LINE1:feb2001#003F00:"Februari 2000" + [ gprint stuff ] +Note: offset is made negative by the VDEF statement + SHIFT:offset + LINE1:jan2001#0000FF:"Januari 2001" + [ gprint stuff ] + LINE1:feb2001#00FF00:"Februari 2001" + [ gprint stuff ] + +=include see_also + diff --git a/doc/rrdgraph_graph.src b/doc/rrdgraph_graph.src new file mode 100644 index 0000000..44beac7 --- /dev/null +++ b/doc/rrdgraph_graph.src @@ -0,0 +1,222 @@ +=include name + +=head1 SYNOPSYS + +I<Depriciated commands> + +[B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>] +[B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>] +[B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]] +[B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]] + +I<available commands> + +[B<PRINT:>I<vname>B<:>I<format>] +[B<GPRINT:>I<vname>B<:>I<format>] +[B<COMMENT:>I<text>] +[B<VRULE:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]] +[B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]][B<:STACK>] +[B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]][B<:STACK>] + +I<to be implemented commands> + +[B<SHIFT:>I<vname>] +[B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]] + +=head1 DESCRIPTION + +These instructions allow you to generate your image or report. +If you don't use any graph elements, no graph is generated. +Similarly no report is generated if you don't use print options. + +=head1 PRINT + +B<PRINT:>I<vname>B<:>I<CF>B<:>I<format> + +I<Depriciated. Use the new form of this command in new scripts.> +The first form of this command is to be used with B<CDEF> I<vname>s. + +B<PRINT:>I<vname>B<:>I<format> + +Depending on the context, either the value component or the time +component of a B<VDEF> is printed using I<format>. It is an error +to specify a I<vname> generated by a B<DEF> or B<CDEF>. + +Any text in I<format> is printed literally with one exception: +The percent character introduces a formatter string. This string +can be: + +For printing values: + +=over 4 + +=item * + +B<%%> just prints a literal '%' character + +=item * + +B<%#.#le> (where # is an optional number) prints like 1.2346e+04 + +=item * + +B<%#.#lf> prints like 12345.6789 + +=item * + +B<%s> place this after B<%le> or B<%lf>. This will be replaced by the +appropriate SI magnitude unit and the value will be scaled +accordingly (123456 -> 123.456 k) + +=item * + +B<%S> is similar to B<%s>. It does however use a previously defined +magnitude unit. If there is no such unit yet, it tries to define +one (just like B<%s>). However, if the value is zero, the magnitude +unit stays undefined. Thus, formatter strings using B<%S> and no B<%s> +will all use the same magnitude unit except for zero values. + +=back + +For printing times: + +=over 4 + +=item * + +B<%%> just prints a literal '%' character + +=item * + +B<%a, %A> prints abbreviated, full weekday name + +=item * + +B<%b, %B> prints abbreviated, full month name + +=item * + +B<%d, %m, %y, %H, %M, %S> day,month,year,hour,minute,second all in two-digit format + +=item * + +B<%Y> year in 4-digit format + +=item * + +B<%I, %p> hour (01..12), 'am' or 'pm' + +=item * + +B<%j, %w> day of the week (0..6), day of the year (1..366) + +=item * + +B<%c, %x, %X> date+time, date, time + +=item * + +B<%U, %W> week number of the current year with either the first sunday or +the first monday determining the first week + +=item * + +B<%Z> time zone + +=back + +=head1 GRAPH + +B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format> + +I<Depriciated. Use the new form of this command in new scripts.> +This is the same as B<PRINT> but now it is printed inside the graph. +See L<PRINT> for more information. + +B<GPRINT:>I<vname>B<:>I<format> + +This is the same as B<PRINT> but now it is printed inside the graph. +See L<PRINT> for more information. + +B<COMMENT:>I<text> + +Text is printed literally in the legend section of the graph + +B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>] + +I<Depriciated. Use a VDEF and a LINEx in new scripts.> + +Draw an horizontal line at I<value>. Its color is composed from three +hexadecimal numbers specifying the color components (00 is off, FF is +maximum) red, green and blue. Optionally a legend box and string is +printed in the legend section. + +B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>] + +Draw a vertical line at I<time>. Its color is composed from three +hexadecimal numbers specifying the color components (00 is off, FF is +maximum) red, green and blue. Optionally a legend box and string is +printed in the legend section. I<time> may be a number or a variable +from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here. + +B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>] + +Draw a line of the specified width into the graph. If the color +is not specified, the drawing is done 'blind'. This is useful when +stacking something else on top of this line. Also optional is the +legend box and string which will be printed in the legend section +if specified. The B<vname> can be generated by B<DEF>, B<VDEF> and +B<CDEF>. If the optional B<STACK> modifier is used, this line is +stacked on top of the previous element which can be a B<LINEx> or +an B<AREA> + +B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>] + +See B<LINEx>, however the area between the x-axis and the line will +also be filled. + +B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]] + +I<Depriciated. Use the B<STACK> modifiers on the other commands.> +I<Note: the comments on stacking are still valid...> +Repeats the last B<LINEx> or B<AREA> however it doesn't start at the +x-axis but rather on top of the previous element. This implies that +there needs to be something to stack on. An invisible B<LINEx> or +B<AREA> is something you can stack on! + +Note: When you stack on something that was I<unknown>, the whole +stack will be I<unknown> for that point in time. If the beginning +is undefined, there's no way to end somewhere... If you want to +graph this stacked variable anyway you need to make sure that the +B<LINEx> or B<AREA> it gets stacked on is not unknown. Use a CDEF +instruction with B<IF> and B<UN> to do so. + +B<THE NEXT STUFF IS NOT YET IMPLEMENTED> + +B<SHIFT:>I<offset in seconds> + +Using this command B<RRDtool> will graph the following elements +with the specified offset. For instance, you can specify an +offset of S<( 7*24*60*60 = ) 604800 seconds> to "look back" one +week. Make sure to notify the viewer you did so... +The offset will be valid until the next B<SHIFT> command, which +can have an offset of zero to restore normal graphing. +As with the other grapher elements, you can specify a number or +a variable here. + +B<RRDtool> has now support for B<pie charts>. If you include the +B<PART> command, the canvas is extended to make room for a chart +(or, if no other graph elements are used, the canvas is solely +used for the pie chart). The size of the canvas is determined by +the lesser of L<width and height|rrdgraph/item_Size>. + +B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>] + +Draw a part of pie. Pie parts will be concatenated, the first one +will start at the top and parts will be created clockwise. +The size of the part is defined by the value part of +the L<VDEF|rrdgraph_data/VDEF> function. It should return +a number between 0 and 100, being a percentage. +Providing wrong input will produce undefined results. + +=include see_also diff --git a/doc/rrdgraph_rpn.src b/doc/rrdgraph_rpn.src new file mode 100644 index 0000000..3278f84 --- /dev/null +++ b/doc/rrdgraph_rpn.src @@ -0,0 +1,219 @@ +=include name + +=head1 SYNOPSYS + +I<E<lt>RPN expressionE<gt>> := +I<E<lt>vnameE<gt>>|I<E<lt>operatorE<gt>>|I<E<lt>valueE<gt>> +[ , I<E<lt>RPN expressionE<gt>>] + +=head1 DESCRIPTION + +If you have ever used a traditional HP calculator you already know +B<RPN>. The idea behind B<RPN> is that you have a stack and push +your data onto this stack. Whenever you execute an operation, it +takes as many elements from the stack as needed. Pushing is done +implicit so whenever you specify a number or a variable, it gets +pushed automatically. + +At the end of the calculation there should be one and exactly one +value left on the stack. This is the outcome of the function and +this is what is put into the I<vname>. For B<CDEF> instructions, +the stack is processed for each data point on the graph. B<VDEF> +instructions work on an entire data set in one run. + +Example: C<CDEF:mydatabits=mydata,8,*> + +This means: push variable I<mydata>, push the number 8, execute +the operator I<+>. The operator needs two elements and uses those +to return one value. This value is then stored in I<mydatabits>. +As you may have guessed, this instruction means nothing more than +I<mydatabits = mydata * 8>. The real power of B<RPN> lies in the +fact that it is always clear in which order to process the input. +For expressions like C<a = b + 3 * 5> you need to multiply 3 with +5 first before you add I<b> to get I<a>. However, with parentheses +you could change this order: C<a = (b + 3) * 5>. In B<RPN>, you +would do C<a = b, 3, +, 5, *> and need no parentheses. + +=head1 OPERATORS + +=over 4 + +=item Boolean operators + +B<LT, LE, GT, GE, EQ, NE> + +I<Note: NE is not yet implemented> + +Pop two elements from the stack, compare them for the selected condition +and return 1 for true or 0 for false. Comparing an I<unknown> or an +I<infinite> value will always result in 0 (false). + +B<UN, ISINF> + +I<Note: ISINF is not yet implemented> + +Pop one element from the stack, compare this to I<unknown> respectively +to I<positive or negative infinity>. Returns 1 for true or 0 for false. + +B<IF> + +Pops three elements from the stack. If the last element is 0 (false), +the first value is pushed back onto the stack, otherwise the second +popped value is pushed back. This does, indeed, mean that any value +other than 0 is considered true. +I<Note: Should this change? It should IMHO as all the other functions +would return unknown if A,B or C were unknown> + +Example: C<A,B,C,IF> should be read as C<if (A) then (B) else (C)> + +Z<> + +=item Comparing values + +B<MIN, MAX> + +Pops two elements from the stack and returns the lesser or larger. +The two numbers shouldn't be I<infinite> or I<unknown>, if they are +that value is pushed back onto the stack as the result. + +B<LIMIT> + +Pops two elements from the stack and uses them to define a range. +Then it pops another element and if it falls inside the range, it +is pushed back. If not, an I<unknown> is pushed. + +The range defined includes the two boundaries (so: a number equal +to one of the boundaries will be pushed back). If any of the three +numbers involved is either I<unknown> or I<infinite> this function +will always return an I<unknown> + +Example: C<CDEF:a=alpha,0,100,LIMIT> will return I<unknown> if +alpha is lower than 0 or if it is higher than 100. + +Z<> + +=item Arithmetics + +B<+, -, *, /, %> + +Add, subtract, multiply, divide, modulo + +B<SIN, COS, LOG, EXP> + +Sine, cosine (input in radians), log, exp (natural logarithm) + +B<FLOOR, CEIL> + +Round down,up to the nearest integer + +Z<> + +=item Special values + +B<UNKN> + +Pushes an unknown value on the stack + +B<INF, NEGINF> + +Pushes a positive or negative infinite value on the stack. When +such a value is graphed, it appears at the top or bottom of the +graph, no matter what the actual value on the y-axis is. + +B<PREV> + +Pushes an I<unknown> value if this is the first value of a data +set or otherwise the result of this B<CDEF> at the previous time +step. This allows you to do calculations across the data. This +function cannot be used in B<VDEF> instructions. + +Z<> + +=item Time + +Time inside RRDtool is measured in seconds since the epoch. This +epoch is defined to be S<C<Thu Jan 1 00:00:00 UTC 1970>>. + +Z<> + +=over 4 + +=item NOW + +Pushes the current time on the stack. + +Z<> + +=item TIME + +Pushes the time the currently processed value was taken onto the stack. + +Z<> + +=item LTIME + +Takes the time as defined by B<TIME>, applies the time zone offset +valid at that time including daylight saving time if your OS supports +it, and pushes the result on the stack. There is an elaborate example +in the examples section on how to use this. + +=back + +For B<VDEF> operations, B<TIME> and B<LTIME> have a different meaning +I<not yet implemented>. As the B<VDEF> statement does not work per +value but rather on a complete time series, there is no such thing as +the currently processed value. However, if you have used an operator +that returned a time component and would like to have this available +in the value component in stead (so you can use it as a number), you +can use B<TIME> or B<LTIME> for that. + +Z<> + +=item Processing the stack directly + +B<DUP, POP, EXC> + +Duplicate the top element, remove the top element, exchange the two +top elements. + +Z<> + +=item Selecting characteristics + +These operators work only on B<VDEF> statements. +I<We can make most of them work at DEF and CDEF statements. If we do +so, we have a moving (not rolling!) average, max,min etcetera> + +Z<> + +=over 4 + +=item MAXIMUM, MINIMUM, AVERAGE + +Return the corresponding value + +Z<> + +=item LAST, FIRST + +Return the last,first value including its time + +Z<> + +=item PERCENTILE + +Should follow a B<DEF> or B<CDEF> I<vname>. This I<vname> is popped, +another number is popped which is a certain percentage (0..100). The +data set is then sorted and the value returned is chosen such that +I<percentage> percent of the values is lower or equal than the result. +I<Unknown> values are considered lower than any finite number for this +purpose so if this operator returns an I<unknown> you have quite a lot +of them in your data... + +Example: C<VDEF:perc95=95,mydata,PERCENTILE> + +=back + +=back + +=include see_also diff --git a/doc/see_also.inc b/doc/see_also.inc new file mode 100644 index 0000000..eb2fa5b --- /dev/null +++ b/doc/see_also.inc @@ -0,0 +1,14 @@ +=head1 SEE ALSO + +L<rrdgraph> gives an overview of how B<rrdtool graph> works. +L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail, +L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements, +L<rrdgraph_graph> page describes all of the graph and print functions. + +Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks. + +=head1 AUTHOR + +Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt> + +This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt> diff --git a/src/rrd_tune.c b/src/rrd_tune.c index b45e5db..f38319e 100644 --- a/src/rrd_tune.c +++ b/src/rrd_tune.c @@ -5,6 +5,11 @@ ***************************************************************************** * $Id$ * $Log$ + * Revision 1.3 2001/03/07 21:21:54 oetiker + * complete rewrite of rrdgraph documentation. This also includs info + * on upcomming/planned changes to the rrdgraph interface and functionality + * -- Alex van den Bogaerdt <alex@slot.hollandcasino.nl> + * * Revision 1.2 2001/03/04 13:01:55 oetiker * Aberrant Behavior Detection support. A brief overview added to rrdtool.pod. * Major updates to rrd_update.c, rrd_create.c. Minor update to other core files. @@ -12,9 +17,6 @@ * by old rrdtool versions. See http://cricket.sourceforge.net/aberrant/rrd_hw.htm * -- Jake Brutlag <jakeb@corp.webtv.net> * - * Revision 1.1.1.1 2001/02/25 22:25:06 oetiker - * checkin - * *****************************************************************************/ #include "rrd_tool.h"