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