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 Gridfitting is turned off for PDF, EPS, SVG output by default.
 155
 156 =item Grid
 157
 158 =over 4
 159
 160 =item X-Axis
 161
 162 [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>]
 163
 164 [B<-x>|B<--x-grid> B<none>]
 165
 166 The x-axis label is quite complex to configure. If you don't have
 167 very special needs it is probably best to rely on the autoconfiguration
 168 to get this right. You can specify the string C<none> to suppress the grid
 169 and labels altogether.
 170
 171 The grid is defined by specifying a certain amount of time in the I<?TM>
 172 positions. You can choose from C<SECOND>, C<MINUTE>, C<HOUR>, C<DAY>,
 173 C<WEEK>, C<MONTH> or C<YEAR>. Then you define how many of these should
 174 pass between each line or label.  This pair (I<?TM:?ST>) needs to be
 175 specified for the base grid (I<G??>), the major grid (I<M??>) and the
 176 labels (I<L??>). For the labels you also must define a precision
 177 in I<LPR> and a I<strftime> format string in I<LFM>.  I<LPR> defines
 178 where each label will be placed. If it is zero, the label will be
 179 placed right under the corresponding line (useful for hours, dates
 180 etcetera).  If you specify a number of seconds here the label is
 181 centered on this interval (useful for Monday, January etcetera).
 182
 183  --x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X
 184
 185 This places grid lines every 10 minutes, major grid lines every hour,
 186 and labels every 4 hours. The labels are placed under the major grid
 187 lines as they specify exactly that time.
 188
 189  --x-grid HOUR:8:DAY:1:DAY:1:86400:%A
 190
 191 This places grid lines every 8 hours, major grid lines and labels
 192 each day. The labels are placed exactly between two major grid lines
 193 as they specify the complete day and not just midnight.
 194
 195 =item Y-Axis
 196
 197 [B<-y>|B<--y-grid> I<grid step>B<:>I<label factor>]
 198
 199 [B<-y>|B<--y-grid> B<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 suppress the grid and labels altogether.  The default for this option is
 204 to automatically select sensible values.
 205
 206 If you have set --y-grid to 'none' not only the labels get supressed, also
 207 the space reserved for the labels is removed. You can still add space
 208 manually if you use the --units-length command to explicitly reserve space.
 209
 210 [B<-Y>|B<--alt-y-grid>]
 211
 212 Place the Y grid dynamically based on the graph's Y range. The algorithm
 213 ensures that you always have a grid, that there are enough but not too many
 214 grid lines, and that the grid is metric. That is the grid lines are placed
 215 every 1, 2, 5 or 10 units. This parameter will also ensure that you get
 216 enough decimals displayed even if your graph goes from 69.998 to 70.001.
 217 (contributed by Sasha Mikheev).
 218
 219 [B<-o>|B<--logarithmic>]
 220
 221 Logarithmic y-axis scaling.
 222
 223 [B<-X>|B<--units-exponent> I<value>]
 224
 225 This sets the 10**exponent scaling of the y-axis values. Normally,
 226 values will be scaled to the appropriate units (k, M, etc.).  However,
 227 you may wish to display units always in k (Kilo, 10e3) even if the data
 228 is in the M (Mega, 10e6) range, for instance. Value should be an
 229 integer which is a multiple of 3 between -18 and 18 inclusively.  It is
 230 the exponent on the units you wish to use. For example, use 3 to
 231 display the y-axis values in k (Kilo, 10e3, thousands), use -6 to
 232 display the y-axis values in u (Micro, 10e-6, millionths).  Use a value
 233 of 0 to prevent any scaling of the y-axis values.
 234
 235 This option is very effective at confusing the heck out of the default
 236 rrdtool autoscaler and grid painter. If rrdtool detects that it is not
 237 successful in labeling the graph under the given circumstances, it will switch
 238 to the more robust B<--alt-y-grid> mode.
 239
 240 [B<-L>|B<--units-length> I<value>]
 241
 242 How many digits should rrdtool assume the y-axis labels to be? You
 243 may have to use this option to make enough space once you start
 244 fideling with the y-axis labeling.
 245
 246 [B<--units=si>]
 247
 248 With this option y-axis values on logarithmic graphs will be scaled to
 249 the appropriate units (k, M, etc.) instead of using exponential notation.
 250 Note that for linear graphs, SI notation is used by default.
 251
 252 =back
 253
 254 =item Miscellaneous
 255
 256 [B<-z>|B<--lazy>]
 257
 258 Only generate the graph if the current graph is out of date or not
 259 existent.
 260
 261 [B<-f>|B<--imginfo> I<printfstr>]
 262
 263 After the image has been created, the graph function uses printf
 264 together with this format string to create output similar to the PRINT
 265 function, only that the printf function is supplied with the parameters
 266 I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag
 267 suitable for including the graph into a web page, the command line
 268 would look like this:
 269
 270  --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
 271
 272 [B<-c>|B<--color> I<COLORTAG>#I<rrggbb>[I<aa>]]
 273
 274 Override the default colors for the standard elements of the graph. The
 275 I<COLORTAG> is one of C<BACK> background, C<CANVAS> for the background of
 276 the actual graph, C<SHADEA> for the left and top border, C<SHADEB> for the
 277 right and bottom border, C<GRID>, C<MGRID> for the major grid, C<FONT> for
 278 the color of the font, C<AXIS> for the axis of the graph, C<FRAME> for the
 279 line around the color spots and finally C<ARROW> for the arrow head pointing
 280 up and forward. Each color is composed out of three hexadecimal numbers
 281 specifying its rgb color component (00 is off, FF is maximum) of red, green
 282 and blue. Optionally you may add another hexadecimal number specifying the
 283 transparency (FF is solid). You may set this option several times to alter
 284 multiple defaults.
 285
 286 A green arrow is made by: C<--color ARROW#00FF00>
 287
 288 [B<--zoom> I<factor>]
 289
 290 Zoom the graphics by the given amount. The factor must be E<gt> 0
 291
 292 [B<-n>|B<--font> I<FONTTAG>B<:>I<size>B<:>[I<font>]]
 293
 294 This lets you customize which font to use for the various text
 295 elements on the RRD graphs. C<DEFAULT> sets the default value for all
 296 elements, C<TITLE> for the title, C<AXIS> for the axis labels, C<UNIT>
 297 for the vertical unit label, C<LEGEND> for the graph legend.
 298
 299 Use Times for the title: C<--font TITLE:13:Times>
 300
 301 If you do not give a font string you can modify just the sice of the default font:
 302 C<--font TITLE:13:>.
 303
 304 If you specify the size 0 then you can modify just the font without touching
 305 the size. This is especially usefull for altering the default font without
 306 resetting the default fontsizes: C<--font DEFAULT:0:Courier>.
 307
 308 RRDtool comes with a preset default font. You can set the environment
 309 variable C<RRD_DEFAULT_FONT> if you want to change this.
 310
 311 RRDtool uses Pango for its font handling. This means you can to use
 312 the full Pango syntax when selecting your font:
 313
 314 The font name has the form "[I<FAMILY-LIST>] [I<STYLE-OPTIONS>] [I<SIZE>]",
 315 where I<FAMILY-LIST> is a comma separated list of families optionally
 316 terminated by a comma, I<STYLE_OPTIONS> is a whitespace separated list of
 317 words where each WORD describes one of style, variant, weight, stretch, or
 318 gravity, and I<SIZE> is a decimal number (size in points) or optionally
 319 followed by the unit modifier "px" for absolute size. Any one of the options
 320 may be absent.
 321
 322 [B<-R>|B<--font-render-mode> {B<normal>,B<light>,B<mono>}]
 323
 324 There are 3 font render modes:
 325
 326 B<normal>: Full Hinting and Antialiasing (default)
 327
 328 B<light>: Slight Hinting and Antialiasing
 329
 330 B<mono>: Full Hinting and NO Antialiasing
 331
 332
 333 [B<-B>|B<--font-smoothing-threshold> I<size>]
 334
 335 (this gets ignored in 1.3 for now!)
 336
 337 This specifies the largest font size which will be rendered
 338 bitmapped, that is, without any font smoothing. By default,
 339 no text is rendered bitmapped.
 340
 341 [B<-G>|B<--graph-render-mode> {B<normal>,B<mono>}]
 342
 343 There are 2 render modes:
 344
 345 B<normal>: Graphs are fully Antialiased (default)
 346
 347 B<mono>: No Antialiasing
 348
 349 [B<-E>|B<--slope-mode>]
 350
 351 RRDtool graphs are composed of stair case curves by default. This is in line with
 352 the way RRDtool calculates its data. Some people favor a more 'organic' look
 353 for their graphs even though it is not all that true.
 354
 355 [B<-a>|B<--imgformat> B<PNG>|B<SVG>|B<EPS>|B<PDF>]
 356
 357 Image format for the generated graph. For the vector formats you can
 358 choose among the standard Postscript fonts Courier-Bold,
 359 Courier-BoldOblique, Courier-Oblique, Courier, Helvetica-Bold,
 360 Helvetica-BoldOblique, Helvetica-Oblique, Helvetica, Symbol,
 361 Times-Bold, Times-BoldItalic, Times-Italic, Times-Roman, and ZapfDingbats.
 362
 363 [B<-i>|B<--interlaced>]
 364
 365 (this gets ignored in 1.3 for now!)
 366
 367 If images are interlaced they become visible on browsers more quickly.
 368
 369 [B<-g>|B<--no-legend>]
 370
 371 Suppress generation of the legend; only render the graph.
 372
 373 [B<-F>|B<--force-rules-legend>]
 374
 375 Force the generation of HRULE and VRULE legends even if those HRULE or
 376 VRULE will not be drawn because out of graph boundaries (mimics
 377 behaviour of pre 1.0.42 versions).
 378
 379 [B<-T>|B<--tabwidth> I<value>]
 380
 381 By default the tab-width is 40 pixels, use this option to change it.
 382
 383 [B<-b>|B<--base> I<value>]
 384
 385 If you are graphing memory (and NOT network traffic) this switch
 386 should be set to 1024 so that one Kb is 1024 byte. For traffic
 387 measurement, 1 kb/s is 1000 b/s.
 388
 389 [B<-W>|B<--watermark> I<string>]
 390
 391 Adds the given string as a watermark, horizontally centred, at the bottom
 392 of the graph.
 393
 394 =item Data and variables
 395
 396 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>]
 397
 398 B<CDEF:>I<vname>B<=>I<RPN expression>
 399
 400 B<VDEF:>I<vname>B<=>I<RPN expression>
 401
 402 You need at least one B<DEF> statement to generate anything. The
 403 other statements are useful but optional.
 404 See L<rrdgraph_data> and L<rrdgraph_rpn> for the exact format.
 405
 406 =item Graph and print elements
 407
 408 You need at least one graph element to generate an image and/or
 409 at least one print statement to generate a report.
 410 See L<rrdgraph_graph> for the exact format.
 411
 412 =item Markup
 413
 414 All text in rrdtool is rendered using Pango markup. This means text can contain embeded markup instructions.
 415 Simple html markup using
 416
 417  <span key="value">text</span>
 418
 419 can be used. Apart from the verbose syntax, there are also the following short tags available.
 420
 421  b     Bold
 422  big   Makes font relatively larger, equivalent to <span size="larger">
 423  i     Italic
 424  s     Strikethrough
 425  sub   Subscript
 426  sup   Superscript
 427  small Makes font relatively smaller, equivalent to <span size="smaller">
 428  tt    Monospace font
 429  u     Underline
 430
 431 More details on http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFormat.html.
 432
 433 =back
 434
 435 =head1 SEE ALSO
 436
 437 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
 438 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
 439 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
 440 L<rrdgraph_graph> page describes all of the graph and print functions.
 441
 442 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 443
 444 =head1 AUTHOR
 445
 446 Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 447
 448 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>
 449