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.
+Documentation for version 1.2.0
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)>
+B<L<variable definition|rrdgraph_data/VDEF>> statement.
+Currently this makes no difference but in a future version
+of rrdtool you may want to collect these values before consolidation.
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 necessary (in that case the first and/or last 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
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!
+set.
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
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.
+placed string at the left hand side of the graph.
Z<>
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.
-If you specify the B<--only-graph> and set the height < 32 pixels you will
-get a tiny graph image to use as an icon in a potential overview. All
-labeling will be stripped off the graph.
+If you specify the B<--only-graph> option and set the height E<lt> 32
+pixels you will get a tiny graph image to use as an icon in a potential
+overview. All labeling will be stripped off the graph.
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]>
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 similarly 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<[-A|--alt-autoscale]>
Sometimes the default algorithm for selecting the y-axis scale is not
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) ]
+elements.
Example: C<VDEF:avg=mydata,AVERAGE>
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,*
+=head2 Viewing This week and last week together
+
+ --end now --start end-1w
+ DEF:thisweek=router.rrd:ds0:AVERAGE
+ DEF:lastweek=router.rrd:ds0:AVERAGE:end=now-1w:start=end-1w
+shift the data forward by one week (604800 seconds)
+ SHIFT:lastweek:604800
[ 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 ]
+ AREA:lastweek#0000FF:Last\ week
+ LINE1:thisweek#FF0000:This\ week
=include see_also
=over 4
-=item B<to be deprecated commands>
+=item B<old-style commands, for compatibility>
=over 4
=back
+Z<>
+
=item B<available commands>
=over 8
=item B<VRULE> : I<vname> # I<color> [ : I<legend> ]
-=item B<LINE>{I<width>} : I<vname> # I<color> [ : I<legend> ] [ : STACK ]
+=item B<LINE>{I<width>} : I<vname> # I<color> [ : I<legend> ] [ C<:STACK> ]
-=item B<AREA> C<:> I<vname> C<#> I<color> [ C<:> I<legend> ] [ C<:> C<STACK> ]
+=item B<AREA> C<:> I<vname> C<#> I<color> [ C<:> I<legend> ] [ C<:STACK> ]
=cut
=item B<HRULE> : I<value> # I<color> [ :I<legend> ]
-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. I<value> can be a variable from a B<VDEF>.
-It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
+I<Deprecated. Use B<LINEx> in new scripts.>
=item B<VRULE> : I<vname> # I<color> [ : I<legend> ]
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.
-=item B<LINE>{I<width>} : I<vname> # I<color> [ : I<legend> ] [ : STACK ]
+=item B<LINE>{I<width>} : I<{vname or number}> # I<color> [ : I<legend> ]
+[ C<: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
stacked on top of the previous element which can be a B<LINEx> or
an B<AREA>
-=item B<AREA> C<:> I<vname> C<#> I<color> [ C<:> I<legend> ] [ C<:> C<STACK> ]
+=item B<AREA> C<:> I<vname> C<#> I<color> [ C<:> I<legend> ] [ C<:STACK> ]
See B<LINE>, however the area between the x-axis and the line will
also be filled.
-=item B<STACK> : I<vname> # I<color> [ :I<legend> ]
+=item B<TICK> : I<vname> B<#> I<rrggbbaa> [ : I<fraction> [ : I<legend> ] ]
-I<Deprecated. 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, an unknown value is not!
-
-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.
+Plot a tick mark (a vertical line) for each value of I<vname> that is
+non-zero and not *UNKNOWN*. The I<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.
+
+=item B<SHIFT> : I<vname> : I<offset>
+
+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...
+As with the other graphing elements, you can specify a number or
+a variable here.
=cut
=pod
-=item B<TICK> : I<vname> B<#> I<rrggbbaa> [ : I<fraction> [ : I<legend> ] ]
+=item B<STACK> : I<vname> # I<color> [ :I<legend> ]
-Plot a tick mark (a vertical line) for each value of I<vname> that is
-non-zero and not *UNKNOWN*. The I<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.
+I<Deprecated. Use the B<STACK> modifiers on the other commands.>
-=item B<SHIFT> : I<vname> : I<offset>
+=back
-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 graphing elements, you can specify a number or
-a variable here.
+B<Some notes on stacking>
-=back
+When stacking, an element is not placed above the X-axis but rather
+on top of the previous element. There must be something to stack
+upon.
+
+An B<invisible> LINEx or AREA B<is> present and can be stacked upon.
+
+An B<unknown> value makes the entire stack unknown from that moment on.
+You don't know where to begin (the unknown value) and therefore do
+not know where to end.
+
+If you want to make sure you will be displaying a certain variable,
+make sure never to stack upon the unknown value. Use a CDEF instruction
+with B<IF> and B<UN> to do so.
=head1 NOTES on legend arguments
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<VDEF:maximum=mydata,MAXIMUM>
+
+This will set variable "maximum" which you now can use in the rest
+of your RRD script.
+
Example: C<CDEF:mydatabits=mydata,8,*>
This means: push variable I<mydata>, push the number 8, execute
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>
+other than 0 is considered to be true.
Example: C<A,B,C,IF> should be read as C<if (A) then (B) else (C)>
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
+B<NOW>
Pushes the current time on the stack.
-Z<>
-
-=item TIME
+B<TIME>
Pushes the time the currently processed value was taken onto the stack.
-Z<>
-
-=item LTIME
+B<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>
Z<>
-=item Selecting characteristics
+=back
-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>
+=head1 VARIABLES
-Z<>
+These operators work only on B<VDEF> statements.
=over 4
Example: C<VDEF:avg=mydata,AVERAGE>
-Z<>
-
=item LAST, FIRST
Return the last,first value including its time. The time for
Example: C<VDEF:first=mydata,FIRST>
-Z<>
-
=item TOTAL
Returns the rate from each defined time slot multiplied with the
Example: C<VDEF:total=mydata,TOTAL>
-Z<>
-
=item PERCENT
Should follow a B<DEF> or B<CDEF> I<vname>. This I<vname> is popped,
=back
-=back
-
=include see_also
projects / rrdtool.git / commitdiff