doc/rrdgraph.src

   1 =include name
   2
   3 =head1 SYNOPSIS
   4
   5 B<rrdtool graph> I<filename>
   6 [E<lt>B<L<option|rrdgraph/OPTIONS>>E<gt> ...]
   7 E<lt>B<L<data definition|rrdgraph_data/DEF>>E<gt>[ ...]
   8 [E<lt>B<L<data calculation|rrdgraph_data/CDEF>>E<gt> ...]
   9 [E<lt>B<L<variable definition|rrdgraph_data/VDEF>>E<gt> ...]
  10 [E<lt>B<L<graph element|rrdgraph_graph/GRAPH>>E<gt> ...]
  11 [E<lt>B<L<print element|rrdgraph_graph/PRINT>>E<gt> ...]
  12
  13 =head1 DESCRIPTION
  14
  15 The B<graph> function of B<RRDtool> is used to present the
  16 data from an B<RRD> to a human viewer.  Its main purpose is to
  17 create a nice graphical representation but it can also generate
  18 a numerical report.
  19
  20 =head1 OVERVIEW
  21
  22 B<rrdtool graph> needs data to work with, use one or more
  23 B<L<data definition|rrdgraph_data/DEF>> statements to collect this
  24 data.  You are not limited to one database, it's perfectly legal to
  25 collect data from two or more databases (one per statement though).
  26
  27 If you want to display averages, maxima, percentiles etcetera
  28 it is best to collect them now using the
  29 B<L<variable definition|rrdgraph_data/VDEF>> statement.
  30 Currently this makes no difference but in a future version
  31 of rrdtool you may want to collect these values before consolidation.
  32
  33 The data fetched from the B<RRA> is then B<consolidated> so that
  34 there is exactly one datapoint per pixel in the graph. If you do
  35 not take care yourself, B<RRDtool> will expand the range slightly
  36 if necessary (in that case the first and/or last pixel may very
  37 well become unknown!).
  38
  39 Sometimes data is not exactly as you would like to display it. For
  40 instance, you might be collecting B<bytes> per second but want to
  41 display B<bits> per second. This is where the
  42 B<L<data calculation|rrdgraph_data/CDEF>> command is designed for.
  43 After B<consolidating> the data, a copy is made and this copy is
  44 modified using a rather flexible B<L<RPN|rrdgraph_rpn/>> command
  45 set.
  46
  47 When you are done fetching and processing the data, it is time to
  48 graph it (or print it).  This ends the B<rrdtool graph> sequence.
  49
  50 =head1 OPTIONS
  51
  52 =over 4
  53
  54 =item filename
  55
  56 The name and path of the graph to generate. It is recommended to
  57 end this in C<.png>, C<.svg> or C<.eps> but B<RRDtool> does not enforce this.
  58
  59 I<filename> can be 'C<->' to send the image to C<stdout>. In
  60 that case, no other output is generated.
  61
  62 Z<>
  63
  64 =item Time range
  65
  66 B<[-s|--start E<lt>timeE<gt>]>
  67 B<[-e|--end E<lt>timeE<gt>]>
  68 B<[-S|--step E<lt>secondsE<gt>]>
  69
  70 The start and end of what you would like to display, and which
  71 B<RRA> the data should come from.  Defaults are: 1 day ago until
  72 now, with the best possible resolution. B<Start> and B<end> can
  73 be specified in several formats, see
  74 L<AT-STYLE TIME SPECIFICATION|rrdfetch/> and L<rrdgraph_examples>.
  75 By default, B<rrdtool graph> calculates the width of one pixel in
  76 the time domain and tries to get data from an B<RRA> with that
  77 resolution.  With the B<step> option you can alter this behaviour.
  78 If you want B<rrdtool graph> to get data at a one-hour resolution
  79 from the B<RRD>, set B<step> to 3600.  Note: a step smaller than
  80 one pixel will silently be ignored.
  81
  82 Z<>
  83
  84 =item Labels
  85
  86 B<[-t|--title E<lt>stringE<gt>]>
  87 B<[-v|--vertical-label E<lt>stringE<gt>]>
  88
  89 A horizontal string at the top of the graph and/or a vertically
  90 placed string at the left hand side of the graph.
  91
  92 Z<>
  93
  94 =item Size
  95
  96 B<[-w|--width E<lt>pixelsE<gt>]>
  97 B<[-h|--height E<lt>pixelsE<gt>]>
  98 B<[-j|--only-graph]>
  99
 100 The width and height of the B<canvas> (the part of the graph with
 101 the actual lines and such). Defaults are 400 pixels by 100 pixels.
 102
 103 If you specify the B<--only-graph> option and set the height E<lt> 32
 104 pixels you will get a tiny graph image to use as an icon in a potential
 105 overview. All labeling will be stripped off the graph.
 106
 107 Z<>
 108
 109 =item Limits
 110
 111 B<[-u|--upper-limit E<lt>valueE<gt>]>
 112 B<[-l|--lower-limit E<lt>valueE<gt>]>
 113 B<[-r|--rigid]>
 114
 115 By default the graph will be autoscaling so that it displays the
 116 portion of the y-axis that is actually used. You can change this
 117 behaviour by setting the limits.  The displayed y-axis will show
 118 at least from B<lower-limit> to B<upper-limit>.  Autoscaling will
 119 still permit those boundaries to be stretched unless the B<rigid>
 120 option is set.
 121
 122 B<[-A|--alt-autoscale]>
 123
 124 Sometimes the default algorithm for selecting the y-axis scale is not
 125 performing very well.  Normally the scale is selected from a predefined
 126 set of ranges and this fails miserably when you need to graph something
 127 like C<260 + 0.001 * sin(x)>. This option calculates the minimum and
 128 maximum y-axis from the actual minimum and maximum values. Our example
 129 would display slightly less than C<260-0.001> to slightly more than
 130 C<260+0.001> (Contributed by Sasha Mikheev).
 131
 132 B<[-M|--alt-autoscale-max]>
 133
 134 Where C<--alt-autoscale> will modify both the absolute maximum AND minimum
 135 values, this option will only affect the maximum value. The minimum
 136 value, if not defined on the command line, will be 0. This option can
 137 be useful when graphing router traffic when the WAN line uses compression,
 138 and thus the throughput may be higher than the WAN line speed.
 139
 140 B<[-N|--no-gridfit]>
 141
 142 To avoid anti-aliasing effects gridlines are placed on
 143 integer pixel values. This is by default done by extending
 144 the scale so gridlines happens to be spaced using an
 145 integer number of pixels, and starts on integer pixel value.
 146 This might extend the scale too much for some logarithmic scales
 147 and for linear scales where --alt-autoscale is needed.
 148 Using --no-gridfit disables modification of the scale,
 149 and just truncates y-coordinates to integer values for bitmap
 150 formats.
 151
 152 Z<>
 153
 154 =item Grid
 155
 156 =over 4
 157
 158 =item X-Axis
 159
 160 B<[-x|--x-grid E<lt>I<GTMC<:>GSTC<:>MTMC<:>MSTC<:>LTMC<:>LSTC<:>LPRC<:>LFM>E<gt>]>
 161
 162 B<[-x|--x-grid C<none>]>
 163
 164 The x-axis label is quite complex to configure, if you don't have
 165 very special needs it is probably best to rely on the autoconfiguration
 166 to get this right.  You can specify the string C<none> to skip the grid
 167 and labels altogether.
 168
 169 The grid is defined by specifying a certain amount of time in the I<?TM>
 170 positions. You can choose from C<SECOND>, C<MINUTE>, C<HOUR>, C<DAY>,
 171 C<WEEK>, C<MONTH> or C<YEAR>. Then you define how many of these should
 172 pass between each line or label.  This pair (I<?TM:?ST>) needs to be
 173 specified for the base grid (I<G??>), the major grid (I<M??>) and the
 174 labels (I<L??>). For the labels you also need to define a precision
 175 in I<LPR> and a I<strftime> format string in I<LFM>.  I<LPR> defines
 176 where each label will be placed. If it is zero, the label will be
 177 placed right under the corresponding line (useful for hours, dates
 178 etcetera).  If you specify a number of seconds here the label is
 179 centered in this interval (useful for Monday, January etcetera).
 180
 181 Example: C<--x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X>
 182
 183 This places grid lines every 10 minutes, major grid lines every hour
 184 and labels every 4 hours. The labels are placed under the major grid
 185 lines as they specify exactly that time.
 186
 187 Example: C<--x-grid HOUR:8:DAY:1:DAY:1:0:%A>
 188
 189 This places grid lines every 8 hours, major grid lines and labels
 190 each day. The labels are placed exactly between two major grid lines
 191 as they specify the complete day and not just midnight.
 192
 193 Z<>
 194
 195 =item Y-Axis
 196
 197 B<[-y|--y-grid I<E<lt>grid stepE<gt>:E<lt>label factorE<gt>>]>
 198
 199 B<[-y|--y-grid C<none>]>
 200
 201 Y-axis grid lines appear at each I<grid step> interval.  Labels are
 202 placed every I<label factor> lines.  You can specify C<-y none> to
 203 skip the grid and labels altogether.  The default for this option is
 204 to automatically select sensible values.
 205
 206 B<[-Y|--alt-y-grid]>
 207
 208 Place Y grid dynamically based on graph Y range. Algorithm ensures
 209 that you always have grid, that there are enough but not too many
 210 grid lines and the grid is metric. That is grid lines are placed
 211 every 1, 2, 5 or 10 units.  (contributed by Sasha Mikheev)
 212
 213 B<[-o|--logarithmic]>
 214
 215 Logarithmic y-axis scaling.
 216
 217 B<[-X|--units-exponent E<lt>valueE<gt>]>
 218
 219 This sets the 10**exponent scaling of the y-axis values.  Normally
 220 values will be scaled to the appropriate units (k, M, etc.).  However
 221 you may wish to display units always in k (Kilo, 10e3) even if the data
 222 is in the M (Mega, 10e6) range for instance.  Value should be an
 223 integer which is a multiple of 3 between -18 and 18 inclusive.  It is
 224 the exponent on the units you which to use.  For example, use 3 to
 225 display the y-axis values in k (Kilo, 10e3, thousands), use -6 to
 226 display the y-axis values in u (Micro, 10e-6, millionths).  Use a value
 227 of 0 to prevent any scaling of the y-axis values.
 228
 229 This option is very effective at confusing the heck out of the default
 230 rrdtool autoscaler and grid painter. If rrdtool detects that it is not
 231 successful in labeling the graph under the given circumstances, it will switch
 232 to the more robust B<--alt-y-grid> mode.
 233
 234 B<[-L|--units-length E<lt>valueE<gt>]>
 235
 236 How many digits should rrdtool assume the y-axis labels to be ? You may have to use this option
 237 to make enough space once you start fideling with the y-axis labeling.
 238
 239 Z<>
 240
 241 =back
 242
 243 Z<>
 244
 245 =item Miscellaneous
 246
 247 B<[-z|--lazy]>
 248
 249 Only generate the graph, if the current graph is out of date or not
 250 existent.
 251
 252 B<[-f|--imginfo E<lt>printfstrE<gt>]>
 253
 254 After the image has been created, the graph function uses printf
 255 together with this format string to create output similar to the PRINT
 256 function, only that the printf is supplied with the parameters
 257 I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag
 258 suitable for including the graph into a web page, the command line
 259 would look like this:
 260
 261     --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
 262
 263 B<[-c|--color I<COLORTAG>#I<rrggbb>[I<aa>]]>
 264
 265 Override the default colors for the standard elements of the graph. The
 266 I<COLORTAG> is one of C<BACK> background, C<CANVAS> for the background of
 267 the actual graph, C<SHADEA> for the left and top border, C<SHADEB> for the
 268 right and bottom border, C<GRID>, C<MGRID> for the major grid, C<FONT> for
 269 the color of the font, C<AXIS> for the axis of the graph and finaly C<ARROW>
 270 for the arrow head pointing to the future. Each color is composed out of
 271 three hexadecimal numbers specifying its color component (00 is off, FF is
 272 maximum) of red, green and blue. Optionally you may add another hexadecimal
 273 number specifying the transparency (FF is solid). You may set this option
 274 several times to alter multiple defaults.
 275
 276 A green arrow is made by: C<--color ARROW:00FF00>
 277
 278 B<[--zoom I<factor>]>
 279
 280 Zoom the graphics by the given amount ... The factor must be E<gt> 0
 281
 282 B<[-n|--font I<FONTTAG>B<:>I<size>B<:>I<font>]>
 283
 284 Lets you customize which font to use for the various text elements on the
 285 RRD graphs. C<DEFAULT> sets the default value for all elements C<TITLE>,
 286 C<AXIS> for the axis labels, C<UNIT> for the vertical unit label, C<LEGEND>
 287 for the graph legend.
 288
 289 Use Times for the title: C<--font TITLE:13:/usr/lib/fonts/times.ttf>
 290
 291 RRDtool comes with a preset default font. You can set the environment
 292 variable C<RRD_DEFAULT_FONT> if you want to change this.
 293
 294 B<[-a|--imgformat C<PNG>|C<SVG>|C<EPS>|C<PDF>]>
 295
 296 Image format for the generated graph.
 297
 298 B<[-i|--interlaced]>
 299
 300 If images are interlaced they become visible on browsers more quickly.
 301
 302 B<[-g|--no-legend]>
 303
 304 Suppress generation of legend; only render the graph.
 305
 306 B<[-F|--force-rules-legend]>
 307
 308 Force the generation of HRULE and VRULE legend even if those HRULE or VRULE will not be drawn because out of graph boundaries (mimics behaviour of pre 1.0.42 versions).
 309
 310 B<[-T|--tabwidth E<lt>valueE<gt>]>
 311
 312 By default the tab-width is 40 pixels, use this option to change it.
 313
 314 B<[-b|--base E<lt>valueE<gt>]>
 315
 316 If you are graphing memory (and NOT network traffic) this switch
 317 should be set to 1024 so that one Kb is 1024 byte. For traffic
 318 measurement, 1 kb/s is 1000 b/s.
 319
 320 Z<>
 321
 322 =item Data and variables
 323
 324 B<DEF:>I<E<lt>vnameE<gt>>=I<E<lt>rrdfileE<gt>>:I<E<lt>ds-nameE<gt>>:I<E<lt>CFE<gt>>[:step=I<E<lt>stepE<gt>>][:start=I<E<lt>timeE<gt>>][:end=I<E<lt>timeE<gt>>]
 325
 326 B<CDEF:>I<E<lt>vnameE<gt>>=I<E<lt>RPN expressionE<gt>>
 327
 328 B<VDEF:>I<E<lt>vnameE<gt>>=I<E<lt>RPN expressionE<gt>>
 329
 330 You need at least one B<DEF> statement to generate anything. The
 331 other statements are useful but optional.
 332 See L<rrdgraph_data> and L<rrdgraph_rpn> for exact format.
 333
 334 Z<>
 335
 336 =item Graph and print elements
 337
 338 You need at least one graph element to generate an image and/or
 339 at least one print statement to generate a report.
 340 See L<rrdgraph_graph> for exact format.
 341
 342 =back
 343
 344 =include see_also