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