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