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>
  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 *
  68
  69 B<%%> just prints a literal '%' character
  70
  71 =item *
  72
  73 B<%#.#le> prints numbers like 1.2346e+04. The optional integers # denote field
  74 width and decimal precision.
  75
  76 =item *
  77
  78 B<%#.#lf> prints numbers like 12345.6789, with optional field width
  79 and precision.
  80
  81 =item *
  82
  83 B<%s> 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 *
  88
  89 B<%S> 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 For printing times:
  98
  99 =over 4
 100
 101 =item *
 102
 103 B<%%> just prints a literal '%' character
 104
 105 =item *
 106
 107 B<%a, %A> print the abbreviated or full name of the day of the week.
 108
 109 =item *
 110
 111 B<%b, %B> print the abbreviated or full name of the month.
 112
 113 =item *
 114
 115 B<%d, %m, %y, %H, %M, %S> print day, month, year, hour, minute, and
 116 second in two-digit format.
 117
 118 =item *
 119
 120 B<%Y> prints the year in 4-digit format.
 121
 122 =item *
 123
 124 B<%I, %p> print the hour (01..12), 'am' or 'pm'.
 125
 126 =item *
 127
 128 B<%j, %w> print day of the week (0..6), day of the year (1..366)
 129
 130 =item *
 131
 132 B<%c, %x, %X> print date+time, date only, time only.
 133
 134 =item *
 135
 136 B<%U, %W> number of the week of the current year, with either the
 137 first Sunday (%U) or the first Monday (%W) determining the first week.
 138
 139 =item *
 140
 141 B<%Z> prints the time zone.
 142
 143 =back
 144
 145 =item B<PRINT:>I<vname>B<:>I<CF><:>I<format>
 146
 147 I<Deprecated. Use the new form of this command in new scripts.>
 148 The first form of this command is to be used with B<CDEF> I<vname>s.
 149
 150 =back
 151
 152 =head1 GRAPH
 153
 154 =over 4
 155
 156 =item B<GPRINT>B<:>I<vname>B<:>I<format>
 157
 158 This is the same as C<PRINT>, but printed inside the graph.
 159
 160 =item B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format>
 161
 162 I<Deprecated. Use the new form of this command in new scripts.>
 163 This is the same as C<PRINT>, but printed inside the graph.
 164
 165 =item B<COMMENT>B<:>I<text>
 166
 167 Text is printed literally in the legend section of the graph. Note that in
 168 RRDtool 1.2 you have to escape colons in COMMENT text in the same way you
 169 have to escape them in B<*PRINT> commands by writing B<'\:'>.
 170
 171 =item B<VRULE>B<:>I<time>B<#>I<color> [B<:>I<legend> ]
 172
 173 Draw a vertical line at I<time>.  Its color is composed from three
 174 hexadecimal numbers specifying the rgb color components (00 is off, FF is
 175 maximum) red, green and blue followed by an optional alpha. Optionally, a legend box and string is
 176 printed in the legend section. I<time> may be a number or a variable
 177 from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
 178
 179 =item B<HRULE>B<:>I<value>B<#>I<color> [ :I<legend> ]
 180
 181 Draw a horyzontal line at I<value>.  HRULE acts much like LINE except that
 182 will have no effect on the scale of the graph. If a HRULE is outside the
 183 graphing area it will just not be visible.
 184
 185 =item B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
 186
 187 Draw a line of the specified width onto the graph. I<width> can be a
 188 floating point number. If the color is not specified, the drawing is done
 189 'invisibly'. This is useful when stacking something else on top of this
 190 line. Also optional is the legend box and string which will be printed in
 191 the legend section if specified. The B<value> can be generated by B<DEF>,
 192 B<VDEF>, and B<CDEF>.  If the optional B<STACK> modifier is used, this line
 193 is stacked on top of the previous element which can be a B<LINE> or an
 194 B<AREA>.
 195
 196 When you do not specify a color, you cannot specify a legend.  Should
 197 you want to use STACK, use the "LINEx:<value>::STACK" form.
 198
 199 =item B<AREA>B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
 200
 201 See B<LINE>, however the area between the x-axis and the line will
 202 be filled.
 203
 204 =item B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
 205
 206 Plot a tick mark (a vertical line) for each value of I<vname> that is
 207 non-zero and not *UNKNOWN*. The I<fraction> argument specifies the length of
 208 the tick mark as a fraction of the y-axis; the default value is 0.1 (10% of
 209 the axis). Note that the color specification is not optional. The TICK marks normaly
 210 start at the lower edge of the graphing area. If the fraction is negative they start
 211 at the upper border of the graphing area.
 212
 213 =item B<SHIFT>B<:>I<vname>B<:>I<offset>
 214
 215 Using this command B<RRDtool> will graph the following elements
 216 with the specified offset.  For instance, you can specify an
 217 offset of S<( 7*24*60*60 = ) 604'800 seconds> to "look back" one
 218 week. Make sure to tell the viewer of your graph you did this ...
 219 As with the other graphing elements, you can specify a number or
 220 a variable here.
 221
 222 =cut
 223
 224 # This section describes the curruently defunct
 225 # PieChart code.
 226 #
 227 # =item B<PART>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<legend>]
 228 #
 229 # B<RRDtool> has now support for B<pie charts>. If you include the
 230 # B<PART> command, the canvas is extended to make room for a chart.
 231 # The size of the canvas is determined by the lesser of
 232 # L<width and height|rrdgraph/item_Size>.
 233 #
 234 # Pie parts will be concatenated, the first one will start at the
 235 # top and parts will be created clockwise.  The size of the part
 236 # is defined by the value part of the L<VDEF|rrdgraph_data/VDEF>
 237 # function.  It should return a number between 0 and 100, being a
 238 # percentage.  Providing wrong input will produce undefined results.
 239 #
 240 #
 241
 242 =pod
 243
 244 =item B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>]
 245
 246 I<Deprecated.  Use the B<STACK> modifiers on the other commands.>
 247
 248 =back
 249
 250 B<Some notes on stacking>
 251
 252 When stacking, an element is not placed above the X-axis but rather
 253 on top of the previous element.  There must be something to stack
 254 upon.
 255
 256 You can use an B<invisible> LINE or AREA to stacked upon.
 257
 258 An B<unknown> value makes the entire stack unknown from that moment on.
 259 You don't know where to begin (the unknown value) and therefore do
 260 not know where to end.
 261
 262 If you want to make sure you will be displaying a certain variable,
 263 make sure never to stack upon the unknown value.  Use a CDEF instruction
 264 with B<IF> and B<UN> to do so.
 265
 266 =head1 NOTES on legend arguments
 267
 268 =head2 Escaping the colon
 269
 270 A colon ':' in a I<legend> argument will mark the end of the
 271 legend. To enter a ':' as part of a legend, the colon must be escaped
 272 with a backslash '\:'.  Beware that many environments process
 273 backslashes themselves, so it may be necessary to write two
 274 backslashes in order to one being passed onto rrd_graph.
 275
 276 =head2 String Formatting
 277
 278 The text printed below the actual graph can be formatted by appending special
 279 escape characters at the end of a text. When ever such a character occurs,
 280 all pending text is pushed onto the graph according to the character
 281 specified.
 282
 283 Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
 284 right aligned, and B<\c> for centered. In the next section there is an
 285 example showing how to use centered formatting.
 286
 287 Normally there are two space characters inserted between every two items
 288 printed into the graph. The space following a string can be suppressed by
 289 putting a B<\g> at the end of the string. The B<\g> also ignores any space
 290 inside the string if it is at the very end of the string. This can be used
 291 in connection with B<%s> to suppress empty unit strings.
 292
 293  GPRINT:a:MAX:%lf%s\g
 294
 295 A special case is COMMENT:B<\s> which inserts some additional vertical space
 296 before placing the next row of legends.
 297
 298 If you are using the proportional font in your graph, you can use tab
 299 characters or the sequence B<\t> to line-up legend elements. Note that
 300 the tabs inserted are relative to the start of the current legend
 301 element!
 302
 303 =head1 SEE ALSO
 304
 305 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
 306 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
 307 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
 308 L<rrdgraph_graph> page describes all of the graph and print functions.
 309
 310 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 311
 312 =head1 AUTHOR
 313
 314 Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 315
 316 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>