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<Soon 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<Soon 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 I<Soon depriciated. Use a VDEF and a LINEx in new scripts.>
 159
 160 Draw an horizontal line at I<value>. Its color is composed from three
 161 hexadecimal numbers specifying the color components (00 is off, FF is
 162 maximum) red, green and blue.  Optionally a legend box and string is
 163 printed in the legend section.
 164
 165 B<VRULE:>I<time>B<#>I<rrggbb>[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 B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>]
 174
 175 Draw a line of the specified width into the graph. If the color
 176 is not specified, the drawing is done 'blind'.  This is useful when
 177 stacking something else on top of this line. Also optional is the
 178 legend box and string which will be printed in the legend section
 179 if specified. The B<vname> can be generated by B<DEF>, B<VDEF> and
 180 B<CDEF>.  If the optional B<STACK> modifier is used, this line is
 181 stacked on top of the previous element which can be a B<LINEx> or
 182 an B<AREA>
 183
 184 B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>]
 185
 186 See B<LINEx>, however the area between the x-axis and the line will
 187 also be filled.
 188
 189 B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
 190
 191 I<Depriciated.  Use the B<STACK> modifiers on the other commands.>
 192 I<Note: the comments on stacking are still valid...>
 193 Repeats the last B<LINEx> or B<AREA> however it doesn't start at the
 194 x-axis but rather on top of the previous element. This implies that
 195 there needs to be something to stack on. An invisible B<LINEx> or
 196 B<AREA> is something you can stack on!
 197
 198 Note: When you stack on something that was I<unknown>, the whole
 199 stack will be I<unknown> for that point in time. If the beginning
 200 is undefined, there's no way to end somewhere...  If you want to
 201 graph this stacked variable anyway you need to make sure that the
 202 B<LINEx> or B<AREA> it gets stacked on is not unknown. Use a CDEF
 203 instruction with B<IF> and B<UN> to do so.
 204
 205 B<THE NEXT STUFF IS NOT YET IMPLEMENTED>
 206
 207 B<SHIFT:>I<offset in seconds>
 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 = ) 604800 seconds> to "look back" one
 212 week. Make sure to notify the viewer you did so...
 213 The offset will be valid until the next B<SHIFT> command, which
 214 can have an offset of zero to restore normal graphing.
 215 As with the other grapher elements, you can specify a number or
 216 a variable here.
 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 (or, if no other graph elements are used, the canvas is solely
 221 used for the pie chart). The size of the canvas is determined by
 222 the lesser of L<width and height|rrdgraph/item_Size>.
 223
 224 B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]
 225
 226 Draw a part of pie. Pie parts will be concatenated, the first one
 227 will start at the top and parts will be created clockwise.
 228 The size of the part is defined by the value part of
 229 the L<VDEF|rrdgraph_data/VDEF> function.  It should return
 230 a number between 0 and 100, being a percentage.
 231 Providing wrong input will produce undefined results.
 232
 233 =head1 SEE ALSO
 234
 235 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
 236 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
 237 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
 238 L<rrdgraph_graph> page describes all of the graph and print functions.
 239
 240 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 241
 242 =head1 AUTHOR
 243
 244 Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
 245
 246 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>