X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=doc%2Frrdgraph.pod;h=71a1e1dde1236d1512d7a7533aa42e69c9d50f08;hb=d874c8f117a7473562da5a6cf3873882c8c4dc2e;hp=8e8038e98c1b56e1253d73907fd3a8b629fc1678;hpb=7c016dfa001ae254bf4e18126f814ee8f0abd821;p=rrdtool.git
diff --git a/doc/rrdgraph.pod b/doc/rrdgraph.pod
index 8e8038e..71a1e1d 100644
--- a/doc/rrdgraph.pod
+++ b/doc/rrdgraph.pod
@@ -1,660 +1,564 @@
=head1 NAME
-rrdtool graph - Create a graph based on data from one or several RRD
-
-=for html
+rrdgraph - Round Robin Database tool graphing functions
=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]]]>
+B I
+[I> ...]
+[I> ...]
+[I> ...]
+[I> ...]
+[I> ...]
+[I> ...]
=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.
+The B function of B is used to present 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.
+
+=head1 OVERVIEW
+
+B needs data to work with, so you must 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).
+
+If you want to display averages, maxima, percentiles, etcetera
+it is best to collect them now using the
+B> statement.
+Currently this makes no difference, but in a future version
+of RRDtool you may want to collect these values before consolidation.
-=over
+The data fetched from the B is then B so that
+there is exactly one data point per pixel in the graph. If you do
+not take care yourself, B will expand the range slightly
+if necessary. Note, in that case the first and/or last pixel may very
+well become unknown!
-=item I
+Sometimes data is not exactly in the format you would like to display
+it. For instance, you might be collecting B per second, but
+want to display B per second. This is what the B> command is designed for. After
+B the data, a copy is made and this copy is modified
+using a rather powerful B> command set.
-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.
+When you are done fetching and processing the data, it is time to
+graph it (or print it). This ends the B sequence.
-PNG output is recommended, since it takes up to 40% less disk space
-and 20-30% less time to generate than a GIF file.
+Use B instead of B to get detailed information about the
+graph geometry and data once it is drawn. See the bottom of the document for
+more information.
-If no graph functions are called, the graph will not be created.
+=head1 OPTIONS
-=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)
+=head2 I
-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.
+The name and path of the graph to generate. It is recommended to
+end this in C<.png>, C<.svg> or C<.eps>, but B does not enforce this.
-=item B<-x>|B<--x-grid> I (default autoconfigure)
+I can be 'C<->' to send the image to C. In
+this case, no other output is generated.
-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.
+=head2 Time range
-If you want no x-grid at all, use the magic setting B.
+[B<-s>|B<--start> I]
+[B<-e>|B<--end> I]
+[B<-S>|B<--step> I]
-The x-axis label and grid can be configured, using the following format:
+The start and end of the time series 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 behavior.
+If you want B to get data at a one-hour resolution
+from the B, set B to 3'600. Note: a step smaller than
+one pixel will silently be ignored.
-IB<:>IB<:>IB<:>IB<:>I:IB<:>IB<:>I
+=head2 Labels
-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).
+[B<-t>|B<--title> I]
+[B<-v>|B<--vertical-label> I]
-The I elements must be one of the following keywords: B,
-B, B, B, B, B or B.
+A horizontal string at the top of the graph and/or a vertically
+placed string at the left hand side of the graph.
-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
+=head2 Size
-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.
+[B<-w>|B<--width> I]
+[B<-h>|B<--height> I]
+[B<-j>|B<--only-graph>]
+[B<-D>|B<--full-size-mode>]
-=item B<-y>|B<--y-grid> I:I (default autoconfigure)
+By default, the width and height of the B (the part with
+the actual data and such). This defaults to 400 pixels by 100 pixels.
-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 specify the B<--full-size-mode> option, the width and height
+specify the final dimensions of the output image and the canvas
+is automatically resized to fit.
-If you want no y-grid at all set specify the magic word B.
+If you specify the B<--only-graph> option and set the height E 32
+pixels you will get a tiny graph image (thumbnail) to use as an icon
+for use in an overview, for example. All labeling will be stripped off
+the graph.
-=item B<--alt-y-grid>
+=head2 Limits
-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<-u>|B<--upper-limit> I]
+[B<-l>|B<--lower-limit> I]
+[B<-r>|B<--rigid>]
+By default the graph will be autoscaling so that it will adjust the
+y-axis to the range of the data. You can change this behavior by
+explicitly setting the limits. The displayed y-axis will then range at
+least from B to B. Autoscaling will still
+permit those boundaries to be stretched unless the B option is
+set.
-=item B<--alt-autoscale>
+[B<-A>|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)
+Sometimes the default algorithm for selecting the y-axis scale is not
+satisfactory. 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 data values. Our example
+would display slightly less than C<260-0.001> to slightly more than
+C<260+0.001> (this feature was contributed by Sasha Mikheev).
+
+[B<-J>|B<--alt-autoscale-min>]
+
+Where C<--alt-autoscale> will modify both the absolute maximum AND minimum
+values, this option will only affect the minimum value. The maximum
+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<--alt-autoscale-max>
+[B<-M>|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
+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 B<--units-exponent> I (default autoconfigure)
+[B<-N>|B<--no-gridfit>]
+
+In order to avoid anti-aliasing blurring effects RRDtool snaps
+points to device resolution pixels, this results in a crisper
+appearance. If this is not to your liking, you can use this switch
+to turn this behavior off.
+
+Grid-fitting is turned off for PDF, EPS, SVG output by default.
+
+=head2 X-Axis
+
+[B<-x>|B<--x-grid> IB<:>IB<:>IB<:>IB<:>IB<:>IB<:>IB<:>I]
+
+[B<-x>|B<--x-grid> B]
+
+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 auto configuration
+to get this right. You can specify the string C to suppress the grid
+and labels altogether.
+
+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) and the
+labels (I). For the labels you also must define a precision
+in I and a I format string in I. I 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 on this interval (useful for Monday, January etcetera).
+
+ --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.
+
+ --x-grid HOUR:8:DAY:1:DAY:1:86400:%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.
+
+[B<--week-fmt> I]
+
+By default rrdtool uses "Week %V" to render the week number. With this option
+you can define your own format, without completely overriding the xaxis format.
+
+=head2 Y-Axis
+
+[B<-y>|B<--y-grid> IB<:>I]
+
+[B<-y>|B<--y-grid> B]
+
+Y-axis grid lines appear at each I interval. Labels are
+placed every I lines. You can specify C<-y none> to
+suppress the grid and labels altogether. The default for this option is
+to automatically select sensible values.
+
+If you have set --y-grid to 'none' not only the labels get suppressed, also
+the space reserved for the labels is removed. You can still add space
+manually if you use the --units-length command to explicitly reserve space.
+
+[B<-Y>|B<--alt-y-grid>]
-This sets the 10**exponent scaling of the y-axis values. Normally
-values will be scaled to the appropriate units (k, M, etc.). However
+Place the Y grid dynamically based on the graph's Y range. The algorithm
+ensures that you always have a grid, that there are enough but not too many
+grid lines, and that the grid is metric. That is the grid lines are placed
+every 1, 2, 5 or 10 units. This parameter will also ensure that you get
+enough decimals displayed even if your graph goes from 69.998 to 70.001.
+(contributed by Sasha Mikheev).
+
+[B<-o>|B<--logarithmic>]
+
+Logarithmic y-axis scaling.
+
+[B<-X>|B<--units-exponent> I]
+
+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
+is in the M (Mega, 10e6) range, for instance. Value should be an
+integer which is a multiple of 3 between -18 and 18 inclusively. It is
+the exponent on the units you wish 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
+This option is very effective at confusing the heck out of the default
+RRDtool autoscaling function and grid painter. If RRDtool detects that it is not
+successful in labeling the graph under the given circumstances, it will switch
+to the more robust B<--alt-y-grid> mode.
-vertical label on the left side of the graph. This is normally used to
-specify the units used.
+[B<-L>|B<--units-length> I]
-=item B<-w>|B<--width> I (default 400 pixel)
+How many digits should RRDtool assume the y-axis labels to be? You
+may have to use this option to make enough space once you start
+fiddling with the y-axis labeling.
-Width of the drawing area within the graph. This affects the size of the
-gif.
+[B<--units=si>]
-=item B<-h>|B<--height> I (default 100 pixel)
+With this option y-axis values on logarithmic graphs will be scaled to
+the appropriate units (k, M, etc.) instead of using exponential notation.
+Note that for linear graphs, SI notation is used by default.
-Width of the drawing area within the graph. This affects the size of the
-gif.
+=head2 Right Y Axis
-=item B<-i>|B<--interlaced> (default: false)
+[B<--right-axis> IB<:>I]
+[B<--right-axis-label> I]
-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
+A second axis will be drawn to the right of the graph. It is tied to the
+left axis via the scale and shift parameters. You can also define a label
+for the right axis.
-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:
+[B<--right-axis-format> I]
- --imginfo ' '
+By default the format of the axis labels gets determined automatically. If
+you want to do this your self, use this option with the same %lf arguments
+you know from the PRINT and GPRINT commands.
-=item B<-a>|B<--imgformat> B|B (default: GIF)
+=head2 Legend
-Allows you to produce PNG output from rrdtool.
+[B<-g>|B<--no-legend>]
-=item B<-z>|B<--lazy> (default: false)
+Suppress generation of the legend; only render the graph.
-Only generate the graph, if the current gif is out of date or not
-existent.
+[B<-F>|B<--force-rules-legend>]
-=item B<-u>|B<--upper-limit> I (default autoconfigure)
+Force the generation of HRULE and VRULE legends even if those HRULE or
+VRULE will not be drawn because out of graph boundaries (mimics
+behavior of pre 1.0.42 versions).
-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.
+[B<--legend-position>=(north|south|west|east)]
-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.
+Place the legend at the given side of the graph. The default is south.
+In west or east position it is necessary to add line breaks manually.
-=item B<-l>|B<--lower-limit> I (default autoconfigure)
+[B<--legend-direction>=(topdown|bottomup)]
-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.
+Place the legend items in the given vertical order. The default is topdown.
+Using bottomup the legend items appear in the same vertical order as a
+stack of lines or areas.
-=item B<-r>|B<--rigid>
+=head2 Miscellaneous
-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
+[B<-z>|B<--lazy>]
-=item B<-b>|B<--base> I
+Only generate the graph if the current graph is out of date or not existent.
+Note, that all the calculations will happen regardless so that the output of
+PRINT and graphv will be complete regardless. Note that the behavior of
+lazy in this regard has seen several changes over time. The only thing you
+can really rely on before RRDtool 1.3.7 is that lazy will not generate the
+graph when it is already there and up to date, and also that it will output
+the size of the graph.
-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.
+[B<--daemon> I]
-=item B<-o>|B<--logarithmic>
+Address of the L daemon. If specified, a C command is sent
+to the server before reading the RRD files. This allows the graph to contain
+fresh data even if the daemon is configured to cache values for a long time.
+For a list of accepted formats, see the B<-l> option in the L manual.
-logarithmic y-axis scaling
+ rrdtool graph [...] --daemon unix:/var/run/rrdcached.sock [...]
-=item B<-c>|B<--color> IB<#>I (default colors)
+[B<-f>|B<--imginfo> I]
-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.
+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 function 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:
-=item B<-g>|B<--no-legend>
+ --imginfo ' '
-Suppress generation of legend; only render the graph.
+[B<-c>|B<--color> I#I[I]]
-=item B<-t>|B<--title> I (default no title)
+Override the default colors for the standard elements of the graph. The
+I is one of C background, C for the background of
+the actual graph, C for the left and top border, C for the
+right and bottom border, C, C for the major grid, C for
+the color of the font, C for the axis of the graph, C for the
+line around the color spots, and finally C for the arrow head pointing
+up and forward. Each color is composed out of three hexadecimal numbers
+specifying its rgb color component (00 is off, FF is maximum) of red, green
+and blue. Optionally you may add another hexadecimal number specifying the
+transparency (FF is solid). You may set this option several times to alter
+multiple defaults.
-Define a title to be written into the graph
+A green arrow is made by: C<--color ARROW#00FF00>
-=item B<--step> I (default automatic)
+[B<--grid-dash> IB<:>I]
-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.
+by default the grid is drawn in a 1 on, 1 off pattern. With this option you can set this yourself
-=item BIB<=>IB<:>IB<:>I
+ --grid-dash 1:3 for a dot grid
+
+ --grid-dash 1:0 for uninterrupted grid lines
-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.
+[B<--border> I]]
-=item BI