doc/rrdgraph_graph.src

   1 =include name
   2
   3 =head1 SYNOPSYS
   4
   5 I<(to be) Depriciated commands>
   6
   7 [B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>]
   8 [B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>]
   9 [B<HRULE:>I<value>B<#>I<rrggbbaa>[B<:>I<legend>]]
  10 [B<STACK:>I<vname>[B<#>I<rrggbbaa>[B<:>I<legend>]]]
  11
  12 I<(soon) available commands>
  13
  14 [B<PRINT:>I<vname>B<:>I<format>]
  15 [B<GPRINT:>I<vname>B<:>I<format>]
  16 [B<COMMENT:>I<text>]
  17 [B<VRULE:>I<vname>B<#>I<rrggbbaa>[B<:>I<legend>]]
  18 [B<LINE>{I<width>}B<:>I<vname>[B<#>I<rrggbbaa>[B<:>I<legend>]]][B<:STACK>]
  19 [B<AREA:>I<vname>[B<#>I<rrggbbaa>[B<:>I<legend>]]][B<:STACK>]
  20 [B<PART:>I<vname>B<#>I<rrggbbaa>[B<:>I<legend>]]
  21
  22 I<to be implemented commands>
  23
  24 [B<SHIFT:>I<vname>]
  25
  26 =head1 DESCRIPTION
  27
  28 These instructions allow you to generate your image or report.
  29 If you don't use any graph elements, no graph is generated.
  30 Similarly no report is generated if you don't use print options.
  31
  32 =head1 PRINT
  33
  34 B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>
  35
  36 I<Depriciated. Use the new form of this command in new scripts.>
  37 The first form of this command is to be used with B<CDEF> I<vname>s.
  38
  39 B<PRINT:>I<vname>B<:>I<format>
  40
  41 Depending on the context, either the value component or the time
  42 component of a B<VDEF> is printed using I<format>. It is an error
  43 to specify a I<vname> generated by a B<DEF> or B<CDEF>.
  44
  45 Any text in I<format> is printed literally with one exception:
  46 The percent character introduces a formatter string. This string
  47 can be:
  48
  49 For printing values:
  50
  51 =over 4
  52
  53 =item *
  54
  55 B<%%> just prints a literal '%' character
  56
  57 =item *
  58
  59 B<%#.#le> (where # is an optional number) prints like 1.2346e+04
  60
  61 =item *
  62
  63 B<%#.#lf> prints like 12345.6789
  64
  65 =item *
  66
  67 B<%s> place this after B<%le> or B<%lf>.  This will be replaced by the
  68 appropriate SI magnitude unit and the value will be scaled
  69 accordingly (123456 -> 123.456 k)
  70
  71 =item *
  72
  73 B<%S> is similar to B<%s>. It does however use a previously defined
  74 magnitude unit. If there is no such unit yet, it tries to define
  75 one (just like B<%s>). However, if the value is zero, the magnitude
  76 unit stays undefined. Thus, formatter strings using B<%S> and no B<%s>
  77 will all use the same magnitude unit except for zero values.
  78
  79 =back
  80
  81 For printing times:
  82
  83 =over 4
  84
  85 =item *
  86
  87 B<%%> just prints a literal '%' character
  88
  89 =item *
  90
  91 B<%a, %A> prints abbreviated, full weekday name
  92
  93 =item *
  94
  95 B<%b, %B> prints abbreviated, full month name
  96
  97 =item *
  98
  99 B<%d, %m, %y, %H, %M, %S> day,month,year,hour,minute,second all in two-digit format
 100
 101 =item *
 102
 103 B<%Y> year in 4-digit format
 104
 105 =item *
 106
 107 B<%I, %p>  hour (01..12), 'am' or 'pm'
 108
 109 =item *
 110
 111 B<%j, %w> day of the week (0..6), day of the year (1..366)
 112
 113 =item *
 114
 115 B<%c, %x, %X> date+time, date, time
 116
 117 =item *
 118
 119 B<%U, %W> week number of the current year with either the first sunday or
 120 the first monday determining the first week
 121
 122 =item *
 123
 124 B<%Z> time zone
 125
 126 =back
 127
 128 =head1 GRAPH
 129
 130 B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>
 131
 132 I<Depriciated. Use the new form of this command in new scripts.>
 133 This is the same as B<PRINT> but now it is printed inside the graph.
 134 See L<PRINT> for more information.
 135
 136 B<GPRINT:>I<vname>B<:>I<format>
 137
 138 This is the same as B<PRINT> but now it is printed inside the graph.
 139 See L<PRINT> for more information.
 140
 141 B<COMMENT:>I<text>
 142
 143 Text is printed literally in the legend section of the graph
 144
 145 B<HRULE:>I<value>B<#>I<rrggbbaa>[B<:>I<legend>]
 146
 147 Draw an horizontal line at I<value>. Its color is composed from three
 148 hexadecimal numbers specifying the color components (00 is off, FF is
 149 maximum) red, green and blue.  Optionally a legend box and string is
 150 printed in the legend section. I<value> can be a variable from a B<VDEF>.
 151 It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
 152
 153 B<VRULE:>I<time>B<#>I<rrggbbaa>[B<:>I<legend>]
 154
 155 Draw a vertical line at I<time>.  Its color is composed from three
 156 hexadecimal numbers specifying the color components (00 is off, FF is
 157 maximum) red, green and blue.  Optionally a legend box and string is
 158 printed in the legend section. I<time> may be a number or a variable
 159 from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
 160
 161 B<LINE>{I<width>}B<:>I<vname>[B<#>I<rrggbbaa>[B<:>I<legend>]][B<:STACK>]
 162
 163 Draw a line of the specified width into the graph. If the color
 164 is not specified, the drawing is done 'blind'.  This is useful when
 165 stacking something else on top of this line. Also optional is the
 166 legend box and string which will be printed in the legend section
 167 if specified. The B<vname> can be generated by B<DEF>, B<VDEF> and
 168 B<CDEF>.  If the optional B<STACK> modifier is used, this line is
 169 stacked on top of the previous element which can be a B<LINEx> or
 170 an B<AREA>
 171
 172 B<AREA:>I<vname>[B<#>I<rrggbbaa>[B<:>I<legend>]][B<:STACK>]
 173
 174 See B<LINEx>, however the area between the x-axis and the line will
 175 also be filled.
 176
 177 B<STACK:>I<vname>[B<#>I<rrggbbaa>[B<:>I<legend>]]
 178
 179 I<Depriciated.  Use the B<STACK> modifiers on the other commands.>
 180 I<Note: the comments on stacking are still valid...>
 181 Repeats the last B<LINEx> or B<AREA> however it doesn't start at the
 182 x-axis but rather on top of the previous element. This implies that
 183 there needs to be something to stack on. An invisible B<LINEx> or
 184 B<AREA> is something you can stack on!
 185
 186 Note: When you stack on something that was I<unknown>, the whole
 187 stack will be I<unknown> for that point in time. If the beginning
 188 is undefined, there's no way to end somewhere...  If you want to
 189 graph this stacked variable anyway you need to make sure that the
 190 B<LINEx> or B<AREA> it gets stacked on is not unknown. Use a CDEF
 191 instruction with B<IF> and B<UN> to do so.
 192
 193 B<PART:>I<vname>B<#>I<rrggbbaa>[B<:>I<legend>]
 194
 195 B<RRDtool> has now support for B<pie charts>. If you include the
 196 B<PART> command, the canvas is extended to make room for a chart
 197 The size of the canvas is determined by the lesser of
 198 L<width and height|rrdgraph/item_Size>.
 199
 200 Pie parts will be concatenated, the first one will start at the
 201 top and parts will be created clockwise.  The size of the part
 202 is defined by the value part of the L<VDEF|rrdgraph_data/VDEF>
 203 function.  It should return a number between 0 and 100, being a
 204 percentage.  Providing wrong input will produce undefined results.
 205
 206 B<THE NEXT STUFF IS NOT YET IMPLEMENTED>
 207
 208 B<SHIFT:>I<offset in seconds>
 209
 210 Using this command B<RRDtool> will graph the following elements
 211 with the specified offset.  For instance, you can specify an
 212 offset of S<( 7*24*60*60 = ) 604800 seconds> to "look back" one
 213 week. Make sure to notify the viewer you did so...
 214 The offset will be valid until the next B<SHIFT> command, which
 215 can have an offset of zero to restore normal graphing.
 216 As with the other grapher elements, you can specify a number or
 217 a variable here.
 218
 219 =include see_also