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