doc/rrdgraph_graph.src

   1 =include name
   2
   3 =head1 SYNOPSYS
   4
   5 I<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<rrggbb>[B<:>I<legend>]]
  10 [B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]
  11
  12 I<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<rrggbb>[B<:>I<legend>]]
  18 [B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]][B<:STACK>]
  19 [B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]][B<:STACK>]
  20
  21 I<to be implemented commands>
  22
  23 [B<SHIFT:>I<vname>]
  24 [B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]]
  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<rrggbb>[B<:>I<legend>]
 146
 147 I<Depriciated. Use a VDEF and a LINEx in new scripts.>
 148
 149 Draw an horizontal line at I<value>. Its color is composed from three
 150 hexadecimal numbers specifying the color components (00 is off, FF is
 151 maximum) red, green and blue.  Optionally a legend box and string is
 152 printed in the legend section.
 153
 154 B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]
 155
 156 Draw a vertical line at I<time>.  Its color is composed from three
 157 hexadecimal numbers specifying the color components (00 is off, FF is
 158 maximum) red, green and blue.  Optionally a legend box and string is
 159 printed in the legend section. I<time> may be a number or a variable
 160 from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
 161
 162 B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>]
 163
 164 Draw a line of the specified width into the graph. If the color
 165 is not specified, the drawing is done 'blind'.  This is useful when
 166 stacking something else on top of this line. Also optional is the
 167 legend box and string which will be printed in the legend section
 168 if specified. The B<vname> can be generated by B<DEF>, B<VDEF> and
 169 B<CDEF>.  If the optional B<STACK> modifier is used, this line is
 170 stacked on top of the previous element which can be a B<LINEx> or
 171 an B<AREA>
 172
 173 B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>]
 174
 175 See B<LINEx>, however the area between the x-axis and the line will
 176 also be filled.
 177
 178 B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
 179
 180 I<Depriciated.  Use the B<STACK> modifiers on the other commands.>
 181 I<Note: the comments on stacking are still valid...>
 182 Repeats the last B<LINEx> or B<AREA> however it doesn't start at the
 183 x-axis but rather on top of the previous element. This implies that
 184 there needs to be something to stack on. An invisible B<LINEx> or
 185 B<AREA> is something you can stack on!
 186
 187 Note: When you stack on something that was I<unknown>, the whole
 188 stack will be I<unknown> for that point in time. If the beginning
 189 is undefined, there's no way to end somewhere...  If you want to
 190 graph this stacked variable anyway you need to make sure that the
 191 B<LINEx> or B<AREA> it gets stacked on is not unknown. Use a CDEF
 192 instruction with B<IF> and B<UN> to do so.
 193
 194 B<THE NEXT STUFF IS NOT YET IMPLEMENTED>
 195
 196 B<SHIFT:>I<offset in seconds>
 197
 198 Using this command B<RRDtool> will graph the following elements
 199 with the specified offset.  For instance, you can specify an
 200 offset of S<( 7*24*60*60 = ) 604800 seconds> to "look back" one
 201 week. Make sure to notify the viewer you did so...
 202 The offset will be valid until the next B<SHIFT> command, which
 203 can have an offset of zero to restore normal graphing.
 204 As with the other grapher elements, you can specify a number or
 205 a variable here.
 206
 207 B<RRDtool> has now support for B<pie charts>. If you include the
 208 B<PART> command, the canvas is extended to make room for a chart
 209 (or, if no other graph elements are used, the canvas is solely
 210 used for the pie chart). The size of the canvas is determined by
 211 the lesser of L<width and height|rrdgraph/item_Size>.
 212
 213 B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]
 214
 215 Draw a part of pie. Pie parts will be concatenated, the first one
 216 will start at the top and parts will be created clockwise.
 217 The size of the part is defined by the value part of
 218 the L<VDEF|rrdgraph_data/VDEF> function.  It should return
 219 a number between 0 and 100, being a percentage.
 220 Providing wrong input will produce undefined results.
 221
 222 =include see_also