doc/rrdgraph_graph.src

   1 =include name
   2
   3 =head1 SYNOPSIS
   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 =cut
  38
  39 # =item B<PART> : I<vname> B<#> I<rrggbbaa> [ B<:> I<legend> ]
  40
  41 =pod
  42
  43 =item B<TICK> : I<vname> B<#> I<rrggbbaa> [ : I<fraction> [ : I<legend> ] ]
  44
  45 =back
  46
  47 =item B<to be implemented commands>
  48
  49 =over 8
  50
  51 =item B<SHIFT> : I<vname> , I<offset>
  52
  53 =back
  54
  55 =back
  56
  57 =head1 DESCRIPTION
  58
  59 These instructions allow you to generate your image or report.
  60 If you don't use any graph elements, no graph is generated.
  61 Similarly no report is generated if you don't use print options.
  62
  63 =head1 PRINT
  64
  65 =over 4
  66
  67 =item B<PRINT> : I<vname> : I<CF> : I<format>
  68
  69 I<Deprecated. Use the new form of this command in new scripts.>
  70 The first form of this command is to be used with B<CDEF> I<vname>s.
  71
  72 =item B<PRINT> : I<vname> : I<format>
  73
  74 Depending on the context, either the value component or the time
  75 component of a B<VDEF> is printed using I<format>. It is an error
  76 to specify a I<vname> generated by a B<DEF> or B<CDEF>.
  77
  78 Any text in I<format> is printed literally with one exception:
  79 The percent character introduces a formatter string. This string
  80 can be:
  81
  82 For printing values:
  83
  84 =over 4
  85
  86 =item *
  87
  88 B<%%> just prints a literal '%' character
  89
  90 =item *
  91
  92 B<%#.#le> prints like 1.2346e+04. Optional numbers # are field width and
  93 decimal precision
  94
  95 =item *
  96
  97 B<%#.#lf> prints like 12345.6789, with optional field width and precision
  98
  99 =item *
 100
 101 B<%s> place this after B<%le>, B<%lf> or B<%lg>. This will be replaced by the
 102 appropriate SI magnitude unit and the value will be scaled
 103 accordingly (123456 -> 123.456 k)
 104
 105 =item *
 106
 107 B<%S> is similar to B<%s>. It does however use a previously defined
 108 magnitude unit. If there is no such unit yet, it tries to define
 109 one (just like B<%s>). However, if the value is zero, the magnitude
 110 unit stays undefined. Thus, formatter strings using B<%S> and no B<%s>
 111 will all use the same magnitude unit except for zero values.
 112
 113 =back
 114
 115 For printing times:
 116
 117 =over 4
 118
 119 =item *
 120
 121 B<%%> just prints a literal '%' character
 122
 123 =item *
 124
 125 B<%a, %A> prints abbreviated, full weekday name
 126
 127 =item *
 128
 129 B<%b, %B> prints abbreviated, full month name
 130
 131 =item *
 132
 133 B<%d, %m, %y, %H, %M, %S> day,month,year,hour,minute,second all in two-digit format
 134
 135 =item *
 136
 137 B<%Y> year in 4-digit format
 138
 139 =item *
 140
 141 B<%I, %p>  hour (01..12), 'am' or 'pm'
 142
 143 =item *
 144
 145 B<%j, %w> day of the week (0..6), day of the year (1..366)
 146
 147 =item *
 148
 149 B<%c, %x, %X> date+time, date, time
 150
 151 =item *
 152
 153 B<%U, %W> week number of the current year with either the first Sunday or
 154 the first Monday determining the first week
 155
 156 =item *
 157
 158 B<%Z> time zone
 159
 160 =back
 161
 162 =back
 163
 164 =head1 GRAPH
 165
 166 =over 4
 167
 168 =item B<GPRINT> : I<vname> : I<CF> : I<format>
 169
 170 I<Deprecated. Use the new form of this command in new scripts.>
 171 This is the same as C<PRINT> but now it is printed inside the graph.
 172
 173 =item B<GPRINT> : I<vname> : I<format>
 174
 175 This is the same as C<PRINT> but now it is printed inside the graph.
 176
 177 =item B<COMMENT> : I<text>
 178
 179 Text is printed literally in the legend section of the graph
 180
 181 =item B<HRULE> : I<value> # I<color> [ :I<legend> ]
 182
 183 Draw an horizontal line at I<value>. Its color is composed from three
 184 hexadecimal numbers specifying the color components (00 is off, FF is
 185 maximum) red, green and blue.  Optionally a legend box and string is
 186 printed in the legend section. I<value> can be a variable from a B<VDEF>.
 187 It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
 188
 189 =item B<VRULE> : I<vname> # I<color> [ : I<legend> ]
 190
 191 Draw a vertical line at I<time>.  Its color is composed from three
 192 hexadecimal numbers specifying the color components (00 is off, FF is
 193 maximum) red, green and blue.  Optionally a legend box and string is
 194 printed in the legend section. I<time> may be a number or a variable
 195 from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
 196
 197 =item B<LINE>{I<width>} : I<vname> # I<color> [ : I<legend> ] [ : STACK ]
 198
 199 Draw a line of the specified width into the graph. If the color
 200 is not specified, the drawing is done 'blind'.  This is useful when
 201 stacking something else on top of this line. Also optional is the
 202 legend box and string which will be printed in the legend section
 203 if specified. The B<vname> can be generated by B<DEF>, B<VDEF> and
 204 B<CDEF>.  If the optional B<STACK> modifier is used, this line is
 205 stacked on top of the previous element which can be a B<LINEx> or
 206 an B<AREA>
 207
 208 =item B<AREA> C<:> I<vname> C<#> I<color> [ C<:> I<legend> ] [ C<:> C<STACK> ]
 209
 210 See B<LINE>, however the area between the x-axis and the line will
 211 also be filled.
 212
 213 =item B<STACK> : I<vname> # I<color> [ :I<legend> ]
 214
 215 I<Deprecated.  Use the B<STACK> modifiers on the other commands.>
 216 I<Note: the comments on stacking are still valid...>
 217 Repeats the last B<LINEx> or B<AREA> however it doesn't start at the
 218 x-axis but rather on top of the previous element. This implies that
 219 there needs to be something to stack on. An invisible B<LINEx> or
 220 B<AREA> is something you can stack on, an unknown value is not!
 221
 222 Note: When you stack on something that was I<unknown>, the whole
 223 stack will be I<unknown> for that point in time. If the beginning
 224 is undefined, there's no way to end somewhere...  If you want to
 225 graph this stacked variable anyway you need to make sure that the
 226 B<LINEx> or B<AREA> it gets stacked on is not unknown. Use a CDEF
 227 instruction with B<IF> and B<UN> to do so.
 228
 229 =cut
 230
 231 #=item B<PART> : I<vname> B<#> I<rrggbbaa> [ B<:> I<legend> ]
 232 #
 233 #B<RRDtool> has now support for B<pie charts>. If you include the
 234 #B<PART> command, the canvas is extended to make room for a chart
 235 #The size of the canvas is determined by the lesser of
 236 #L<width and height|rrdgraph/item_Size>.
 237 #
 238 #Pie parts will be concatenated, the first one will start at the
 239 #top and parts will be created clockwise.  The size of the part
 240 #is defined by the value part of the L<VDEF|rrdgraph_data/VDEF>
 241 #function.  It should return a number between 0 and 100, being a
 242 #percentage.  Providing wrong input will produce undefined results.
 243
 244 =pod
 245
 246 =item B<TICK> : I<vname> B<#> I<rrggbbaa> [ : I<fraction> [ : I<legend> ] ]
 247
 248 Plot a tick mark (a vertical line) for each value of I<vname> that is
 249 non-zero and not *UNKNOWN*. The I<fraction> argument specifies the
 250 length of the tick mark as a fraction of the y-axis; the default value
 251 is 0.1 (10% of the axis). Note that the color specification is not
 252 optional.
 253
 254 =item B<SHIFT> : I<vname> , I<offset>
 255
 256 Using this command B<RRDtool> will graph the following elements
 257 with the specified offset.  For instance, you can specify an
 258 offset of S<( 7*24*60*60 = ) 604800 seconds> to "look back" one
 259 week. Make sure to notify the viewer you did so...
 260 The offset will be valid until the next B<SHIFT> command, which
 261 can have an offset of zero to restore normal graphing.
 262 As with the other graphing elements, you can specify a number or
 263 a variable here.
 264
 265 =back
 266
 267 =head1 NOTES on legend arguments
 268
 269 =head2 Escaping the colon
 270
 271 In a ':' in a I<legend> argument will mark the end of the legend. To
 272 enter a ':' into a legend, the colon must be escaped with a backslash '\:'.
 273 Beware, that many environments look for backslashes themselves, so it may
 274 be necessary to write two backslashes so that one is passed onto rrd_graph.
 275
 276 =head2 String Formatting
 277
 278 The text printed below the actual graph can be formated by appending special
 279 escaped characters at the end of a text. When ever such a character occurs,
 280 all pending text is pushed onto the graph according to the character
 281 specified.
 282
 283 Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
 284 right aligned and B<\c> for centered. In the next section there is an
 285 example showing how to use centered formating.
 286
 287 Normally there are two space characters inserted between every two items
 288 printed into the graph. The space following a string can be suppressed by
 289 putting a B<\g> at the end of the string. The B<\g> also ignores any space
 290 inside the string if it is at the very end of the string. This can be used
 291 in connection with B<%s> to suppress empty unit strings.
 292
 293  GPRINT:a:MAX:%lf%s\g
 294
 295 A special case is COMMENT:B<\s> this inserts some additional vertical space
 296 before placing the next row of legends.
 297
 298 If you are using the proportional font in your graph, you can use tab characters
 299 or the sequence B<\t> to lin-up legend elements. Note that the tabs inserted are
 300 relative to the start of the current legend element!
 301
 302 =include see_also