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<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 normally
 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 currently 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 instead!>
 316
 317 B<Some notes on stacking>
 318
 319 When stacking, an element is not placed above the X-axis but rather
 320 on top of the previous element.  There must be something to stack
 321 upon.
 322
 323 You can use an B<invisible> LINE or AREA to stacked upon.
 324
 325 An B<unknown> value makes the entire stack unknown from that moment on.
 326 You don't know where to begin (the unknown value) and therefore do
 327 not know where to end.
 328
 329 If you want to make sure you will be displaying a certain variable,
 330 make sure never to stack upon the unknown value.  Use a CDEF instruction
 331 with B<IF> and B<UN> to do so.
 332
 333 =head1 NOTES on legend arguments
 334
 335 =head2 Escaping the colon
 336
 337 A colon ':' in a I<legend> argument will mark the end of the
 338 legend. To enter a ':' as part of a legend, the colon must be escaped
 339 with a backslash '\:'.  Beware that many environments process
 340 backslashes themselves, so it may be necessary to write two
 341 backslashes in order to one being passed onto rrd_graph.
 342
 343 =head2 String Formatting
 344
 345 The text printed below the actual graph can be formatted by appending special
 346 escape characters at the end of a text. When ever such a character occurs,
 347 all pending text is pushed onto the graph according to the character
 348 specified.
 349
 350 Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
 351 right aligned, and B<\c> for centered. In the next section there is an
 352 example showing how to use centered formatting.
 353
 354 B<\n> is a valid alias for B<\l> since incomplete parsing in earlier
 355 versions of RRDtool lead to this behavior and a number of people has been using it.
 356
 357 Normally there are two space characters inserted between every two items
 358 printed into the graph. The space following a string can be suppressed by
 359 putting a B<\g> at the end of the string. The B<\g> also ignores any space
 360 inside the string if it is at the very end of the string. This can be used
 361 in connection with B<%s> to suppress empty unit strings.
 362
 363  GPRINT:a:MAX:%lf%s\g
 364
 365 A special case is COMMENT:B<\s> which inserts some additional vertical space
 366 before placing the next row of legends.
 367
 368 If you want to have left and right aligned legends on the same line use COMMENT:B<\u>
 369 to go one line back like this:
 370
 371  COMMENT:left\l
 372  COMMENT:\u
 373  COMMENT:right\r
 374
 375 When using a proportional font in your graph, the tab
 376 characters or the sequence B<\t> will line-up legend elements. Note that
 377 the tabs inserted are relative to the start of the current legend
 378 element!
 379
 380 Since RRDtool 1.3 is using Pango for rending text, you can use Pango markup.
 381 Pango uses the xml B<span> tags for inline formatting instructions.:
 382
 383 A simple example of a marked-up string might be:
 384
 385  <span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!
 386
 387 The complete list of attributes for the span tag (taken from the pango documentation):
 388
 389 =over
 390
 391 =item B<font_desc>
 392
 393 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.
 394
 395 =item B<font_family>
 396
 397 A font family name
 398
 399 =item B<face>
 400
 401 Synonym for font_family
 402
 403 =item B<size>
 404
 405 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'.
 406
 407 =item B<style>
 408
 409 One of 'normal', 'oblique', 'italic'
 410
 411 =item B<weight>
 412
 413 One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a numeric weight
 414
 415 =item B<variant>
 416
 417 'normal' or 'smallcaps'
 418
 419 =item B<stretch>
 420
 421 One of 'ultracondensed', 'extracondensed', 'condensed', 'semicondensed', 'normal', 'semiexpanded', 'expanded', 'extraexpanded', 'ultraexpanded'
 422
 423 =item B<foreground>
 424
 425 An RGB color specification such as '#00FF00' or a color name such as 'red'
 426
 427 =item B<background>
 428
 429 An RGB color specification such as '#00FF00' or a color name such as 'red'
 430
 431 =item B<underline>
 432
 433 One of 'none', 'single', 'double', 'low', 'error'
 434
 435 =item B<underline_color>
 436
 437 The color of underlines; an RGB color specification such as '#00FF00' or a color name such as 'red'
 438
 439 =item B<rise>
 440
 441 Vertical displacement, in 10000ths of an em. Can be negative for subscript, positive for superscript.
 442
 443 =item B<strikethrough>
 444
 445 'true' or 'false' whether to strike through the text
 446
 447 =item B<strikethrough_color>
 448
 449 The color of crossed out lines; an RGB color specification such as '#00FF00' or a color name such as 'red'
 450
 451 =item B<fallback>
 452
 453 '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.
 454
 455 =item B<lang>
 456
 457 A language code, indicating the text language
 458
 459 =item B<letter_spacing>
 460
 461 Inter-letter spacing in 1024ths of a point.
 462
 463 =item B<gravity>
 464
 465 One of 'south', 'east', 'north', 'west', 'auto'.
 466
 467 =item B<gravity_hint>
 468
 469 One of 'natural', 'strong', 'line'.
 470
 471 =back
 472
 473 To save you some typing, there are also some shortcuts:
 474
 475 =over
 476
 477 =item B<b>
 478
 479 Bold
 480
 481 =item B<big>
 482
 483 Makes font relatively larger, equivalent to <span size="larger">
 484
 485 =item B<i>
 486
 487 Italic
 488
 489 =item B<s>
 490
 491 Strike through
 492
 493 =item B<sub>
 494
 495 Subscript
 496
 497 =item B<sup>
 498
 499 Superscript
 500
 501 =item B<small>
 502
 503 Makes font relatively smaller, equivalent to <span size="smaller">
 504
 505 =item B<tt>
 506
 507 Monospace font
 508
 509 =item B<u>
 510
 511 Underline
 512
 513 =back
 514
 515 =head1 SEE ALSO
 516
 517 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
 518 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
 519 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
 520 L<rrdgraph_graph> page describes all of the graph and print functions.
 521
 522 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 523
 524 =head1 AUTHOR
 525
 526 Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 527
 528 This manual page by Alex van den Bogaerdt E<lt>alex@vandenbogaerdt.nlE<gt>
 529 with corrections and/or additions by several people