doc/rrdgraph_graph.src

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