program/doc/rrdgraph_graph.src

   1 =include name
   2
   3 =head1 SYNOPSIS
   4
   5 =over 4
   6
   7 =item B<old-style commands, for compatibility>
   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 Z<>
  22
  23 =item B<available commands>
  24
  25 =over 8
  26
  27 =item B<PRINT> : I<vname> : I<format>
  28
  29 =item B<GPRINT> : I<vname> : I<format>
  30
  31 =item B<COMMENT> : I<text>
  32
  33 =item B<VRULE> : I<vname> # I<color> [ : I<legend> ]
  34
  35 =item B<LINE>{I<width>} : I<vname> # I<color> [ : I<legend> ] [ C<:STACK> ]
  36
  37 =item B<AREA> C<:> I<vname> C<#> I<color> [ C<:> I<legend> ] [ C<:STACK> ]
  38
  39 =cut
  40
  41 # =item B<PART> : I<vname> B<#> I<rrggbbaa> [ B<:> I<legend> ]
  42
  43 =pod
  44
  45 =item B<TICK> : I<vname> B<#> I<rrggbbaa> [ : I<fraction> [ : I<legend> ] ]
  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 I<Deprecated. Use B<LINEx> in new scripts.>
 180
 181 =item B<VRULE> : I<vname> # I<color> [ : I<legend> ]
 182
 183 Draw a vertical line at I<time>.  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<time> may be a number or a variable
 187 from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
 188
 189 =item B<LINE>{I<width>} : I<{vname or number}> # I<color> [ : I<legend> ]
 190 [ C<:STACK> ]
 191
 192 Draw a line of the specified width into the graph. If the color
 193 is not specified, the drawing is done 'blind'.  This is useful when
 194 stacking something else on top of this line. Also optional is the
 195 legend box and string which will be printed in the legend section
 196 if specified. The B<vname> can be generated by B<DEF>, B<VDEF> and
 197 B<CDEF>.  If the optional B<STACK> modifier is used, this line is
 198 stacked on top of the previous element which can be a B<LINEx> or
 199 an B<AREA>
 200
 201 =item B<AREA> C<:> I<vname> C<#> I<color> [ C<:> I<legend> ] [ C<:STACK> ]
 202
 203 See B<LINE>, however the area between the x-axis and the line will
 204 also be filled.
 205
 206 =item B<TICK> : I<vname> B<#> I<rrggbbaa> [ : I<fraction> [ : I<legend> ] ]
 207
 208 Plot a tick mark (a vertical line) for each value of I<vname> that is
 209 non-zero and not *UNKNOWN*. The I<fraction> argument specifies the
 210 length of the tick mark as a fraction of the y-axis; the default value
 211 is 0.1 (10% of the axis). Note that the color specification is not
 212 optional.
 213
 214 =item B<SHIFT> : I<vname> : I<offset>
 215
 216 Using this command B<RRDtool> will graph the following elements
 217 with the specified offset.  For instance, you can specify an
 218 offset of S<( 7*24*60*60 = ) 604800 seconds> to "look back" one
 219 week. Make sure to notify the viewer you did so...
 220 As with the other graphing elements, you can specify a number or
 221 a variable here.
 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<STACK> : I<vname> # I<color> [ :I<legend> ]
 241
 242 I<Deprecated.  Use the B<STACK> modifiers on the other commands.>
 243
 244 =back
 245
 246 B<Some notes on stacking>
 247
 248 When stacking, an element is not placed above the X-axis but rather
 249 on top of the previous element.  There must be something to stack
 250 upon.
 251
 252 An B<invisible> LINEx or AREA B<is> present and can be stacked upon.
 253
 254 An B<unknown> value makes the entire stack unknown from that moment on.
 255 You don't know where to begin (the unknown value) and therefore do
 256 not know where to end.
 257
 258 If you want to make sure you will be displaying a certain variable,
 259 make sure never to stack upon the unknown value.  Use a CDEF instruction
 260 with B<IF> and B<UN> to do so.
 261
 262 =head1 NOTES on legend arguments
 263
 264 =head2 Escaping the colon
 265
 266 In a ':' in a I<legend> argument will mark the end of the legend. To
 267 enter a ':' into a legend, the colon must be escaped with a backslash '\:'.
 268 Beware, that many environments look for backslashes themselves, so it may
 269 be necessary to write two backslashes so that one is passed onto rrd_graph.
 270
 271 =head2 String Formatting
 272
 273 The text printed below the actual graph can be formated by appending special
 274 escaped characters at the end of a text. When ever such a character occurs,
 275 all pending text is pushed onto the graph according to the character
 276 specified.
 277
 278 Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
 279 right aligned and B<\c> for centered. In the next section there is an
 280 example showing how to use centered formating.
 281
 282 Normally there are two space characters inserted between every two items
 283 printed into the graph. The space following a string can be suppressed by
 284 putting a B<\g> at the end of the string. The B<\g> also ignores any space
 285 inside the string if it is at the very end of the string. This can be used
 286 in connection with B<%s> to suppress empty unit strings.
 287
 288  GPRINT:a:MAX:%lf%s\g
 289
 290 A special case is COMMENT:B<\s> this inserts some additional vertical space
 291 before placing the next row of legends.
 292
 293 If you are using the proportional font in your graph, you can use tab characters
 294 or the sequence B<\t> to lin-up legend elements. Note that the tabs inserted are
 295 relative to the start of the current legend element!
 296
 297 =include see_also