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