program/doc/rrdgraph_graph.src

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