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