3 rrdtool graph - Round Robin Database tool grapher functions
5 WARNING: This is for version 1.1.x which is B<I<BETA>> software.
6 The software may contain serious bugs. Some of the items
7 described in here may not yet exist (although this should
8 be mentioned) or still be in the alpha stage. As with every
9 other RRDtool release: use at your own risk. In contrast with
10 the stable version of RRDtool, this release may contain bugs
11 known to the authors. It is highly recommended that you subscribe
16 I<(to be) Depriciated commands>
18 [B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>]
19 [B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>]
20 [B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]]
21 [B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]]
23 I<(soon) available commands>
25 [B<PRINT:>I<vname>B<:>I<format>]
26 [B<GPRINT:>I<vname>B<:>I<format>]
28 [B<VRULE:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]]
29 [B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]][B<:STACK>]
30 [B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]][B<:STACK>]
32 I<to be implemented commands>
35 [B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]]
39 These instructions allow you to generate your image or report.
40 If you don't use any graph elements, no graph is generated.
41 Similarly no report is generated if you don't use print options.
45 B<PRINT:>I<vname>B<:>I<CF>B<:>I<format>
47 I<Soon depriciated. Use the new form of this command in new scripts.>
48 The first form of this command is to be used with B<CDEF> I<vname>s.
50 B<PRINT:>I<vname>B<:>I<format>
52 Depending on the context, either the value component or the time
53 component of a B<VDEF> is printed using I<format>. It is an error
54 to specify a I<vname> generated by a B<DEF> or B<CDEF>.
56 Any text in I<format> is printed literally with one exception:
57 The percent character introduces a formatter string. This string
66 B<%%> just prints a literal '%' character
70 B<%#.#le> (where # is an optional number) prints like 1.2346e+04
74 B<%#.#lf> prints like 12345.6789
78 B<%s> place this after B<%le> or B<%lf>. This will be replaced by the
79 appropriate SI magnitude unit and the value will be scaled
80 accordingly (123456 -> 123.456 k)
84 B<%S> is similar to B<%s>. It does however use a previously defined
85 magnitude unit. If there is no such unit yet, it tries to define
86 one (just like B<%s>). However, if the value is zero, the magnitude
87 unit stays undefined. Thus, formatter strings using B<%S> and no B<%s>
88 will all use the same magnitude unit except for zero values.
98 B<%%> just prints a literal '%' character
102 B<%a, %A> prints abbreviated, full weekday name
106 B<%b, %B> prints abbreviated, full month name
110 B<%d, %m, %y, %H, %M, %S> day,month,year,hour,minute,second all in two-digit format
114 B<%Y> year in 4-digit format
118 B<%I, %p> hour (01..12), 'am' or 'pm'
122 B<%j, %w> day of the week (0..6), day of the year (1..366)
126 B<%c, %x, %X> date+time, date, time
130 B<%U, %W> week number of the current year with either the first sunday or
131 the first monday determining the first week
141 B<GPRINT:>I<vname>B<:>I<CF>B<:>I<format>
143 I<Soon depriciated. Use the new form of this command in new scripts.>
144 This is the same as B<PRINT> but now it is printed inside the graph.
145 See L<PRINT> for more information.
147 B<GPRINT:>I<vname>B<:>I<format>
149 This is the same as B<PRINT> but now it is printed inside the graph.
150 See L<PRINT> for more information.
154 Text is printed literally in the legend section of the graph
156 B<HRULE:>I<value>B<#>I<rrggbb>[B<:>I<legend>]
158 I<Soon depriciated. Use a VDEF and a LINEx in new scripts.>
160 Draw an horizontal line at I<value>. Its color is composed from three
161 hexadecimal numbers specifying the color components (00 is off, FF is
162 maximum) red, green and blue. Optionally a legend box and string is
163 printed in the legend section.
165 B<VRULE:>I<time>B<#>I<rrggbb>[B<:>I<legend>]
167 Draw a vertical line at I<time>. Its color is composed from three
168 hexadecimal numbers specifying the color components (00 is off, FF is
169 maximum) red, green and blue. Optionally a legend box and string is
170 printed in the legend section. I<time> may be a number or a variable
171 from a B<VDEF>. It is an error to use I<vname>s from B<DEF> or B<CDEF> here.
173 B<LINE>{B<1>|B<2>|B<3>}B<:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>]
175 Draw a line of the specified width into the graph. If the color
176 is not specified, the drawing is done 'blind'. This is useful when
177 stacking something else on top of this line. Also optional is the
178 legend box and string which will be printed in the legend section
179 if specified. The B<vname> can be generated by B<DEF>, B<VDEF> and
180 B<CDEF>. If the optional B<STACK> modifier is used, this line is
181 stacked on top of the previous element which can be a B<LINEx> or
184 B<AREA:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]][B<:STACK>]
186 See B<LINEx>, however the area between the x-axis and the line will
189 B<STACK:>I<vname>[B<#>I<rrggbb>[B<:>I<legend>]]
191 I<Depriciated. Use the B<STACK> modifiers on the other commands.>
192 I<Note: the comments on stacking are still valid...>
193 Repeats the last B<LINEx> or B<AREA> however it doesn't start at the
194 x-axis but rather on top of the previous element. This implies that
195 there needs to be something to stack on. An invisible B<LINEx> or
196 B<AREA> is something you can stack on!
198 Note: When you stack on something that was I<unknown>, the whole
199 stack will be I<unknown> for that point in time. If the beginning
200 is undefined, there's no way to end somewhere... If you want to
201 graph this stacked variable anyway you need to make sure that the
202 B<LINEx> or B<AREA> it gets stacked on is not unknown. Use a CDEF
203 instruction with B<IF> and B<UN> to do so.
205 B<THE NEXT STUFF IS NOT YET IMPLEMENTED>
207 B<SHIFT:>I<offset in seconds>
209 Using this command B<RRDtool> will graph the following elements
210 with the specified offset. For instance, you can specify an
211 offset of S<( 7*24*60*60 = ) 604800 seconds> to "look back" one
212 week. Make sure to notify the viewer you did so...
213 The offset will be valid until the next B<SHIFT> command, which
214 can have an offset of zero to restore normal graphing.
215 As with the other grapher elements, you can specify a number or
218 B<RRDtool> has now support for B<pie charts>. If you include the
219 B<PART> command, the canvas is extended to make room for a chart
220 (or, if no other graph elements are used, the canvas is solely
221 used for the pie chart). The size of the canvas is determined by
222 the lesser of L<width and height|rrdgraph/item_Size>.
224 B<PART:>I<vname>B<#>I<rrggbb>[B<:>I<legend>]
226 Draw a part of pie. Pie parts will be concatenated, the first one
227 will start at the top and parts will be created clockwise.
228 The size of the part is defined by the value part of
229 the L<VDEF|rrdgraph_data/VDEF> function. It should return
230 a number between 0 and 100, being a percentage.
231 Providing wrong input will produce undefined results.
235 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
236 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
237 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
238 L<rrdgraph_graph> page describes all of the graph and print functions.
240 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
244 Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
246 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>