X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=doc%2Frrdgraph.pod;h=eeab6bbc6c42a1bc0f4cfd87a69018a6381443af;hb=5571bcfcae02ea6cca124844489d683ff04a7502;hp=8e8038e98c1b56e1253d73907fd3a8b629fc1678;hpb=7c016dfa001ae254bf4e18126f814ee8f0abd821;p=rrdtool.git 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
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>]]]> +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>