X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=doc%2Frrdgraph.pod;h=8689febaf0e9c5eb1d51b43a9a59ed301ddcb095;hb=5cbf604e8be474094aef371c53917ec9046bad32;hp=8e8038e98c1b56e1253d73907fd3a8b629fc1678;hpb=7c016dfa001ae254bf4e18126f814ee8f0abd821;p=rrdtool.git
diff --git a/doc/rrdgraph.pod b/doc/rrdgraph.pod
index 8e8038e..8689feb 100644
--- a/doc/rrdgraph.pod
+++ b/doc/rrdgraph.pod
@@ -1,660 +1,355 @@
=head1 NAME
-rrdtool graph - Create a graph based on data from one or several RRD
-
-=for html
-
-=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<[BIB<=>IB<:>IB<:>I]>
-S<[BIB<=>I]>
-S<[BIB<:>IB<:>I]>
-S<[BIB<:>IB<:>I]>
-S<[BI]>
-S<[BIB<#>I[B<:>I]]>
-S<[BIB<#>I[B<:>I]]>
-S<[B{B<1>|B<2>|B<3>}B<:>I[B<#>I[B<:>I]]]>
-S<[BI[B<#>I[B<:>I]]]>
-S<[BI[B<#>I[B<:>I]]]>
-S<[BIB<#>I[B<:>I[B<:>I]]]>
+=cut
-=head1 DESCRIPTION
-
-The B functions main purpose is to create graphical
-representations of the data stored in one or several Bs. Apart
-from generating graphs, it can also extract numerical reports.
-
-=over
-
-=item I
-
-The name of the graph to generate. Since B outputs
-GIFs and PNGs, it's recommended that the filename end in either
-F<.gif> or F<.png>. B does not enforce this, however.
-If the I 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 (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
-documentation for a detailed explanation on how to specify time.
-
-=item B<-e>|B<--end> I (default now)
-
-The time when the graph should end. Time in seconds since epoch.
-See also AT-STYLE TIME SPECIFICATION section in the I
-documentation for a detailed explanation of ways to specify time.
-
-=item B<-x>|B<--x-grid> I (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.
-
-The x-axis label and grid can be configured, using the following format:
-
-IB<:>IB<:>IB<:>IB<:>I:IB<:>IB<:>I
-
-You have to configure three elements making up the x-axis labels and
-grid. The base grid (I), the major grid (I) and the labels
-(I). The configuration is based on the idea that you first
-specify a well known amount of time (I) and then say how many
-times it has to pass between each grid line or label (I). For the
-label you have to define two additional items: The precision of the
-label in seconds (I) and the strftime format used to generate the
-text of the label (I).
-
-The I elements must be one of the following keywords: B,
-B, B, B, B, B or B.
-
-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
-
-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:I (default autoconfigure)
-
-Makes vertical grid lines appear at I interval. Every
-I 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.
-
-=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 (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
-
-vertical label on the left side of the graph. This is normally used to
-specify the units used.
-
-=item B<-w>|B<--width> I (default 400 pixel)
-
-Width of the drawing area within the graph. This affects the size of the
-gif.
-
-=item B<-h>|B<--height> I (default 100 pixel)
+WARNING: DO NOT EDIT THE POD FILES. THEY ARE AUTO-GENERATED
-Width of the drawing area within the graph. This affects the size of the
-gif.
+=pod
-=item B<-i>|B<--interlaced> (default: false)
+rrdtool graph - Round Robin Database tool grapher functions
-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.
+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.
-=item B<-f>|B<--imginfo> I
-
-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, I and I. In order to generate an B tag
-suitable for including the graph into a web page, the command line
-would look like this:
+=head1 SYNOPSYS
- --imginfo ' '
+B I
+[EB>E ...]
+EB>E
+[EB>E ...]
+[EB>E ...]
+[EB>E ...]
+[EB>E ...]
+[EB>E ...]
-=item B<-a>|B<--imgformat> B|B (default: GIF)
+=head1 DESCRIPTION
-Allows you to produce PNG output from rrdtool.
+The B function of B is used to represent the
+data from an B to a human viewer. Its main purpose is to
+create a nice graphical representation but it can also generate
+a numerical report.
-=item B<-z>|B<--lazy> (default: false)
+=head1 OVERVIEW
-Only generate the graph, if the current gif is out of date or not
-existent.
+B needs data to work with, use one or more
+B> 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).
-=item B<-u>|B<--upper-limit> I (default autoconfigure)
+If you want to display averages, maxima, percentiles etcetera
+it is best to collect them now using the
+B> statement. At this
+stage, this command works at the unprocessed data from the B.
+I<(Note: this is not yet true; it works on consolidated information
+right now)>
-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.
+The data fetched from the B is then B so that
+there is exactly one datapoint per pixel in the graph. If you do
+not take care yourself, B will expand the range slightly
+if necessary (in that case the first pixel may very well become
+unknown!).
-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.
+Sometimes data is not exactly as you would like to display it. For
+instance, you might be collecting B per second but want to
+display B per second. This is where the
+B> command is designed for.
+After B the data, a copy is made and this copy is
+modified using a rather flexible B > command
+set. If you use B>
+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 sequence.
-=item B<-l>|B<--lower-limit> I (default autoconfigure)
+=head1 OPTIONS
-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.
+It is expected that most options will move to the graph definition
+statements (after all, most of them do define graph elements...).
-=item B<-r>|B<--rigid>
+=over 4
-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 filename
-=item B<-b>|B<--base> I
+The name and path of the graph to generate. It is recommended to
+end this in C<.png> or C<.gif> but B does not enforce this.
-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.
+I can be 'C<->' to send the image to C. In
+that case, no other output is generated.
-=item B<-o>|B<--logarithmic>
+Z<>
-logarithmic y-axis scaling
+=item Time range
-=item B<-c>|B<--color> IB<#>I (default colors)
+B<[-s|--start EtimeE]>
+B<[-e|--end EtimeE]>
+B<[--step EsecondsE]>
-override the colors for the standard elements of the graph. The I
-must be one of the following symbolic names: B ground, B,
-B left/top border, B right/bottom border, B, B
-major grid, B, B and axis of the graph or B. This option
-can be called multiple times to set several colors.
+The start and end of what you would like to display, and which
+B the data should come from. Defaults are: 1 day ago until
+now, with the best possible resolution. B and B can
+be specified in several formats, see
+L and L.
+By default, B calculates the width of one pixel in
+the time domain and tries to get data from an B with that
+resolution. With the B option you can alter this behaviour.
+If you want B to get data at a one-hour resolution
+from the B, set B to 3600. Note: a step smaller than
+one pixel will silently be ignored.
-=item B<-g>|B<--no-legend>
+Z<>
-Suppress generation of legend; only render the graph.
+=item Labels
-=item B<-t>|B<--title> I (default no title)
+B<[-t|--title EstringE]>
+B<[-v|--vertical-label EstringE]>
-Define a title to be written into the graph
+A horizontal string at the top of the graph and/or a vertically
+placed string at the left hand side of the graph. I The string can contain formatter options that
+are used to include variables (from Bs) and newlines.
-=item B<--step> I (default automatic)
+Z<>
-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 Size
-=item BIB<=>IB<:>IB<:>I
+B<[-w|--width EpixelsE]>
+B<[-h|--heigth EpixelsE]>
-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 which contains I 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 should be represented
-by one pixel in the graph. If the resolution of the B is higher
-than the resolution of the graph, the data in the RRA will be further
-consolidated according to the consolidation function (I) chosen.
+The width and height of the B (the part of the graph with
+the actual lines and such). Defaults are 400 pixels by 100 pixels.
-=item BIB<=>I
+Z<>
-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.
+=item Limits
-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 becomes C 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.
+I
+B<[-u|--upper-limit EvalueE]>
+B<[-l|--lower-limit EvalueE]>
+B<[-r|--rigid]>
-The I in the B function takes both, constant values
-as well as I variables. The following operators can be used on these
-values:
+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 to B. Autoscaling will
+still permit those boundaries to be stretched unless the B
+option is set.
-=over
+I
+B<[--maximum-upper-limit EvalueE]>
+B<[--minimum-upper-limit EvalueE]>
+B<[--maximum-lower-limit EvalueE]>
+B<[--minimum-lower-limit EvalueE]>
-=item +, -, *, /, %
+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 and at least B
+at the top, and similarily at least B and
+at most B at the bottom. The default is to
+display at most B (so: no limit) and at least
+B (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.
-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.
+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 SIN, COS, LOG, EXP, FLOOR, CEIL
+--maximum-upper-limit 4000 --minimum-upper-limit 2000
+--maximum-lower-limit -1000 --minimum-lower-limit -3000
-pops one value from the stack, applies the selected function and pushes
-the result back onto the stack.
+To mimic the old B option, you can do:
-=item LT, LE, GT, GE, EQ
+--maximum-upper-limit 4000 --minimum-upper-limit 4000
+--maximum-lower-limit -3000 --minimum-lower-limit -3000
-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.
+B<[--alt-autoscale]>
-=item IF
+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).
-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.
+B<[--alt-autoscale-max]>
-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 EIGSTC<:>MTMC<:>MSTC<:>LTMC<:>LSTC<:>LPRC<:>LFM>E|C]>
-=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 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
+positions. You can choose from C, C, C, C,
+C, C or C. Then you define how many of these should
+pass between each line or label. This pair (I) needs to be
+specified for the base grid (I), the major grid (I