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>]
  16
  17 B<HRULE>B<:>I<value>B<#>I<color>[B<:>I<legend>]
  18
  19 B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
  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 =cut
  28
  29 #
  30 #B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
  31 #
  32
  33 =pod
  34
  35 B<PRINT>B<:>I<vname>B<:>I<CF>B<:>I<format> (deprecated)
  36
  37 B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format> (deprecated)
  38
  39
  40 B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>] (deprecated)
  41
  42 =head1 DESCRIPTION
  43
  44 These instructions allow you to generate your image or report.
  45 If you don't use any graph elements, no graph is generated.
  46 Similarly, no report is generated if you don't use print options.
  47
  48 =head1 PRINT
  49
  50 =over 4
  51
  52
  53 =item B<PRINT:>I<vname>B<:>I<format>[B<:strftime>]
  54
  55 Depending on the context, either the value component or the time
  56 component of a B<VDEF> is printed using I<format>. It is an error
  57 to specify a I<vname> generated by a B<DEF> or B<CDEF>.
  58
  59 Any text in I<format> is printed literally with one exception:
  60 The percent character introduces a formatter string. This string
  61 can be:
  62
  63 For printing values:
  64
  65 =over 4
  66
  67 =item B<%%>
  68
  69 just prints a literal '%' character
  70
  71 =item B<%#.#le>
  72
  73 prints numbers like 1.2346e+04. The optional integers # denote field
  74 width and decimal precision.
  75
  76 =item B<%#.#lf>
  77
  78 prints numbers like 12345.6789, with optional field width
  79 and precision.
  80
  81 =item B<%s>
  82
  83 place this after B<%le>, B<%lf> or B<%lg>. This will be replaced by the
  84 appropriate SI magnitude unit and the value will be scaled
  85 accordingly (123456 -> 123.456 k).
  86
  87 =item B<%S>
  88
  89 is similar to B<%s>. It does, however, use a previously defined
  90 magnitude unit. If there is no such unit yet, it tries to define
  91 one (just like B<%s>) unless the value is zero, in which case the magnitude
  92 unit stays undefined. Thus, formatter strings using B<%S> and no B<%s>
  93 will all use the same magnitude unit except for zero values.
  94
  95 =back
  96
  97 If you PRINT a VDEF value, you can also print the time associated with it by appending the string
  98 B<:strftime> to the format. Note that rrdtool uses the strftime function of your OSs clibrary. This means that
  99 the conversion specifier may vary. Check the manual page if you are uncertain. The following is a list of
 100 conversion specifiers usually supported across the board.
 101
 102 =over 4
 103
 104 =item B<%a>
 105
 106 The abbreviated weekday name according to the current locale.
 107
 108 =item B<%A>
 109
 110 The full weekday name according to the current locale.
 111
 112 =item B<%b>
 113
 114 The abbreviated month name according to the current locale.
 115
 116 =item B<%B>
 117
 118 The full month name according to the current locale.
 119
 120 =item B<%c>
 121
 122 The preferred date and time representation for the current locale.
 123
 124 =item B<%d>
 125
 126 The day of the month as a decimal number (range 01 to 31).
 127
 128 =item B<%H>
 129
 130 The hour as a decimal number using a 24-hour clock (range 00 to 23).
 131
 132 =item B<%I>
 133
 134 The hour as a decimal number using a 12-hour clock (range 01 to 12).
 135
 136 =item B<%j>
 137
 138 The day of the year as a decimal number (range 001 to 366).
 139
 140 =item B<%m>
 141
 142 The month as a decimal number (range 01 to 12).
 143
 144 =item B<%M>
 145
 146 The minute as a decimal number (range 00 to 59).
 147
 148 =item B<%p>
 149
 150 Either `AM' or `PM' according to the given time value, or the corresponding
 151 strings for the current locale.  Noon is treated as `pm' and midnight as
 152 `am'.  Note that in many locales and `pm' notation is unsupported and in
 153 such cases %p will return an empty string.
 154
 155 =item B<%S>
 156
 157 The second as a decimal number (range 00 to 61).
 158
 159 =item B<%U>
 160
 161 The  week  number  of  the current year as a decimal number, range 00 to 53, starting with the
 162 first Sunday as the first day of week 01. See also %V and %W.
 163
 164 =item B<%V>
 165
 166 The ISO 8601:1988 week number of the current year as a decimal number, range 01 to  53,  where
 167 week  1 is the first week that has at least 4 days in the current year, and with Monday as the
 168 first day of the week. See also %U and %W.
 169
 170 =item B<%w>
 171
 172 The day of the week as a decimal, range 0 to 6, Sunday being 0.  See also %u.
 173
 174 =item B<%W>
 175
 176 The week number of the current year as a decimal number, range 00 to  53,  starting  with  the
 177 first Monday as the first day of week 01.
 178
 179 =item B<%x>
 180
 181 The preferred date representation for the current locale without the time.
 182
 183 =item B<%X>
 184
 185 The preferred time representation for the current locale without the date.
 186
 187 =item B<%y>
 188
 189 The year as a decimal number without a century (range 00 to 99).
 190
 191 =item B<%Y>
 192
 193 The year as a decimal number including the century.
 194
 195 =item B<%Z>
 196
 197 The time zone or name or abbreviation.
 198
 199 =item B<%%>
 200
 201 A literal `%' character.
 202
 203 =back
 204
 205 =item B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>
 206
 207 I<Deprecated. Use the new form of this command in new scripts.>
 208 The first form of this command is to be used with B<CDEF> I<vname>s.
 209
 210 =back
 211
 212 =head1 GRAPH
 213
 214 =over 4
 215
 216 =item B<GPRINT>B<:>I<vname>B<:>I<format>
 217
 218 This is the same as C<PRINT>, but printed inside the graph.
 219
 220 =item B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format>
 221
 222 I<Deprecated. Use the new form of this command in new scripts.>
 223 This is the same as C<PRINT>, but printed inside the graph.
 224
 225 =item B<COMMENT>B<:>I<text>
 226
 227 Text is printed literally in the legend section of the graph. Note that in
 228 RRDtool 1.2 you have to escape colons in COMMENT text in the same way you
 229 have to escape them in B<*PRINT> commands by writing B<'\:'>.
 230
 231 =item B<VRULE>B<:>I<time>B<#>I<color> [B<:>I<legend> ]
 232
 233 Draw a vertical line at I<time>.  Its color is composed from three
 234 hexadecimal numbers specifying the rgb color components (00 is off, FF is
 235 maximum) red, green and blue followed by an optional alpha. Optionally, a legend box and string is
 236 printed in the legend section. I<time> may be a number or a variable
 237 from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
 238
 239 =item B<HRULE>B<:>I<value>B<#>I<color> [ :I<legend> ]
 240
 241 Draw a horizontal line at I<value>.  HRULE acts much like LINE except that
 242 will have no effect on the scale of the graph. If a HRULE is outside the
 243 graphing area it will just not be visible.
 244
 245 =item B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
 246
 247 Draw a line of the specified width onto the graph. I<width> can be a
 248 floating point number. If the color is not specified, the drawing is done
 249 'invisibly'. This is useful when stacking something else on top of this
 250 line. Also optional is the legend box and string which will be printed in
 251 the legend section if specified. The B<value> can be generated by B<DEF>,
 252 B<VDEF>, and B<CDEF>.  If the optional B<STACK> modifier is used, this line
 253 is stacked on top of the previous element which can be a B<LINE> or an
 254 B<AREA>.
 255
 256 When you do not specify a color, you cannot specify a legend.  Should
 257 you want to use STACK, use the "LINEx:<value>::STACK" form.
 258
 259 =item B<AREA>B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
 260
 261 See B<LINE>, however the area between the x-axis and the line will
 262 be filled.
 263
 264 =item B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
 265
 266 Plot a tick mark (a vertical line) for each value of I<vname> that is
 267 non-zero and not *UNKNOWN*. The I<fraction> argument specifies the length of
 268 the tick mark as a fraction of the y-axis; the default value is 0.1 (10% of
 269 the axis). Note that the color specification is not optional. The TICK marks normaly
 270 start at the lower edge of the graphing area. If the fraction is negative they start
 271 at the upper border of the graphing area.
 272
 273 =item B<SHIFT>B<:>I<vname>B<:>I<offset>
 274
 275 Using this command B<RRDtool> will graph the following elements
 276 with the specified offset.  For instance, you can specify an
 277 offset of S<( 7*24*60*60 = ) 604'800 seconds> to "look back" one
 278 week. Make sure to tell the viewer of your graph you did this ...
 279 As with the other graphing elements, you can specify a number or
 280 a variable here.
 281
 282 =cut
 283
 284 # This section describes the curruently defunct
 285 # PieChart code.
 286 #
 287 # =item B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
 288 #
 289 # B<RRDtool> has now support for B<pie charts>. If you include the
 290 # B<PART> command, the canvas is extended to make room for a chart.
 291 # The size of the canvas is determined by the lesser of
 292 # L<width and height|rrdgraph/item_Size>.
 293 #
 294 # Pie parts will be concatenated, the first one will start at the
 295 # top and parts will be created clockwise.  The size of the part
 296 # is defined by the value part of the L<VDEF|rrdgraph_data/VDEF>
 297 # function.  It should return a number between 0 and 100, being a
 298 # percentage.  Providing wrong input will produce undefined results.
 299 #
 300 #
 301
 302 =pod
 303
 304 =item B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>]
 305
 306 I<Deprecated.  Use the B<STACK> modifiers on the other commands.>
 307
 308 =back
 309
 310 B<Some notes on stacking>
 311
 312 When stacking, an element is not placed above the X-axis but rather
 313 on top of the previous element.  There must be something to stack
 314 upon.
 315
 316 You can use an B<invisible> LINE or AREA to stacked upon.
 317
 318 An B<unknown> value makes the entire stack unknown from that moment on.
 319 You don't know where to begin (the unknown value) and therefore do
 320 not know where to end.
 321
 322 If you want to make sure you will be displaying a certain variable,
 323 make sure never to stack upon the unknown value.  Use a CDEF instruction
 324 with B<IF> and B<UN> to do so.
 325
 326 =head1 NOTES on legend arguments
 327
 328 =head2 Escaping the colon
 329
 330 A colon ':' in a I<legend> argument will mark the end of the
 331 legend. To enter a ':' as part of a legend, the colon must be escaped
 332 with a backslash '\:'.  Beware that many environments process
 333 backslashes themselves, so it may be necessary to write two
 334 backslashes in order to one being passed onto rrd_graph.
 335
 336 =head2 String Formatting
 337
 338 The text printed below the actual graph can be formatted by appending special
 339 escape characters at the end of a text. When ever such a character occurs,
 340 all pending text is pushed onto the graph according to the character
 341 specified.
 342
 343 Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
 344 right aligned, and B<\c> for centered. In the next section there is an
 345 example showing how to use centered formatting.
 346
 347 B<\n> is a valid alias for B<\l> since incomplete parsing in earlier
 348 versions of rrdtool lead to this behaviour and a number of people has been using it.
 349
 350 Normally there are two space characters inserted between every two items
 351 printed into the graph. The space following a string can be suppressed by
 352 putting a B<\g> at the end of the string. The B<\g> also ignores any space
 353 inside the string if it is at the very end of the string. This can be used
 354 in connection with B<%s> to suppress empty unit strings.
 355
 356  GPRINT:a:MAX:%lf%s\g
 357
 358 A special case is COMMENT:B<\s> which inserts some additional vertical space
 359 before placing the next row of legends.
 360
 361 If you are using the proportional font in your graph, you can use tab
 362 characters or the sequence B<\t> to line-up legend elements. Note that
 363 the tabs inserted are relative to the start of the current legend
 364 element!
 365
 366 =head1 SEE ALSO
 367
 368 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
 369 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
 370 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
 371 L<rrdgraph_graph> page describes all of the graph and print functions.
 372
 373 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 374
 375 =head1 AUTHOR
 376
 377 Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 378
 379 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>