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 clibrary. 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 dependant 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<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
 266
 267 Plot a tick mark (a vertical line) for each value of I<vname> that is
 268 non-zero and not *UNKNOWN*. The I<fraction> argument specifies the length of
 269 the tick mark as a fraction of the y-axis; the default value is 0.1 (10% of
 270 the axis). Note that the color specification is not optional. The TICK marks normaly
 271 start at the lower edge of the graphing area. If the fraction is negative they start
 272 at the upper border of the graphing area.
 273
 274 =head3 B<SHIFT>B<:>I<vname>B<:>I<offset>
 275
 276 Using this command B<RRDtool> will graph the following elements
 277 with the specified offset.  For instance, you can specify an
 278 offset of S<( 7*24*60*60 = ) 604'800 seconds> to "look back" one
 279 week. Make sure to tell the viewer of your graph you did this ...
 280 As with the other graphing elements, you can specify a number or
 281 a variable here.
 282
 283 =head3 B<TEXTALIGN>B<:>{B<left>|B<right>|B<justified>|B<center>}
 284
 285 Labels are placed below the graph. When they overflow to the left, they wrap
 286 to the next line. By default, lines are justified left and right. The
 287 B<TEXTALIGN> function lets you change this default. This is a command and
 288 not an option, so that you can change the default several times in your
 289 argument list.
 290
 291 =cut
 292
 293 # This section describes the curruently defunct
 294 # PieChart code.
 295 #
 296 # =item B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
 297 #
 298 # B<RRDtool> has now support for B<pie charts>. If you include the
 299 # B<PART> command, the canvas is extended to make room for a chart.
 300 # The size of the canvas is determined by the lesser of
 301 # L<width and height|rrdgraph/item_Size>.
 302 #
 303 # Pie parts will be concatenated, the first one will start at the
 304 # top and parts will be created clockwise.  The size of the part
 305 # is defined by the value part of the L<VDEF|rrdgraph_data/VDEF>
 306 # function.  It should return a number between 0 and 100, being a
 307 # percentage.  Providing wrong input will produce undefined results.
 308 #
 309 #
 310
 311 =pod
 312
 313 =head3 B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>]
 314
 315 I<Deprecated.  Use the B<STACK> modifiers on the other commands.>
 316
 317 =back
 318
 319 B<Some notes on stacking>
 320
 321 When stacking, an element is not placed above the X-axis but rather
 322 on top of the previous element.  There must be something to stack
 323 upon.
 324
 325 You can use an B<invisible> LINE or AREA to stacked upon.
 326
 327 An B<unknown> value makes the entire stack unknown from that moment on.
 328 You don't know where to begin (the unknown value) and therefore do
 329 not know where to end.
 330
 331 If you want to make sure you will be displaying a certain variable,
 332 make sure never to stack upon the unknown value.  Use a CDEF instruction
 333 with B<IF> and B<UN> to do so.
 334
 335 =head1 NOTES on legend arguments
 336
 337 =head2 Escaping the colon
 338
 339 A colon ':' in a I<legend> argument will mark the end of the
 340 legend. To enter a ':' as part of a legend, the colon must be escaped
 341 with a backslash '\:'.  Beware that many environments process
 342 backslashes themselves, so it may be necessary to write two
 343 backslashes in order to one being passed onto rrd_graph.
 344
 345 =head2 String Formatting
 346
 347 The text printed below the actual graph can be formatted by appending special
 348 escape characters at the end of a text. When ever such a character occurs,
 349 all pending text is pushed onto the graph according to the character
 350 specified.
 351
 352 Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
 353 right aligned, and B<\c> for centered. In the next section there is an
 354 example showing how to use centered formatting.
 355
 356 B<\n> is a valid alias for B<\l> since incomplete parsing in earlier
 357 versions of rrdtool lead to this behaviour and a number of people has been using it.
 358
 359 Normally there are two space characters inserted between every two items
 360 printed into the graph. The space following a string can be suppressed by
 361 putting a B<\g> at the end of the string. The B<\g> also ignores any space
 362 inside the string if it is at the very end of the string. This can be used
 363 in connection with B<%s> to suppress empty unit strings.
 364
 365  GPRINT:a:MAX:%lf%s\g
 366
 367 A special case is COMMENT:B<\s> which inserts some additional vertical space
 368 before placing the next row of legends.
 369
 370 If you are using the proportional font in your graph, you can use tab
 371 characters or the sequence B<\t> to line-up legend elements. Note that
 372 the tabs inserted are relative to the start of the current legend
 373 element!
 374
 375 Since RRDtool 1.3 is using Pango for rending text, you can use Pango markup.
 376 Pango uses the xml B<span> tags for inline formatting instructions.:
 377
 378 A simple example of a marked-up string might be:
 379
 380  <span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!
 381
 382 The complete list of attributes for the span tag (taken from the pango documentation):
 383
 384 =over
 385
 386 =item B<font_desc>
 387
 388 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.
 389
 390 =item B<font_family>
 391
 392 A font family name
 393
 394 =item B<face>
 395
 396 Synonym for font_family
 397
 398 =item B<size>
 399
 400 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'.
 401
 402 =item B<style>
 403
 404 One of 'normal', 'oblique', 'italic'
 405
 406 =item B<weight>
 407
 408 One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight
 409
 410 =item B<variant>
 411
 412 'normal' or 'smallcaps'
 413
 414 =item B<stretch>
 415
 416 One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'
 417
 418 =item B<foreground>
 419
 420 An RGB color specification such as '#00FF00' or a color name such as 'red'
 421
 422 =item B<background>
 423
 424 An RGB color specification such as '#00FF00' or a color name such as 'red'
 425
 426 =item B<underline>
 427
 428 One of 'none', 'single', 'double', 'low', 'error'
 429
 430 =item B<underline_color>
 431
 432 The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'
 433
 434 =item B<rise>
 435
 436 Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
 437
 438 =item B<strikethrough>
 439
 440 'true' or 'false' whether to strike through the text
 441
 442 =item B<strikethrough_color>
 443
 444 The color of strikethrough lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
 445
 446 =item B<fallback>
 447
 448 '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.
 449
 450 =item B<lang>
 451
 452 A language code, indicating the text language
 453
 454 =item B<letter_spacing>
 455
 456 Inter-letter spacing in 1024ths of a point.
 457
 458 =item B<gravity>
 459
 460 One of 'south', 'east', 'north', 'west', 'auto'.
 461
 462 =item B<gravity_hint>
 463
 464 One of 'natural', 'strong', 'line'.
 465
 466 =back
 467
 468 To save you some typing, there are also some shortcuts:
 469
 470 =over
 471
 472 =item B<b>
 473
 474 Bold
 475
 476 =item B<big>
 477
 478 Makes font relatively larger, equivalent to <span size="larger">
 479
 480 =item B<i>
 481
 482 Italic
 483
 484 =item B<s>
 485
 486 Strikethrough
 487
 488 =item B<sub>
 489
 490 Subscript
 491
 492 =item B<sup>
 493
 494 Superscript
 495
 496 =item B<small>
 497
 498 Makes font relatively smaller, equivalent to <span size="smaller">
 499
 500 =item B<tt>
 501
 502 Monospace font
 503
 504 =item B<u>
 505
 506 Underline
 507
 508 =back
 509
 510 =head1 SEE ALSO
 511
 512 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
 513 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
 514 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
 515 L<rrdgraph_graph> page describes all of the graph and print functions.
 516
 517 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 518
 519 =head1 AUTHOR
 520
 521 Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 522
 523 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>