doc/rrdgraph_graph.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 rrdgraph_graph - rrdtool graph command reference
   6
   7 =head1 SYNOPSIS
   8
   9 B<PRINT>B<:>I<vname>B<:>I<format>
  10
  11 B<GPRINT>B<:>I<vname>B<:>I<format>
  12
  13 B<COMMENT>B<:>I<text>
  14
  15 B<VRULE>B<:>I<time>B<#>I<color>[B<:>I<legend>][B<:dashes>[B<=>I<on_s>[,I<off_s>[,I<on_s>,I<off_s>]...]][B<:dash-offset=>I<offset>]]
  16
  17 B<HRULE>B<:>I<value>B<#>I<color>[B<:>I<legend>][B<:dashes>[B<=>I<on_s>[,I<off_s>[,I<on_s>,I<off_s>]...]][B<:dash-offset=>I<offset>]]
  18
  19 B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]][B<:dashes>[B<=>I<on_s>[,I<off_s>[,I<on_s>,I<off_s>]...]][B<:dash-offset=>I<offset>]]
  20
  21 B<AREA>B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
  22
  23 B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
  24
  25 B<SHIFT>B<:>I<vname>B<:>I<offset>
  26
  27 B<TEXTALIGN>B<:>{B<left>|B<right>|B<justified>|B<center>}
  28
  29 B<PRINT>B<:>I<vname>B<:>I<CF>B<:>I<format> (deprecated)
  30
  31 B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format> (deprecated)
  32
  33 B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>] (deprecated)
  34
  35 =head1 DESCRIPTION
  36
  37 These instructions allow you to generate your image or report.
  38 If you don't use any graph elements, no graph is generated.
  39 Similarly, no report is generated if you don't use print options.
  40
  41 =head2 PRINT
  42
  43 =head3 B<PRINT:>I<vname>B<:>I<format>[B<:strftime>]
  44
  45 Depending on the context, either the value component or the time
  46 component of a B<VDEF> is printed using I<format>. It is an error
  47 to specify a I<vname> generated by a B<DEF> or B<CDEF>.
  48
  49 Any text in I<format> is printed literally with one exception:
  50 The percent character introduces a formatter string. This string
  51 can be:
  52
  53 For printing values:
  54
  55 =over
  56
  57 =item B<%%>
  58
  59 just prints a literal '%' character
  60
  61 =item B<%#.#le>
  62
  63 prints numbers like 1.2346e+04. The optional integers # denote field
  64 width and decimal precision.
  65
  66 =item B<%#.#lf>
  67
  68 prints numbers like 12345.6789, with optional field width
  69 and precision.
  70
  71 =item B<%s>
  72
  73 place this after B<%le>, B<%lf> or B<%lg>. This will be replaced by the
  74 appropriate SI magnitude unit and the value will be scaled
  75 accordingly (123456 -> 123.456 k).
  76
  77 =item B<%S>
  78
  79 is similar to B<%s>. It does, however, use a previously defined
  80 magnitude unit. If there is no such unit yet, it tries to define
  81 one (just like B<%s>) unless the value is zero, in which case the magnitude
  82 unit stays undefined. Thus, formatter strings using B<%S> and no B<%s>
  83 will all use the same magnitude unit except for zero values.
  84
  85 =back
  86
  87 If you PRINT a VDEF value, you can also print the time associated with it by appending the string
  88 B<:strftime> to the format. Note that RRDtool uses the strftime function of your OSs C library. This means that
  89 the conversion specifier may vary. Check the manual page if you are uncertain. The following is a list of
  90 conversion specifiers usually supported across the board.
  91
  92 =over
  93
  94 =item B<%a>
  95
  96 The abbreviated weekday name according to the current locale.
  97
  98 =item B<%A>
  99
 100 The full weekday name according to the current locale.
 101
 102 =item B<%b>
 103
 104 The abbreviated month name according to the current locale.
 105
 106 =item B<%B>
 107
 108 The full month name according to the current locale.
 109
 110 =item B<%c>
 111
 112 The preferred date and time representation for the current locale.
 113
 114 =item B<%d>
 115
 116 The day of the month as a decimal number (range 01 to 31).
 117
 118 =item B<%H>
 119
 120 The hour as a decimal number using a 24-hour clock (range 00 to 23).
 121
 122 =item B<%I>
 123
 124 The hour as a decimal number using a 12-hour clock (range 01 to 12).
 125
 126 =item B<%j>
 127
 128 The day of the year as a decimal number (range 001 to 366).
 129
 130 =item B<%m>
 131
 132 The month as a decimal number (range 01 to 12).
 133
 134 =item B<%M>
 135
 136 The minute as a decimal number (range 00 to 59).
 137
 138 =item B<%p>
 139
 140 Either `AM' or `PM' according to the given time value, or the corresponding
 141 strings for the current locale.  Noon is treated as `pm' and midnight as
 142 `am'.  Note that in many locales and `pm' notation is unsupported and in
 143 such cases %p will return an empty string.
 144
 145 =item B<%s>
 146
 147 The second as a decimal number (range 00 to 61).
 148
 149 =item B<%S>
 150
 151 The seconds since the epoch (1.1.1970) (libc dependent non standard!)
 152
 153 =item B<%U>
 154
 155 The  week  number  of  the current year as a decimal number, range 00 to 53, starting with the
 156 first Sunday as the first day of week 01. See also %V and %W.
 157
 158 =item B<%V>
 159
 160 The ISO 8601:1988 week number of the current year as a decimal number, range 01 to  53,  where
 161 week  1 is the first week that has at least 4 days in the current year, and with Monday as the
 162 first day of the week. See also %U and %W.
 163
 164 =item B<%w>
 165
 166 The day of the week as a decimal, range 0 to 6, Sunday being 0.  See also %u.
 167
 168 =item B<%W>
 169
 170 The week number of the current year as a decimal number, range 00 to  53,  starting  with  the
 171 first Monday as the first day of week 01.
 172
 173 =item B<%x>
 174
 175 The preferred date representation for the current locale without the time.
 176
 177 =item B<%X>
 178
 179 The preferred time representation for the current locale without the date.
 180
 181 =item B<%y>
 182
 183 The year as a decimal number without a century (range 00 to 99).
 184
 185 =item B<%Y>
 186
 187 The year as a decimal number including the century.
 188
 189 =item B<%Z>
 190
 191 The time zone or name or abbreviation.
 192
 193 =item B<%%>
 194
 195 A literal `%' character.
 196
 197 =back
 198
 199 =head3 B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>
 200
 201 I<Deprecated. Use the new form of this command in new scripts.>
 202 The first form of this command is to be used with B<CDEF> I<vname>s.
 203
 204
 205 =head2 GRAPH
 206
 207 =head3 B<GPRINT>B<:>I<vname>B<:>I<format>
 208
 209 This is the same as C<PRINT>, but printed inside the graph.
 210
 211 =head3 B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format>
 212
 213 I<Deprecated. Use the new form of this command in new scripts.>
 214 This is the same as C<PRINT>, but printed inside the graph.
 215
 216 =head3 B<COMMENT>B<:>I<text>
 217
 218 Text is printed literally in the legend section of the graph. Note that in
 219 RRDtool 1.2 you have to escape colons in COMMENT text in the same way you
 220 have to escape them in B<*PRINT> commands by writing B<'\:'>.
 221
 222 =head3 B<VRULE>B<:>I<time>B<#>I<color>[B<:>I<legend>][B<:dashes>[B<=>I<on_s>[,I<off_s>[,I<on_s>,I<off_s>]...]][B<:dash-offset=>I<offset>]]
 223
 224 Draw a vertical line at I<time>.  Its color is composed from three
 225 hexadecimal numbers specifying the rgb color components (00 is off, FF is
 226 maximum) red, green and blue followed by an optional alpha. Optionally, a legend box and string is
 227 printed in the legend section. I<time> may be a number or a variable
 228 from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
 229 Dashed lines can be drawn using the B<dashes> modifier. See B<LINE> for more
 230 details.
 231
 232 =head3 B<HRULE>B<:>I<value>B<#>I<color>[B<:>I<legend>][B<:dashes>[B<=>I<on_s>[,I<off_s>[,I<on_s>,I<off_s>]...]][B<:dash-offset=>I<offset>]]
 233
 234 Draw a horizontal line at I<value>.  HRULE acts much like LINE except that
 235 will have no effect on the scale of the graph. If a HRULE is outside the
 236 graphing area it will just not be visible.
 237
 238 =head3 B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]][B<:dashes>[B<=>I<on_s>[,I<off_s>[,I<on_s>,I<off_s>]...]][B<:dash-offset=>I<offset>]]
 239
 240 Draw a line of the specified width onto the graph. I<width> can be a
 241 floating point number. If the color is not specified, the drawing is done
 242 'invisibly'. This is useful when stacking something else on top of this
 243 line. Also optional is the legend box and string which will be printed in
 244 the legend section if specified. The B<value> can be generated by B<DEF>,
 245 B<VDEF>, and B<CDEF>.  If the optional B<STACK> modifier is used, this line
 246 is stacked on top of the previous element which can be a B<LINE> or an
 247 B<AREA>.
 248
 249 The B<dashes> modifier enables dashed line style. Without any further options
 250 a symmetric dashed line with a segment length of 5 pixels will be drawn. The
 251 dash pattern can be changed if the B<dashes=> parameter is followed by either
 252 one value or an even number (1, 2, 4, 6, ...) of positive values. Each value
 253 provides the length of alternate I<on_s> and I<off_s> portions of the
 254 stroke. The B<dash-offset> parameter specifies an I<offset> into the pattern
 255 at which the stroke begins.
 256
 257 When you do not specify a color, you cannot specify a legend.  Should
 258 you want to use STACK, use the "LINEx:<value>::STACK" form.
 259
 260 =head3 B<AREA>B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
 261
 262 See B<LINE>, however the area between the x-axis and the line will
 263 be filled.
 264
 265 =head3 B<GRAD>B<:>I<value>[B<#>I<color1>[B<#>I<color2>B<:>I<height>][B<:>[I<legend>][B<:STACK>]]
 266
 267 Similar to B<AREA>, except the area between the line and the x-axis will contain a gradient from color1 to color2.
 268
 269 The I<height> parameter can create three different behaviors. If I<height> > 0, then the gradient is a fixed height, starting at the line going down. If I<height> < 0, then the gradient starts at fixed height above the x-axis, going down to the x-axis. If I<height> == 0, then the gradient goes from the line to x-axis.
 270
 271 If not present, I<color2> defaults to #00000000 and I<height> defaults to 50.
 272
 273 =head3 B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
 274
 275 Plot a tick mark (a vertical line) for each value of I<vname> that is
 276 non-zero and not *UNKNOWN*. The I<fraction> argument specifies the length of
 277 the tick mark as a fraction of the y-axis; the default value is 0.1 (10% of
 278 the axis). Note that the color specification is not optional. The TICK marks normally
 279 start at the lower edge of the graphing area. If the fraction is negative they start
 280 at the upper border of the graphing area.
 281
 282 =head3 B<SHIFT>B<:>I<vname>B<:>I<offset>
 283
 284 Using this command B<RRDtool> will graph the following elements
 285 with the specified offset.  For instance, you can specify an
 286 offset of S<( 7*24*60*60 = ) 604'800 seconds> to "look back" one
 287 week. Make sure to tell the viewer of your graph you did this ...
 288 As with the other graphing elements, you can specify a number or
 289 a variable here.
 290
 291 =head3 B<TEXTALIGN>B<:>{B<left>|B<right>|B<justified>|B<center>}
 292
 293 Labels are placed below the graph. When they overflow to the left, they wrap
 294 to the next line. By default, lines are justified left and right. The
 295 B<TEXTALIGN> function lets you change this default. This is a command and
 296 not an option, so that you can change the default several times in your
 297 argument list.
 298
 299 =cut
 300
 301 # This section describes the currently defunct
 302 # PieChart code.
 303 #
 304 # =item B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
 305 #
 306 # B<RRDtool> has now support for B<pie charts>. If you include the
 307 # B<PART> command, the canvas is extended to make room for a chart.
 308 # The size of the canvas is determined by the lesser of
 309 # L<width and height|rrdgraph/item_Size>.
 310 #
 311 # Pie parts will be concatenated, the first one will start at the
 312 # top and parts will be created clockwise.  The size of the part
 313 # is defined by the value part of the L<VDEF|rrdgraph_data/VDEF>
 314 # function.  It should return a number between 0 and 100, being a
 315 # percentage.  Providing wrong input will produce undefined results.
 316 #
 317 #
 318
 319 =pod
 320
 321 =head3 B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>]
 322
 323 I<Deprecated.  Use the B<STACK> modifiers on the other commands instead!>
 324
 325 B<Some notes on stacking>
 326
 327 When stacking, an element is not placed above the X-axis but rather
 328 on top of the previous element.  There must be something to stack
 329 upon.
 330
 331 You can use an B<invisible> LINE or AREA to stacked upon.
 332
 333 An B<unknown> value makes the entire stack unknown from that moment on.
 334 You don't know where to begin (the unknown value) and therefore do
 335 not know where to end.
 336
 337 If you want to make sure you will be displaying a certain variable,
 338 make sure never to stack upon the unknown value.  Use a CDEF instruction
 339 with B<IF> and B<UN> to do so.
 340
 341 =head1 NOTES on legend arguments
 342
 343 =head2 Escaping the colon
 344
 345 A colon ':' in a I<legend> argument will mark the end of the
 346 legend. To enter a ':' as part of a legend, the colon must be escaped
 347 with a backslash '\:'.  Beware that many environments process
 348 backslashes themselves, so it may be necessary to write two
 349 backslashes in order to one being passed onto rrd_graph.
 350
 351 =head2 String Formatting
 352
 353 The text printed below the actual graph can be formatted by appending special
 354 escape characters at the end of a text. When ever such a character occurs,
 355 all pending text is pushed onto the graph according to the character
 356 specified.
 357
 358 Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
 359 right aligned, and B<\c> for centered. In the next section there is an
 360 example showing how to use centered formatting.
 361
 362 B<\n> is a valid alias for B<\l> since incomplete parsing in earlier
 363 versions of RRDtool lead to this behavior and a number of people has been using it.
 364
 365 Normally there are two space characters inserted between every two items
 366 printed into the graph. The space following a string can be suppressed by
 367 putting a B<\g> at the end of the string. The B<\g> also ignores any space
 368 inside the string if it is at the very end of the string. This can be used
 369 in connection with B<%s> to suppress empty unit strings.
 370
 371  GPRINT:a:MAX:%lf%s\g
 372
 373 A special case is COMMENT:B<\s> which inserts some additional vertical space
 374 before placing the next row of legends.
 375
 376 If you want to have left and right aligned legends on the same line use COMMENT:B<\u>
 377 to go one line back like this:
 378
 379  COMMENT:left\l
 380  COMMENT:\u
 381  COMMENT:right\r
 382
 383 There is also a 'nop' control for situations where you want a string to
 384 actually end in a backslash character sequence B<\.>
 385
 386  COMMENT:OS\2\.
 387
 388 When using a proportional font in your graph, the tab
 389 characters or the sequence B<\t> will line-up legend elements. Note that
 390 the tabs inserted are relative to the start of the current legend
 391 element!
 392
 393 Since RRDtool 1.3 is using Pango for rending text, you can use Pango markup.
 394 Pango uses the xml B<span> tags for inline formatting instructions.:
 395
 396 A simple example of a marked-up string might be:
 397
 398  <span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!
 399
 400 The complete list of attributes for the span tag (taken from the pango documentation):
 401
 402 =over
 403
 404 =item B<font_desc>
 405
 406 A font description string, such as "Sans Italic 12"; note that any other span attributes will override this description. So if you have "Sans Italic" and also a style="normal" attribute, you will get Sans normal, not italic.
 407
 408 =item B<font_family>
 409
 410 A font family name
 411
 412 =item B<face>
 413
 414 Synonym for font_family
 415
 416 =item B<size>
 417
 418 Font size in 1024ths of a point, or one of the absolute sizes 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large', or one of the relative sizes 'smaller' or 'larger'. If you want to specify a absolute size, it's usually easier to take advantage of the ability to specify a partial font description using 'font_desc'; you can use font_desc='12.5' rather than size='12800'.
 419
 420 =item B<style>
 421
 422 One of 'normal', 'oblique', 'italic'
 423
 424 =item B<weight>
 425
 426 One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight
 427
 428 =item B<variant>
 429
 430 'normal' or 'smallcaps'
 431
 432 =item B<stretch>
 433
 434 One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'
 435
 436 =item B<foreground>
 437
 438 An RGB color specification such as '#00FF00' or a color name such as 'red'
 439
 440 =item B<background>
 441
 442 An RGB color specification such as '#00FF00' or a color name such as 'red'
 443
 444 =item B<underline>
 445
 446 One of 'none', 'single', 'double', 'low', 'error'
 447
 448 =item B<underline_color>
 449
 450 The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'
 451
 452 =item B<rise>
 453
 454 Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
 455
 456 =item B<strikethrough>
 457
 458 'true' or 'false' whether to strike through the text
 459
 460 =item B<strikethrough_color>
 461
 462 The color of crossed out lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
 463
 464 =item B<fallback>
 465
 466 'true' or 'false' whether to enable fallback. If disabled, then characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text. Fallback is enabled by default. Most applications should not disable fallback.
 467
 468 =item B<lang>
 469
 470 A language code, indicating the text language
 471
 472 =item B<letter_spacing>
 473
 474 Inter-letter spacing in 1024ths of a point.
 475
 476 =item B<gravity>
 477
 478 One of 'south', 'east', 'north', 'west', 'auto'.
 479
 480 =item B<gravity_hint>
 481
 482 One of 'natural', 'strong', 'line'.
 483
 484 =back
 485
 486 To save you some typing, there are also some shortcuts:
 487
 488 =over
 489
 490 =item B<b>
 491
 492 Bold
 493
 494 =item B<big>
 495
 496 Makes font relatively larger, equivalent to <span size="larger">
 497
 498 =item B<i>
 499
 500 Italic
 501
 502 =item B<s>
 503
 504 Strike through
 505
 506 =item B<sub>
 507
 508 Subscript
 509
 510 =item B<sup>
 511
 512 Superscript
 513
 514 =item B<small>
 515
 516 Makes font relatively smaller, equivalent to <span size="smaller">
 517
 518 =item B<tt>
 519
 520 Monospace font
 521
 522 =item B<u>
 523
 524 Underline
 525
 526 =back
 527
 528 =head1 SEE ALSO
 529
 530 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
 531 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
 532 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
 533 L<rrdgraph_graph> page describes all of the graph and print functions.
 534
 535 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 536
 537 =head1 AUTHOR
 538
 539 Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 540
 541 This manual page by Alex van den Bogaerdt E<lt>alex@vandenbogaerdt.nlE<gt>
 542 with corrections and/or additions by several people