doc/rrdgraph_graph.pod

   1 =head1 NAME
   2
   3 rrdtool graph - Round Robin Database tool grapher functions
   4
   5 WARNING: This is for version 1.1.x which is B<I<BETA>> software.
   6 The software may contain serious bugs. Some of the items
   7 described in here may not yet exist (although this should
   8 be mentioned) or still be in the alpha stage.  As with every
   9 other RRDtool release: use at your own risk.  In contrast with
  10 the stable version of RRDtool, this release may contain bugs
  11 known to the authors.  It is highly recommended that you subscribe
  12 to the mailing list.
  13
  14 =head1 SYNOPSYS
  15
  16 I<(to be) Depriciated commands>
  17
  18 [B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>]
  19 [B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>]
  20 [B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]]
  21 [B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]
  22
  23 I<(soon) available commands>
  24
  25 [B<PRINT:>I<vname>B<:>I<format>]
  26 [B<GPRINT:>I<vname>B<:>I<format>]
  27 [B<COMMENT:>I<text>]
  28 [B<VRULE:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]]
  29 [B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]][B<:STACK>]
  30 [B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]][B<:STACK>]
  31
  32 I<to be implemented commands>
  33
  34 [B<SHIFT:>I<vname>]
  35 [B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]]
  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 B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>
  46
  47 I<Depriciated. Use the new form of this command in new scripts.>
  48 The first form of this command is to be used with B<CDEF> I<vname>s.
  49
  50 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> (where # is an optional number) prints like 1.2346e+04
  71
  72 =item *
  73
  74 B<%#.#lf> prints like 12345.6789
  75
  76 =item *
  77
  78 B<%s> place this after B<%le> or B<%lf>.  This will be replaced by the
  79 appropriate SI magnitude unit and the value will be scaled
  80 accordingly (123456 -> 123.456 k)
  81
  82 =item *
  83
  84 B<%S> is similar to B<%s>. It does however use a previously defined
  85 magnitude unit. If there is no such unit yet, it tries to define
  86 one (just like B<%s>). However, if the value is zero, the magnitude
  87 unit stays undefined. Thus, formatter strings using B<%S> and no B<%s>
  88 will all use the same magnitude unit except for zero values.
  89
  90 =back
  91
  92 For printing times:
  93
  94 =over 4
  95
  96 =item *
  97
  98 B<%%> just prints a literal '%' character
  99
 100 =item *
 101
 102 B<%a, %A> prints abbreviated, full weekday name
 103
 104 =item *
 105
 106 B<%b, %B> prints abbreviated, full month name
 107
 108 =item *
 109
 110 B<%d, %m, %y, %H, %M, %S> day,month,year,hour,minute,second all in two-digit format
 111
 112 =item *
 113
 114 B<%Y> year in 4-digit format
 115
 116 =item *
 117
 118 B<%I, %p>  hour (01..12), 'am' or 'pm'
 119
 120 =item *
 121
 122 B<%j, %w> day of the week (0..6), day of the year (1..366)
 123
 124 =item *
 125
 126 B<%c, %x, %X> date+time, date, time
 127
 128 =item *
 129
 130 B<%U, %W> week number of the current year with either the first sunday or
 131 the first monday determining the first week
 132
 133 =item *
 134
 135 B<%Z> time zone
 136
 137 =back
 138
 139 =head1 GRAPH
 140
 141 B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>
 142
 143 I<Depriciated. Use the new form of this command in new scripts.>
 144 This is the same as B<PRINT> but now it is printed inside the graph.
 145 See L<PRINT> for more information.
 146
 147 B<GPRINT:>I<vname>B<:>I<format>
 148
 149 This is the same as B<PRINT> but now it is printed inside the graph.
 150 See L<PRINT> for more information.
 151
 152 B<COMMENT:>I<text>
 153
 154 Text is printed literally in the legend section of the graph
 155
 156 B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]
 157
 158 Draw an horizontal line at I<value>. Its color is composed from three
 159 hexadecimal numbers specifying the color components (00 is off, FF is
 160 maximum) red, green and blue.  Optionally a legend box and string is
 161 printed in the legend section. I<value> can be a variable from a B<VDEF>.
 162 It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
 163
 164 B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]
 165
 166 Draw a vertical line at I<time>.  Its color is composed from three
 167 hexadecimal numbers specifying the color components (00 is off, FF is
 168 maximum) red, green and blue.  Optionally a legend box and string is
 169 printed in the legend section. I<time> may be a number or a variable
 170 from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
 171
 172 B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>]
 173
 174 Draw a line of the specified width into the graph. If the color
 175 is not specified, the drawing is done 'blind'.  This is useful when
 176 stacking something else on top of this line. Also optional is the
 177 legend box and string which will be printed in the legend section
 178 if specified. The B<vname> can be generated by B<DEF>, B<VDEF> and
 179 B<CDEF>.  If the optional B<STACK> modifier is used, this line is
 180 stacked on top of the previous element which can be a B<LINEx> or
 181 an B<AREA>
 182
 183 B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>]
 184
 185 See B<LINEx>, however the area between the x-axis and the line will
 186 also be filled.
 187
 188 B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
 189
 190 I<Depriciated.  Use the B<STACK> modifiers on the other commands.>
 191 I<Note: the comments on stacking are still valid...>
 192 Repeats the last B<LINEx> or B<AREA> however it doesn't start at the
 193 x-axis but rather on top of the previous element. This implies that
 194 there needs to be something to stack on. An invisible B<LINEx> or
 195 B<AREA> is something you can stack on!
 196
 197 Note: When you stack on something that was I<unknown>, the whole
 198 stack will be I<unknown> for that point in time. If the beginning
 199 is undefined, there's no way to end somewhere...  If you want to
 200 graph this stacked variable anyway you need to make sure that the
 201 B<LINEx> or B<AREA> it gets stacked on is not unknown. Use a CDEF
 202 instruction with B<IF> and B<UN> to do so.
 203
 204 B<THE NEXT STUFF IS NOT YET IMPLEMENTED>
 205
 206 B<SHIFT:>I<offset in seconds>
 207
 208 Using this command B<RRDtool> will graph the following elements
 209 with the specified offset.  For instance, you can specify an
 210 offset of S<( 7*24*60*60 = ) 604800 seconds> to "look back" one
 211 week. Make sure to notify the viewer you did so...
 212 The offset will be valid until the next B<SHIFT> command, which
 213 can have an offset of zero to restore normal graphing.
 214 As with the other grapher elements, you can specify a number or
 215 a variable here.
 216
 217 B<RRDtool> has now support for B<pie charts>. If you include the
 218 B<PART> command, the canvas is extended to make room for a chart
 219 (or, if no other graph elements are used, the canvas is solely
 220 used for the pie chart). The size of the canvas is determined by
 221 the lesser of L<width and height|rrdgraph/item_Size>.
 222
 223 B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]
 224
 225 Draw a part of pie. Pie parts will be concatenated, the first one
 226 will start at the top and parts will be created clockwise.
 227 The size of the part is defined by the value part of
 228 the L<VDEF|rrdgraph_data/VDEF> function.  It should return
 229 a number between 0 and 100, being a percentage.
 230 Providing wrong input will produce undefined results.
 231
 232 =head1 SEE ALSO
 233
 234 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
 235 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
 236 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
 237 L<rrdgraph_graph> page describes all of the graph and print functions.
 238
 239 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 240
 241 =head1 AUTHOR
 242
 243 Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
 244
 245 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>