doc/rrdgraph.pod

   1 =head1 NAME
   2
   3 rrdgraph - Round Robin Database tool grapher functions
   4
   5 =head1 SYNOPSIS
   6
   7 B<rrdtool graph> 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 filename
  56
  57 The name and path of the graph to generate. It is recommended to
  58 end this in C<.png>, C<.svg> or C<.eps>, but B<RRDtool> does not enforce this.
  59
  60 I<filename> can be 'C<->' to send the image to C<stdout>. In
  61 this case, no other output is generated.
  62
  63 =item Time range
  64
  65 [B<-s>|B<--start> I<time>]
  66 [B<-e>|B<--end> I<time>]
  67 [B<-S>|B<--step> I<seconds>]
  68
  69 The start and end of the time series you would like to display, and which
  70 B<RRA> the data should come from.  Defaults are: 1 day ago until
  71 now, with the best possible resolution. B<Start> and B<end> can
  72 be specified in several formats, see
  73 L<AT-STYLE TIME SPECIFICATION|rrdfetch/> and L<rrdgraph_examples>.
  74 By default, B<rrdtool graph> calculates the width of one pixel in
  75 the time domain and tries to get data from an B<RRA> with that
  76 resolution.  With the B<step> option you can alter this behaviour.
  77 If you want B<rrdtool graph> to get data at a one-hour resolution
  78 from the B<RRD>, set B<step> to 3'600. Note: a step smaller than
  79 one pixel will silently be ignored.
  80
  81 =item Labels
  82
  83 [B<-t>|B<--title> I<string>]
  84 [B<-v>|B<--vertical-label> I<string>]
  85
  86 A horizontal string at the top of the graph and/or a vertically
  87 placed string at the left hand side of the graph.
  88
  89 =item Size
  90
  91 [B<-w>|B<--width> I<pixels>]
  92 [B<-h>|B<--height> I<pixels>]
  93 [B<-j>|B<--only-graph>]
  94 [B<-D>|B<--full-size-mode>]
  95
  96 By default, the width and height of the B<canvas> (the part with
  97 the actual data and such). This defaults to 400 pixels by 100 pixels.
  98
  99 If you specify the B<--full-size-mode> option, the width and height
 100 specify the final dimensions of the output image and the canvas
 101 is automatically resized to fit.
 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 (thumbnail) to use as an icon
 105 for use in an overview, for example. All labeling will be stripped off
 106 the graph.
 107
 108 =item Limits
 109
 110 [B<-u>|B<--upper-limit> I<value>]
 111 [B<-l>|B<--lower-limit> I<value>]
 112 [B<-r>|B<--rigid>]
 113
 114 By default the graph will be autoscaling so that it will adjust the
 115 y-axis to the range of the data. You can change this behaviour by
 116 explicitly setting the limits. The displayed y-axis will then range at
 117 least from B<lower-limit> to B<upper-limit>. Autoscaling will still
 118 permit those boundaries to be stretched unless the B<rigid> option is
 119 set.
 120
 121 [B<-A>|B<--alt-autoscale>]
 122
 123 Sometimes the default algorithm for selecting the y-axis scale is not
 124 satisfactory. Normally the scale is selected from a predefined
 125 set of ranges and this fails miserably when you need to graph something
 126 like C<260 + 0.001 * sin(x)>. This option calculates the minimum and
 127 maximum y-axis from the actual minimum and maximum data values. Our example
 128 would display slightly less than C<260-0.001> to slightly more than
 129 C<260+0.001> (this feature was contributed by Sasha Mikheev).
 130
 131 [B<-J>|B<--alt-autoscale-min>]
 132
 133 Where C<--alt-autoscale> will modify both the absolute maximum AND minimum
 134 values, this option will only affect the minimum value. The maximum
 135 value, if not defined on the command line, will be 0. This option can
 136 be useful when graphing router traffic when the WAN line uses compression,
 137 and thus the throughput may be higher than the WAN line speed.
 138
 139 [B<-M>|B<--alt-autoscale-max>]
 140
 141 Where C<--alt-autoscale> will modify both the absolute maximum AND minimum
 142 values, this option will only affect the maximum value. The minimum
 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<-N>|B<--no-gridfit>]
 148
 149 In order to avoid anti-aliasing blurring effects rrdtool snaps
 150 points to device resolution pixels, this results in a crisper
 151 aperance. If this is not to your liking, you can use this switch
 152 to turn this behaviour off.
 153
 154 =item Grid
 155
 156 =over 4
 157
 158 =item X-Axis
 159
 160 [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>]
 161
 162 [B<-x>|B<--x-grid> B<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 suppress 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 must 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 on this interval (useful for Monday, January etcetera).
 180
 181  --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  --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 =item Y-Axis
 194
 195 [B<-y>|B<--y-grid> I<grid step>B<:>I<label factor>]
 196
 197 [B<-y>|B<--y-grid> B<none>]
 198
 199 Y-axis grid lines appear at each I<grid step> interval.  Labels are
 200 placed every I<label factor> lines.  You can specify C<-y none> to
 201 suppress the grid and labels altogether.  The default for this option is
 202 to automatically select sensible values.
 203
 204 If you have set --y-grid to 'none' not only the labels get supressed, also
 205 the space reserved for the labels is removed. You can still add space
 206 manually if you use the --units-length command to explicitly reserve space.
 207
 208 [B<-Y>|B<--alt-y-grid>]
 209
 210 Place the Y grid dynamically based on the graph's Y range. The algorithm
 211 ensures that you always have a grid, that there are enough but not too many
 212 grid lines, and that the grid is metric. That is the grid lines are placed
 213 every 1, 2, 5 or 10 units. This parameter will also ensure that you get
 214 enough decimals displayed even if your graph goes from 69.998 to 70.001.
 215 (contributed by Sasha Mikheev).
 216
 217 [B<-o>|B<--logarithmic>]
 218
 219 Logarithmic y-axis scaling.
 220
 221 [B<-X>|B<--units-exponent> I<value>]
 222
 223 This sets the 10**exponent scaling of the y-axis values. Normally,
 224 values will be scaled to the appropriate units (k, M, etc.).  However,
 225 you may wish to display units always in k (Kilo, 10e3) even if the data
 226 is in the M (Mega, 10e6) range, for instance. Value should be an
 227 integer which is a multiple of 3 between -18 and 18 inclusively.  It is
 228 the exponent on the units you wish to use. For example, use 3 to
 229 display the y-axis values in k (Kilo, 10e3, thousands), use -6 to
 230 display the y-axis values in u (Micro, 10e-6, millionths).  Use a value
 231 of 0 to prevent any scaling of the y-axis values.
 232
 233 This option is very effective at confusing the heck out of the default
 234 rrdtool autoscaler and grid painter. If rrdtool detects that it is not
 235 successful in labeling the graph under the given circumstances, it will switch
 236 to the more robust B<--alt-y-grid> mode.
 237
 238 [B<-L>|B<--units-length> I<value>]
 239
 240 How many digits should rrdtool assume the y-axis labels to be? You
 241 may have to use this option to make enough space once you start
 242 fideling with the y-axis labeling.
 243
 244 [B<--units=si>]
 245
 246 With this option y-axis values on logarithmic graphs will be scaled to
 247 the appropriate units (k, M, etc.) instead of using exponential notation.
 248 Note that for linear graphs, SI notation is used by default.
 249
 250 =back
 251
 252 =item Miscellaneous
 253
 254 [B<-z>|B<--lazy>]
 255
 256 Only generate the graph if the current graph is out of date or not
 257 existent.
 258
 259 [B<-f>|B<--imginfo> I<printfstr>]
 260
 261 After the image has been created, the graph function uses printf
 262 together with this format string to create output similar to the PRINT
 263 function, only that the printf function is supplied with the parameters
 264 I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag
 265 suitable for including the graph into a web page, the command line
 266 would look like this:
 267
 268  --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
 269
 270 [B<-c>|B<--color> I<COLORTAG>#I<rrggbb>[I<aa>]]
 271
 272 Override the default colors for the standard elements of the graph. The
 273 I<COLORTAG> is one of C<BACK> background, C<CANVAS> for the background of
 274 the actual graph, C<SHADEA> for the left and top border, C<SHADEB> for the
 275 right and bottom border, C<GRID>, C<MGRID> for the major grid, C<FONT> for
 276 the color of the font, C<AXIS> for the axis of the graph, C<FRAME> for the
 277 line around the color spots and finally C<ARROW> for the arrow head pointing
 278 up and forward. Each color is composed out of three hexadecimal numbers
 279 specifying its rgb color component (00 is off, FF is maximum) of red, green
 280 and blue. Optionally you may add another hexadecimal number specifying the
 281 transparency (FF is solid). You may set this option several times to alter
 282 multiple defaults.
 283
 284 A green arrow is made by: C<--color ARROW#00FF00>
 285
 286 [B<--zoom> I<factor>]
 287
 288 Zoom the graphics by the given amount. The factor must be E<gt> 0
 289
 290 [B<-n>|B<--font> I<FONTTAG>B<:>I<size>B<:>[I<font>]]
 291
 292 This lets you customize which font to use for the various text
 293 elements on the RRD graphs. C<DEFAULT> sets the default value for all
 294 elements, C<TITLE> for the title, C<AXIS> for the axis labels, C<UNIT>
 295 for the vertical unit label, C<LEGEND> for the graph legend.
 296
 297 Use Times for the title: C<--font TITLE:13:Times>
 298
 299 If you do not give a font string you can modify just the sice of the default font:
 300 C<--font TITLE:13:>.
 301
 302 If you specify the size 0 then you can modify just the font without touching
 303 the size. This is especially usefull for altering the default font without
 304 resetting the default fontsizes: C<--font DEFAULT:0:Courier>.
 305
 306 RRDtool comes with a preset default font. You can set the environment
 307 variable C<RRD_DEFAULT_FONT> if you want to change this.
 308
 309 RRDtool uses Pango for its font handling. This means you can to use
 310 the full Pango syntax when selecting your font:
 311
 312 The font name has the form "[I<FAMILY-LIST>] [I<STYLE-OPTIONS>] [I<SIZE>]",
 313 where I<FAMILY-LIST> is a comma separated list of families optionally
 314 terminated by a comma, I<STYLE_OPTIONS> is a whitespace separated list of
 315 words where each WORD describes one of style, variant, weight, stretch, or
 316 gravity, and I<SIZE> is a decimal number (size in points) or optionally
 317 followed by the unit modifier "px" for absolute size. Any one of the options
 318 may be absent.
 319
 320 [B<-R>|B<--font-render-mode> {B<normal>,B<light>,B<mono>}]
 321
 322 There are 3 font render modes:
 323
 324 B<normal>: Full Hinting and Antialiasing (default)
 325
 326 B<light>: Slight Hinting and Antialiasing
 327
 328 B<mono>: Full Hinting and NO Antialiasing
 329
 330
 331 [B<-B>|B<--font-smoothing-threshold> I<size>]
 332
 333 (this gets ignored in 1.3 for now!)
 334
 335 This specifies the largest font size which will be rendered
 336 bitmapped, that is, without any font smoothing. By default,
 337 no text is rendered bitmapped.
 338
 339 [B<-G>|B<--graph-render-mode> {B<normal>,B<mono>}]
 340
 341 There are 2 render modes:
 342
 343 B<normal>: Graphs are fully Antialiased (default)
 344
 345 B<mono>: No Antialiasing
 346
 347 [B<-E>|B<--slope-mode>]
 348
 349 RRDtool graphs are composed of stair case curves by default. This is in line with
 350 the way RRDtool calculates its data. Some people favor a more 'organic' look
 351 for their graphs even though it is not all that true.
 352
 353 [B<-a>|B<--imgformat> B<PNG>|B<SVG>|B<EPS>|B<PDF>]
 354
 355 Image format for the generated graph. For the vector formats you can
 356 choose among the standard Postscript fonts Courier-Bold,
 357 Courier-BoldOblique, Courier-Oblique, Courier, Helvetica-Bold,
 358 Helvetica-BoldOblique, Helvetica-Oblique, Helvetica, Symbol,
 359 Times-Bold, Times-BoldItalic, Times-Italic, Times-Roman, and ZapfDingbats.
 360
 361 [B<-i>|B<--interlaced>]
 362
 363 (this gets ignored in 1.3 for now!)
 364
 365 If images are interlaced they become visible on browsers more quickly.
 366
 367 [B<-g>|B<--no-legend>]
 368
 369 Suppress generation of the legend; only render the graph.
 370
 371 [B<-F>|B<--force-rules-legend>]
 372
 373 Force the generation of HRULE and VRULE legends even if those HRULE or
 374 VRULE will not be drawn because out of graph boundaries (mimics
 375 behaviour of pre 1.0.42 versions).
 376
 377 [B<-T>|B<--tabwidth> I<value>]
 378
 379 By default the tab-width is 40 pixels, use this option to change it.
 380
 381 [B<-b>|B<--base> I<value>]
 382
 383 If you are graphing memory (and NOT network traffic) this switch
 384 should be set to 1024 so that one Kb is 1024 byte. For traffic
 385 measurement, 1 kb/s is 1000 b/s.
 386
 387 [B<-W>|B<--watermark> I<string>]
 388
 389 Adds the given string as a watermark, horizontally centred, at the bottom
 390 of the graph.
 391
 392 =item Data and variables
 393
 394 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>]
 395
 396 B<CDEF:>I<vname>B<=>I<RPN expression>
 397
 398 B<VDEF:>I<vname>B<=>I<RPN expression>
 399
 400 You need at least one B<DEF> statement to generate anything. The
 401 other statements are useful but optional.
 402 See L<rrdgraph_data> and L<rrdgraph_rpn> for the exact format.
 403
 404 =item Graph and print elements
 405
 406 You need at least one graph element to generate an image and/or
 407 at least one print statement to generate a report.
 408 See L<rrdgraph_graph> for the exact format.
 409
 410 =item Markup
 411
 412 All text in rrdtool is rendered using Pango markup. This means text can contain embeded markup instructions.
 413 Simple html markup using
 414
 415  <span key="value">text</span>
 416
 417 can be used. Apart from the verbose syntax, there are also the following short tags available.
 418
 419  b     Bold
 420  big   Makes font relatively larger, equivalent to <span size="larger">
 421  i     Italic
 422  s     Strikethrough
 423  sub   Subscript
 424  sup   Superscript
 425  small Makes font relatively smaller, equivalent to <span size="smaller">
 426  tt    Monospace font
 427  u     Underline
 428
 429 More details on http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html.
 430
 431 =back
 432
 433 =head1 SEE ALSO
 434
 435 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
 436 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
 437 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
 438 L<rrdgraph_graph> page describes all of the graph and print functions.
 439
 440 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 441
 442 =head1 AUTHOR
 443
 444 Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 445
 446 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>
 447