program/doc/rrdgraph_graph.src

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