doc/rrdgraph.pod

   1 =head1 NAME
   2
   3 rrdgraph - Round Robin Database tool grapher functions
   4
   5 =head1 SYNOPSIS
   6
   7 B<rrdtool graph|graphv> I<filename>
   8 [I<L<option|rrdgraph/OPTIONS>> ...]
   9 [I<L<data definition|rrdgraph_data/DEF>> ...]
  10 [I<L<data calculation|rrdgraph_data/CDEF>> ...]
  11 [I<L<variable definition|rrdgraph_data/VDEF>> ...]
  12 [I<L<graph element|rrdgraph_graph/GRAPH>> ...]
  13 [I<L<print element|rrdgraph_graph/PRINT>> ...]
  14
  15 =head1 DESCRIPTION
  16
  17 The B<graph> function of B<RRDtool> is used to present the
  18 data from an B<RRD> to a human viewer.  Its main purpose is to
  19 create a nice graphical representation, but it can also generate
  20 a numerical report.
  21
  22 =head1 OVERVIEW
  23
  24 B<rrdtool graph> needs data to work with, so you must use one or more
  25 B<L<data definition|rrdgraph_data/DEF>> statements to collect this
  26 data.  You are not limited to one database, it's perfectly legal to
  27 collect data from two or more databases (one per statement, though).
  28
  29 If you want to display averages, maxima, percentiles, etcetera
  30 it is best to collect them now using the
  31 B<L<variable definition|rrdgraph_data/VDEF>> statement.
  32 Currently this makes no difference, but in a future version
  33 of rrdtool you may want to collect these values before consolidation.
  34
  35 The data fetched from the B<RRA> is then B<consolidated> so that
  36 there is exactly one datapoint per pixel in the graph. If you do
  37 not take care yourself, B<RRDtool> will expand the range slightly
  38 if necessary. Note, in that case the first and/or last pixel may very
  39 well become unknown!
  40
  41 Sometimes data is not exactly in the format you would like to display
  42 it. For instance, you might be collecting B<bytes> per second, but
  43 want to display B<bits> per second. This is what the B<L<data
  44 calculation|rrdgraph_data/CDEF>> command is designed for. After
  45 B<consolidating> the data, a copy is made and this copy is modified
  46 using a rather powerful B<L<RPN|rrdgraph_rpn/>> command set.
  47
  48 When you are done fetching and processing the data, it is time to
  49 graph it (or print it).  This ends the B<rrdtool graph> sequence.
  50
  51 =head1 OPTIONS
  52
  53 =over 4
  54
  55 =item B<graphv>
  56
  57 This alternate version of B<graph> takes the same arguments and performs the
  58 same function. The I<v> stands for I<verbose>, which describes the output
  59 returned. B<graphv> will return a lot of information about the graph using
  60 the same format as rrdtool info (key = value). See the bottom of the document for more information.
  61
  62
  63 =item filename
  64
  65 The name and path of the graph to generate. It is recommended to
  66 end this in C<.png>, C<.svg> or C<.eps>, but B<RRDtool> does not enforce this.
  67
  68 I<filename> can be 'C<->' to send the image to C<stdout>. In
  69 this case, no other output is generated.
  70
  71 =item Time range
  72
  73 [B<-s>|B<--start> I<time>]
  74 [B<-e>|B<--end> I<time>]
  75 [B<-S>|B<--step> I<seconds>]
  76
  77 The start and end of the time series you would like to display, and which
  78 B<RRA> the data should come from.  Defaults are: 1 day ago until
  79 now, with the best possible resolution. B<Start> and B<end> can
  80 be specified in several formats, see
  81 L<AT-STYLE TIME SPECIFICATION|rrdfetch/> and L<rrdgraph_examples>.
  82 By default, B<rrdtool graph> calculates the width of one pixel in
  83 the time domain and tries to get data from an B<RRA> with that
  84 resolution.  With the B<step> option you can alter this behaviour.
  85 If you want B<rrdtool graph> to get data at a one-hour resolution
  86 from the B<RRD>, set B<step> to 3'600. Note: a step smaller than
  87 one pixel will silently be ignored.
  88
  89 =item Labels
  90
  91 [B<-t>|B<--title> I<string>]
  92 [B<-v>|B<--vertical-label> I<string>]
  93
  94 A horizontal string at the top of the graph and/or a vertically
  95 placed string at the left hand side of the graph.
  96
  97 =item Size
  98
  99 [B<-w>|B<--width> I<pixels>]
 100 [B<-h>|B<--height> I<pixels>]
 101 [B<-j>|B<--only-graph>]
 102 [B<-D>|B<--full-size-mode>]
 103
 104 By default, the width and height of the B<canvas> (the part with
 105 the actual data and such). This defaults to 400 pixels by 100 pixels.
 106
 107 If you specify the B<--full-size-mode> option, the width and height
 108 specify the final dimensions of the output image and the canvas
 109 is automatically resized to fit.
 110
 111 If you specify the B<--only-graph> option and set the height E<lt> 32
 112 pixels you will get a tiny graph image (thumbnail) to use as an icon
 113 for use in an overview, for example. All labeling will be stripped off
 114 the graph.
 115
 116 =item Limits
 117
 118 [B<-u>|B<--upper-limit> I<value>]
 119 [B<-l>|B<--lower-limit> I<value>]
 120 [B<-r>|B<--rigid>]
 121
 122 By default the graph will be autoscaling so that it will adjust the
 123 y-axis to the range of the data. You can change this behaviour by
 124 explicitly setting the limits. The displayed y-axis will then range at
 125 least from B<lower-limit> to B<upper-limit>. Autoscaling will still
 126 permit those boundaries to be stretched unless the B<rigid> option is
 127 set.
 128
 129 [B<-A>|B<--alt-autoscale>]
 130
 131 Sometimes the default algorithm for selecting the y-axis scale is not
 132 satisfactory. Normally the scale is selected from a predefined
 133 set of ranges and this fails miserably when you need to graph something
 134 like C<260 + 0.001 * sin(x)>. This option calculates the minimum and
 135 maximum y-axis from the actual minimum and maximum data values. Our example
 136 would display slightly less than C<260-0.001> to slightly more than
 137 C<260+0.001> (this feature was contributed by Sasha Mikheev).
 138
 139 [B<-J>|B<--alt-autoscale-min>]
 140
 141 Where C<--alt-autoscale> will modify both the absolute maximum AND minimum
 142 values, this option will only affect the minimum value. The maximum
 143 value, if not defined on the command line, will be 0. This option can
 144 be useful when graphing router traffic when the WAN line uses compression,
 145 and thus the throughput may be higher than the WAN line speed.
 146
 147 [B<-M>|B<--alt-autoscale-max>]
 148
 149 Where C<--alt-autoscale> will modify both the absolute maximum AND minimum
 150 values, this option will only affect the maximum value. The minimum
 151 value, if not defined on the command line, will be 0. This option can
 152 be useful when graphing router traffic when the WAN line uses compression,
 153 and thus the throughput may be higher than the WAN line speed.
 154
 155 [B<-N>|B<--no-gridfit>]
 156
 157 In order to avoid anti-aliasing blurring effects rrdtool snaps
 158 points to device resolution pixels, this results in a crisper
 159 aperance. If this is not to your liking, you can use this switch
 160 to turn this behaviour off.
 161
 162 Gridfitting is turned off for PDF, EPS, SVG output by default.
 163
 164 =item Grid
 165
 166 =over 4
 167
 168 =item X-Axis
 169
 170 [B<-x>|B<--x-grid> I<GTM>B<:>I<GST>B<:>I<MTM>B<:>I<MST>B<:>I<LTM>B<:>I<LST>B<:>I<LPR>B<:>I<LFM>]
 171
 172 [B<-x>|B<--x-grid> B<none>]
 173
 174 The x-axis label is quite complex to configure. If you don't have
 175 very special needs it is probably best to rely on the autoconfiguration
 176 to get this right. You can specify the string C<none> to suppress the grid
 177 and labels altogether.
 178
 179 The grid is defined by specifying a certain amount of time in the I<?TM>
 180 positions. You can choose from C<SECOND>, C<MINUTE>, C<HOUR>, C<DAY>,
 181 C<WEEK>, C<MONTH> or C<YEAR>. Then you define how many of these should
 182 pass between each line or label.  This pair (I<?TM:?ST>) needs to be
 183 specified for the base grid (I<G??>), the major grid (I<M??>) and the
 184 labels (I<L??>). For the labels you also must define a precision
 185 in I<LPR> and a I<strftime> format string in I<LFM>.  I<LPR> defines
 186 where each label will be placed. If it is zero, the label will be
 187 placed right under the corresponding line (useful for hours, dates
 188 etcetera).  If you specify a number of seconds here the label is
 189 centered on this interval (useful for Monday, January etcetera).
 190
 191  --x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X
 192
 193 This places grid lines every 10 minutes, major grid lines every hour,
 194 and labels every 4 hours. The labels are placed under the major grid
 195 lines as they specify exactly that time.
 196
 197  --x-grid HOUR:8:DAY:1:DAY:1:86400:%A
 198
 199 This places grid lines every 8 hours, major grid lines and labels
 200 each day. The labels are placed exactly between two major grid lines
 201 as they specify the complete day and not just midnight.
 202
 203 =item Y-Axis
 204
 205 [B<-y>|B<--y-grid> I<grid step>B<:>I<label factor>]
 206
 207 [B<-y>|B<--y-grid> B<none>]
 208
 209 Y-axis grid lines appear at each I<grid step> interval.  Labels are
 210 placed every I<label factor> lines.  You can specify C<-y none> to
 211 suppress the grid and labels altogether.  The default for this option is
 212 to automatically select sensible values.
 213
 214 If you have set --y-grid to 'none' not only the labels get supressed, also
 215 the space reserved for the labels is removed. You can still add space
 216 manually if you use the --units-length command to explicitly reserve space.
 217
 218 [B<-Y>|B<--alt-y-grid>]
 219
 220 Place the Y grid dynamically based on the graph's Y range. The algorithm
 221 ensures that you always have a grid, that there are enough but not too many
 222 grid lines, and that the grid is metric. That is the grid lines are placed
 223 every 1, 2, 5 or 10 units. This parameter will also ensure that you get
 224 enough decimals displayed even if your graph goes from 69.998 to 70.001.
 225 (contributed by Sasha Mikheev).
 226
 227 [B<-o>|B<--logarithmic>]
 228
 229 Logarithmic y-axis scaling.
 230
 231 [B<-X>|B<--units-exponent> I<value>]
 232
 233 This sets the 10**exponent scaling of the y-axis values. Normally,
 234 values will be scaled to the appropriate units (k, M, etc.).  However,
 235 you may wish to display units always in k (Kilo, 10e3) even if the data
 236 is in the M (Mega, 10e6) range, for instance. Value should be an
 237 integer which is a multiple of 3 between -18 and 18 inclusively.  It is
 238 the exponent on the units you wish to use. For example, use 3 to
 239 display the y-axis values in k (Kilo, 10e3, thousands), use -6 to
 240 display the y-axis values in u (Micro, 10e-6, millionths).  Use a value
 241 of 0 to prevent any scaling of the y-axis values.
 242
 243 This option is very effective at confusing the heck out of the default
 244 rrdtool autoscaler and grid painter. If rrdtool detects that it is not
 245 successful in labeling the graph under the given circumstances, it will switch
 246 to the more robust B<--alt-y-grid> mode.
 247
 248 [B<-L>|B<--units-length> I<value>]
 249
 250 How many digits should rrdtool assume the y-axis labels to be? You
 251 may have to use this option to make enough space once you start
 252 fideling with the y-axis labeling.
 253
 254 [B<--units=si>]
 255
 256 With this option y-axis values on logarithmic graphs will be scaled to
 257 the appropriate units (k, M, etc.) instead of using exponential notation.
 258 Note that for linear graphs, SI notation is used by default.
 259
 260 =back
 261
 262 =item Miscellaneous
 263
 264 [B<-z>|B<--lazy>]
 265
 266 Only generate the graph if the current graph is out of date or not
 267 existent.
 268
 269 [B<-f>|B<--imginfo> I<printfstr>]
 270
 271 After the image has been created, the graph function uses printf
 272 together with this format string to create output similar to the PRINT
 273 function, only that the printf function is supplied with the parameters
 274 I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag
 275 suitable for including the graph into a web page, the command line
 276 would look like this:
 277
 278  --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
 279
 280 [B<-c>|B<--color> I<COLORTAG>#I<rrggbb>[I<aa>]]
 281
 282 Override the default colors for the standard elements of the graph. The
 283 I<COLORTAG> is one of C<BACK> background, C<CANVAS> for the background of
 284 the actual graph, C<SHADEA> for the left and top border, C<SHADEB> for the
 285 right and bottom border, C<GRID>, C<MGRID> for the major grid, C<FONT> for
 286 the color of the font, C<AXIS> for the axis of the graph, C<FRAME> for the
 287 line around the color spots and finally C<ARROW> for the arrow head pointing
 288 up and forward. Each color is composed out of three hexadecimal numbers
 289 specifying its rgb color component (00 is off, FF is maximum) of red, green
 290 and blue. Optionally you may add another hexadecimal number specifying the
 291 transparency (FF is solid). You may set this option several times to alter
 292 multiple defaults.
 293
 294 A green arrow is made by: C<--color ARROW#00FF00>
 295
 296 [B<--zoom> I<factor>]
 297
 298 Zoom the graphics by the given amount. The factor must be E<gt> 0
 299
 300 [B<-n>|B<--font> I<FONTTAG>B<:>I<size>B<:>[I<font>]]
 301
 302 This lets you customize which font to use for the various text
 303 elements on the RRD graphs. C<DEFAULT> sets the default value for all
 304 elements, C<TITLE> for the title, C<AXIS> for the axis labels, C<UNIT>
 305 for the vertical unit label, C<LEGEND> for the graph legend.
 306
 307 Use Times for the title: C<--font TITLE:13:Times>
 308
 309 If you do not give a font string you can modify just the sice of the default font:
 310 C<--font TITLE:13:>.
 311
 312 If you specify the size 0 then you can modify just the font without touching
 313 the size. This is especially usefull for altering the default font without
 314 resetting the default fontsizes: C<--font DEFAULT:0:Courier>.
 315
 316 RRDtool comes with a preset default font. You can set the environment
 317 variable C<RRD_DEFAULT_FONT> if you want to change this.
 318
 319 RRDtool uses Pango for its font handling. This means you can to use
 320 the full Pango syntax when selecting your font:
 321
 322 The font name has the form "[I<FAMILY-LIST>] [I<STYLE-OPTIONS>] [I<SIZE>]",
 323 where I<FAMILY-LIST> is a comma separated list of families optionally
 324 terminated by a comma, I<STYLE_OPTIONS> is a whitespace separated list of
 325 words where each WORD describes one of style, variant, weight, stretch, or
 326 gravity, and I<SIZE> is a decimal number (size in points) or optionally
 327 followed by the unit modifier "px" for absolute size. Any one of the options
 328 may be absent.
 329
 330 [B<-R>|B<--font-render-mode> {B<normal>,B<light>,B<mono>}]
 331
 332 There are 3 font render modes:
 333
 334 B<normal>: Full Hinting and Antialiasing (default)
 335
 336 B<light>: Slight Hinting and Antialiasing
 337
 338 B<mono>: Full Hinting and NO Antialiasing
 339
 340
 341 [B<-B>|B<--font-smoothing-threshold> I<size>]
 342
 343 (this gets ignored in 1.3 for now!)
 344
 345 This specifies the largest font size which will be rendered
 346 bitmapped, that is, without any font smoothing. By default,
 347 no text is rendered bitmapped.
 348
 349 [B<-P>|B<--pango-markup>]
 350
 351 All text in rrdtool is rendered using Pango. With the B<--pango-markup> option, all
 352 text will be processed by pango markup. This allows to embed some simple html
 353 like markup tags using
 354
 355  <span key="value">text</span>
 356
 357 Apart from the verbose syntax, there are also the following short tags available.
 358
 359  b     Bold
 360  big   Makes font relatively larger, equivalent to <span size="larger">
 361  i     Italic
 362  s     Strikethrough
 363  sub   Subscript
 364  sup   Superscript
 365  small Makes font relatively smaller, equivalent to <span size="smaller">
 366  tt    Monospace font
 367  u     Underline
 368
 369 More details on L<http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html>.
 370
 371 [B<-G>|B<--graph-render-mode> {B<normal>,B<mono>}]
 372
 373 There are 2 render modes:
 374
 375 B<normal>: Graphs are fully Antialiased (default)
 376
 377 B<mono>: No Antialiasing
 378
 379 [B<-E>|B<--slope-mode>]
 380
 381 RRDtool graphs are composed of stair case curves by default. This is in line with
 382 the way RRDtool calculates its data. Some people favor a more 'organic' look
 383 for their graphs even though it is not all that true.
 384
 385 [B<-a>|B<--imgformat> B<PNG>|B<SVG>|B<EPS>|B<PDF>]
 386
 387 Image format for the generated graph. For the vector formats you can
 388 choose among the standard Postscript fonts Courier-Bold,
 389 Courier-BoldOblique, Courier-Oblique, Courier, Helvetica-Bold,
 390 Helvetica-BoldOblique, Helvetica-Oblique, Helvetica, Symbol,
 391 Times-Bold, Times-BoldItalic, Times-Italic, Times-Roman, and ZapfDingbats.
 392
 393 [B<-i>|B<--interlaced>]
 394
 395 (this gets ignored in 1.3 for now!)
 396
 397 If images are interlaced they become visible on browsers more quickly.
 398
 399 [B<-g>|B<--no-legend>]
 400
 401 Suppress generation of the legend; only render the graph.
 402
 403 [B<-F>|B<--force-rules-legend>]
 404
 405 Force the generation of HRULE and VRULE legends even if those HRULE or
 406 VRULE will not be drawn because out of graph boundaries (mimics
 407 behaviour of pre 1.0.42 versions).
 408
 409 [B<-T>|B<--tabwidth> I<value>]
 410
 411 By default the tab-width is 40 pixels, use this option to change it.
 412
 413 [B<-b>|B<--base> I<value>]
 414
 415 If you are graphing memory (and NOT network traffic) this switch
 416 should be set to 1024 so that one Kb is 1024 byte. For traffic
 417 measurement, 1 kb/s is 1000 b/s.
 418
 419 [B<-W>|B<--watermark> I<string>]
 420
 421 Adds the given string as a watermark, horizontally centred, at the bottom
 422 of the graph.
 423
 424 =item Data and variables
 425
 426 B<DEF:>I<vname>B<=>I<rrdfile>B<:>I<ds-name>B<:>I<CF>[B<:step=>I<step>][B<:start=>I<time>][B<:end=>I<time>]
 427
 428 B<CDEF:>I<vname>B<=>I<RPN expression>
 429
 430 B<VDEF:>I<vname>B<=>I<RPN expression>
 431
 432 You need at least one B<DEF> statement to generate anything. The
 433 other statements are useful but optional.
 434 See L<rrdgraph_data> and L<rrdgraph_rpn> for the exact format.
 435
 436 =item Graph and print elements
 437
 438 You need at least one graph element to generate an image and/or
 439 at least one print statement to generate a report.
 440 See L<rrdgraph_graph> for the exact format.
 441
 442
 443 =back
 444
 445 =head2 graphv
 446
 447 Calling rrdtool with the graphv option will return information in the
 448 rrdtool info format. On the command line this means that all output will be
 449 in key=value format. When used from the perl and ruby bindings a hash
 450 pointer will be returned from the call.
 451
 452 When the filename '-' is given, the contents of the graph itself will also
 453 be returned through this interface (hash key 'image'). On the command line
 454 the output will look like this:
 455
 456  print[0] = "0.020833"
 457  print[1] = "0.0440833"
 458  graph_left = 51
 459  graph_top = 22
 460  graph_width = 400
 461  graph_height = 100
 462  image_width = 481
 463  image_height = 154
 464  value_min = 0.0000000000e+00
 465  value_max = 4.0000000000e-02
 466  image = BLOB_SIZE:8196
 467  [... 8196 bytes of image data ...]
 468
 469 There is more information returned than in the standard interface.
 470 Especially the 'graph_*' keys are new. They help applications that want to
 471 know what is where on the graph.
 472
 473 =head1 SEE ALSO
 474
 475 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
 476 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
 477 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
 478 L<rrdgraph_graph> page describes all of the graph and print functions.
 479
 480 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 481
 482 =head1 AUTHOR
 483
 484 Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 485
 486 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>
 487