doc/rrdgraph_graph.pod

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