doc/rrdgraph_graph.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 rrdgraph_graph - rrdtool graph command reference
   6
   7 =head1 SYNOPSIS
   8
   9 B<PRINT>B<:>I<vname>B<:>I<format>
  10
  11 B<GPRINT>B<:>I<vname>B<:>I<format>
  12
  13 B<COMMENT>B<:>I<text>
  14
  15 B<VRULE>B<:>I<time>B<#>I<color>[B<:>I<legend>]
  16
  17 B<HRULE>B<:>I<value>B<#>I<color>[B<:>I<legend>]
  18
  19 B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
  20
  21 B<AREA>B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
  22
  23 B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
  24
  25 B<SHIFT>B<:>I<vname>B<:>I<offset>
  26
  27 B<PRINT>B<:>I<vname>B<:>I<CF>B<:>I<format> (deprecated)
  28
  29 B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format> (deprecated)
  30
  31 B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>] (deprecated)
  32
  33 =head1 DESCRIPTION
  34
  35 These instructions allow you to generate your image or report.
  36 If you don't use any graph elements, no graph is generated.
  37 Similarly, no report is generated if you don't use print options.
  38
  39 =head2 PRINT
  40
  41 =over
  42
  43 =item B<PRINT:>I<vname>B<:>I<format>[B<:strftime>]
  44
  45 Depending on the context, either the value component or the time
  46 component of a B<VDEF> is printed using I<format>. It is an error
  47 to specify a I<vname> generated by a B<DEF> or B<CDEF>.
  48
  49 Any text in I<format> is printed literally with one exception:
  50 The percent character introduces a formatter string. This string
  51 can be:
  52
  53 For printing values:
  54
  55 B<%%> - just prints a literal '%' character
  56
  57 B<%#.#le> - prints numbers like 1.2346e+04. The optional integers # denote field
  58 width and decimal precision.
  59
  60 B<%#.#lf> - prints numbers like 12345.6789, with optional field width
  61 and precision.
  62
  63 B<%s> - place this after B<%le>, B<%lf> or B<%lg>. This will be replaced by the
  64 appropriate SI magnitude unit and the value will be scaled
  65 accordingly (123456 -> 123.456 k).
  66
  67 B<%S> - is similar to B<%s>. It does, however, use a previously defined
  68 magnitude unit. If there is no such unit yet, it tries to define
  69 one (just like B<%s>) unless the value is zero, in which case the magnitude
  70 unit stays undefined. Thus, formatter strings using B<%S> and no B<%s>
  71 will all use the same magnitude unit except for zero values.
  72
  73 If you PRINT a VDEF value, you can also print the time associated with it by appending the string
  74 B<:strftime> to the format. Note that rrdtool uses the strftime function of your OSs clibrary. This means that
  75 the conversion specifier may vary. Check the manual page if you are uncertain. The following is a list of
  76 conversion specifiers usually supported across the board.
  77
  78 B<%a> - The abbreviated weekday name according to the current locale.
  79
  80 B<%A> - The full weekday name according to the current locale.
  81
  82 B<%b> - The abbreviated month name according to the current locale.
  83
  84 B<%B> - The full month name according to the current locale.
  85
  86 B<%c> - The preferred date and time representation for the current locale.
  87
  88 B<%d> - The day of the month as a decimal number (range 01 to 31).
  89
  90 B<%H> - The hour as a decimal number using a 24-hour clock (range 00 to 23).
  91
  92 B<%I> - The hour as a decimal number using a 12-hour clock (range 01 to 12).
  93
  94 B<%j> - The day of the year as a decimal number (range 001 to 366).
  95
  96 B<%m> - The month as a decimal number (range 01 to 12).
  97
  98 B<%M> - The minute as a decimal number (range 00 to 59).
  99
 100 B<%p> - Either `AM' or `PM' according to the given time value, or the corresponding
 101 strings for the current locale.  Noon is treated as `pm' and midnight as
 102 `am'.  Note that in many locales and `pm' notation is unsupported and in
 103 such cases %p will return an empty string.
 104
 105 B<%S> - The second as a decimal number (range 00 to 61).
 106
 107 B<%U> - The  week  number  of  the current year as a decimal number, range 00 to 53, starting with the
 108 first Sunday as the first day of week 01. See also %V and %W.
 109
 110 B<%V> - The ISO 8601:1988 week number of the current year as a decimal number, range 01 to  53,  where
 111 week  1 is the first week that has at least 4 days in the current year, and with Monday as the
 112 first day of the week. See also %U and %W.
 113
 114 B<%w> - The day of the week as a decimal, range 0 to 6, Sunday being 0.  See also %u.
 115
 116 B<%W> - The week number of the current year as a decimal number, range 00 to  53,  starting  with  the
 117 first Monday as the first day of week 01.
 118
 119 B<%x> - The preferred date representation for the current locale without the time.
 120
 121 B<%X> - The preferred time representation for the current locale without the date.
 122
 123 B<%y> - The year as a decimal number without a century (range 00 to 99).
 124
 125 B<%Y> - The year as a decimal number including the century.
 126
 127 B<%Z> - The time zone or name or abbreviation.
 128
 129 B<%%> - A literal `%' character.
 130
 131 =item B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>
 132
 133 I<Deprecated. Use the new form of this command in new scripts.>
 134 The first form of this command is to be used with B<CDEF> I<vname>s.
 135
 136 =back
 137
 138 =head2 GRAPH
 139
 140 =over
 141
 142 =item B<GPRINT>B<:>I<vname>B<:>I<format>
 143
 144 This is the same as C<PRINT>, but printed inside the graph.
 145
 146 =item B<GPRINT>B<:>I<vname>B<:>I<CF>B<:>I<format>
 147
 148 I<Deprecated. Use the new form of this command in new scripts.>
 149 This is the same as C<PRINT>, but printed inside the graph.
 150
 151 =item B<COMMENT>B<:>I<text>
 152
 153 Text is printed literally in the legend section of the graph. Note that in
 154 RRDtool 1.2 you have to escape colons in COMMENT text in the same way you
 155 have to escape them in B<*PRINT> commands by writing B<'\:'>.
 156
 157 =item B<VRULE>B<:>I<time>B<#>I<color> [B<:>I<legend> ]
 158
 159 Draw a vertical line at I<time>.  Its color is composed from three
 160 hexadecimal numbers specifying the rgb color components (00 is off, FF is
 161 maximum) red, green and blue followed by an optional alpha. Optionally, a legend box and string is
 162 printed in the legend section. I<time> may be a number or a variable
 163 from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
 164
 165 =item B<HRULE>B<:>I<value>B<#>I<color> [ :I<legend> ]
 166
 167 Draw a horizontal line at I<value>.  HRULE acts much like LINE except that
 168 will have no effect on the scale of the graph. If a HRULE is outside the
 169 graphing area it will just not be visible.
 170
 171 =item B<LINE>[I<width>]B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
 172
 173 Draw a line of the specified width onto the graph. I<width> can be a
 174 floating point number. If the color is not specified, the drawing is done
 175 'invisibly'. This is useful when stacking something else on top of this
 176 line. Also optional is the legend box and string which will be printed in
 177 the legend section if specified. The B<value> can be generated by B<DEF>,
 178 B<VDEF>, and B<CDEF>.  If the optional B<STACK> modifier is used, this line
 179 is stacked on top of the previous element which can be a B<LINE> or an
 180 B<AREA>.
 181
 182 When you do not specify a color, you cannot specify a legend.  Should
 183 you want to use STACK, use the "LINEx:<value>::STACK" form.
 184
 185 =item B<AREA>B<:>I<value>[B<#>I<color>][B<:>[I<legend>][B<:STACK>]]
 186
 187 See B<LINE>, however the area between the x-axis and the line will
 188 be filled.
 189
 190 =item B<TICK>B<:>I<vname>B<#>I<rrggbb>[I<aa>][B<:>I<fraction>[B<:>I<legend>]]
 191
 192 Plot a tick mark (a vertical line) for each value of I<vname> that is
 193 non-zero and not *UNKNOWN*. The I<fraction> argument specifies the length of
 194 the tick mark as a fraction of the y-axis; the default value is 0.1 (10% of
 195 the axis). Note that the color specification is not optional. The TICK marks normaly
 196 start at the lower edge of the graphing area. If the fraction is negative they start
 197 at the upper border of the graphing area.
 198
 199 =item B<SHIFT>B<:>I<vname>B<:>I<offset>
 200
 201 Using this command B<RRDtool> will graph the following elements
 202 with the specified offset.  For instance, you can specify an
 203 offset of S<( 7*24*60*60 = ) 604'800 seconds> to "look back" one
 204 week. Make sure to tell the viewer of your graph you did this ...
 205 As with the other graphing elements, you can specify a number or
 206 a variable here.
 207
 208 =item B<STACK>B<:>I<vname>B<#>I<color>[B<:>I<legend>]
 209
 210 I<Deprecated.  Use the B<STACK> modifiers on the other commands.>
 211
 212 =back
 213
 214 B<Some notes on stacking>
 215
 216 When stacking, an element is not placed above the X-axis but rather
 217 on top of the previous element.  There must be something to stack
 218 upon.
 219
 220 You can use an B<invisible> LINE or AREA to stacked upon.
 221
 222 An B<unknown> value makes the entire stack unknown from that moment on.
 223 You don't know where to begin (the unknown value) and therefore do
 224 not know where to end.
 225
 226 If you want to make sure you will be displaying a certain variable,
 227 make sure never to stack upon the unknown value.  Use a CDEF instruction
 228 with B<IF> and B<UN> to do so.
 229
 230 =head1 NOTES on legend arguments
 231
 232 =head2 Escaping the colon
 233
 234 A colon ':' in a I<legend> argument will mark the end of the
 235 legend. To enter a ':' as part of a legend, the colon must be escaped
 236 with a backslash '\:'.  Beware that many environments process
 237 backslashes themselves, so it may be necessary to write two
 238 backslashes in order to one being passed onto rrd_graph.
 239
 240 =head2 String Formatting
 241
 242 The text printed below the actual graph can be formatted by appending special
 243 escape characters at the end of a text. When ever such a character occurs,
 244 all pending text is pushed onto the graph according to the character
 245 specified.
 246
 247 Valid markers are: B<\j> for justified, B<\l> for left aligned, B<\r> for
 248 right aligned, and B<\c> for centered. In the next section there is an
 249 example showing how to use centered formatting.
 250
 251 B<\n> is a valid alias for B<\l> since incomplete parsing in earlier
 252 versions of rrdtool lead to this behaviour and a number of people has been using it.
 253
 254 Normally there are two space characters inserted between every two items
 255 printed into the graph. The space following a string can be suppressed by
 256 putting a B<\g> at the end of the string. The B<\g> also ignores any space
 257 inside the string if it is at the very end of the string. This can be used
 258 in connection with B<%s> to suppress empty unit strings.
 259
 260  GPRINT:a:MAX:%lf%s\g
 261
 262 A special case is COMMENT:B<\s> which inserts some additional vertical space
 263 before placing the next row of legends.
 264
 265 If you are using the proportional font in your graph, you can use tab
 266 characters or the sequence B<\t> to line-up legend elements. Note that
 267 the tabs inserted are relative to the start of the current legend
 268 element!
 269
 270 =head1 SEE ALSO
 271
 272 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
 273 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail.
 274 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements.
 275 L<rrdgraph_graph> page describes all of the graph and print functions.
 276
 277 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
 278
 279 =head1 AUTHOR
 280
 281 Program by Tobias Oetiker E<lt>tobi@oetiker.chE<gt>
 282
 283 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>