5 WARNING: DO NOT EDIT THE POD FILES. THEY ARE AUTO-GENERATED
9 rrdgraph - Round Robin Database tool grapher functions
13 B<rrdtool graph> I<filename>
14 [I<L<option|rrdgraph/OPTIONS>> ...]
15 [I<L<data definition|rrdgraph_data/DEF>> ...]
16 [I<L<data calculation|rrdgraph_data/CDEF>> ...]
17 [I<L<variable definition|rrdgraph_data/VDEF>> ...]
18 [I<L<graph element|rrdgraph_graph/GRAPH>> ...]
19 [I<L<print element|rrdgraph_graph/PRINT>> ...]
23 The B<graph> function of B<RRDtool> is used to present the
24 data from an B<RRD> to a human viewer. Its main purpose is to
25 create a nice graphical representation but it can also generate
30 B<rrdtool graph> needs data to work with, use one or more
31 B<L<data definition|rrdgraph_data/DEF>> statements to collect this
32 data. You are not limited to one database, it's perfectly legal to
33 collect data from two or more databases (one per statement though).
35 If you want to display averages, maxima, percentiles etcetera
36 it is best to collect them now using the
37 B<L<variable definition|rrdgraph_data/VDEF>> statement.
38 Currently this makes no difference but in a future version
39 of rrdtool you may want to collect these values before consolidation.
41 The data fetched from the B<RRA> is then B<consolidated> so that
42 there is exactly one datapoint per pixel in the graph. If you do
43 not take care yourself, B<RRDtool> will expand the range slightly
44 if necessary (in that case the first and/or last pixel may very
45 well become unknown!).
47 Sometimes data is not exactly as you would like to display it. For
48 instance, you might be collecting B<bytes> per second but want to
49 display B<bits> per second. This is where the
50 B<L<data calculation|rrdgraph_data/CDEF>> command is designed for.
51 After B<consolidating> the data, a copy is made and this copy is
52 modified using a rather flexible B<L<RPN|rrdgraph_rpn/>> command
55 When you are done fetching and processing the data, it is time to
56 graph it (or print it). This ends the B<rrdtool graph> sequence.
64 The name and path of the graph to generate. It is recommended to
65 end this in C<.png>, C<.svg> or C<.eps> but B<RRDtool> does not enforce this.
67 I<filename> can be 'C<->' to send the image to C<stdout>. In
68 that case, no other output is generated.
72 [B<-s>|B<--start> I<time>]
73 [B<-e>|B<--end> I<time>]
74 [B<-S>|B<--step> I<seconds>]
76 The start and end of what you would like to display, and which
77 B<RRA> the data should come from. Defaults are: 1 day ago until
78 now, with the best possible resolution. B<Start> and B<end> can
79 be specified in several formats, see
80 L<AT-STYLE TIME SPECIFICATION|rrdfetch/> and L<rrdgraph_examples>.
81 By default, B<rrdtool graph> calculates the width of one pixel in
82 the time domain and tries to get data from an B<RRA> with that
83 resolution. With the B<step> option you can alter this behaviour.
84 If you want B<rrdtool graph> to get data at a one-hour resolution
85 from the B<RRD>, set B<step> to 3600. Note: a step smaller than
86 one pixel will silently be ignored.
90 [B<-t>|B<--title> I<string>]
91 [B<-v>|B<--vertical-label> I<string>]
93 A horizontal string at the top of the graph and/or a vertically
94 placed string at the left hand side of the graph.
98 [B<-w>|B<--width> I<pixels>]
99 [B<-h>|B<--height> I<pixels>]
100 [B<-j>|B<--only-graph>]
102 The width and height of the B<canvas> (the part of the graph with
103 the actual lines and such). Defaults are 400 pixels by 100 pixels.
105 If you specify the B<--only-graph> option and set the height E<lt> 32
106 pixels you will get a tiny graph image to use as an icon in a potential
107 overview. All labeling will be stripped off the graph.
111 [B<-u>|B<--upper-limit> I<value>]
112 [B<-l>|B<--lower-limit> I<value>]
115 By default the graph will be autoscaling so that it displays the
116 portion of the y-axis that is actually used. You can change this
117 behaviour by setting the limits. The displayed y-axis will show
118 at least from B<lower-limit> to B<upper-limit>. Autoscaling will
119 still permit those boundaries to be stretched unless the B<rigid>
122 [B<-A>|B<--alt-autoscale>]
124 Sometimes the default algorithm for selecting the y-axis scale is not
125 performing very well. Normally the scale is selected from a predefined
126 set of ranges and this fails miserably when you need to graph something
127 like C<260 + 0.001 * sin(x)>. This option calculates the minimum and
128 maximum y-axis from the actual minimum and maximum values. Our example
129 would display slightly less than C<260-0.001> to slightly more than
130 C<260+0.001> (Contributed by Sasha Mikheev).
132 [B<-M>|B<--alt-autoscale-max>]
134 Where C<--alt-autoscale> will modify both the absolute maximum AND minimum
135 values, this option will only affect the maximum value. The minimum
136 value, if not defined on the command line, will be 0. This option can
137 be useful when graphing router traffic when the WAN line uses compression,
138 and thus the throughput may be higher than the WAN line speed.
140 [B<-N>|B<--no-gridfit>]
142 To avoid anti-aliasing effects gridlines are placed on
143 integer pixel values. This is by default done by extending
144 the scale so gridlines happens to be spaced using an
145 integer number of pixels, and starts on integer pixel value.
146 This might extend the scale too much for some logarithmic scales
147 and for linear scales where B<--alt-autoscale> is needed.
148 Using B<--no-gridfit> disables modification of the scale.
156 [B<-x>|B<--x-grid> I<GTM>B<:>I<GST>B<:>I<MTM>B<:>I<MST>B<:>I<LTM>B<:>I<LST>B<:>I<LPR>B<:>I<LFM>]
158 [B<-x>|B<--x-grid> B<none>]
160 The x-axis label is quite complex to configure, if you don't have
161 very special needs it is probably best to rely on the autoconfiguration
162 to get this right. You can specify the string C<none> to skip the grid
163 and labels altogether.
165 The grid is defined by specifying a certain amount of time in the I<?TM>
166 positions. You can choose from C<SECOND>, C<MINUTE>, C<HOUR>, C<DAY>,
167 C<WEEK>, C<MONTH> or C<YEAR>. Then you define how many of these should
168 pass between each line or label. This pair (I<?TM:?ST>) needs to be
169 specified for the base grid (I<G??>), the major grid (I<M??>) and the
170 labels (I<L??>). For the labels you also need to define a precision
171 in I<LPR> and a I<strftime> format string in I<LFM>. I<LPR> defines
172 where each label will be placed. If it is zero, the label will be
173 placed right under the corresponding line (useful for hours, dates
174 etcetera). If you specify a number of seconds here the label is
175 centered in this interval (useful for Monday, January etcetera).
177 Example: C<--x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X>
179 This places grid lines every 10 minutes, major grid lines every hour
180 and labels every 4 hours. The labels are placed under the major grid
181 lines as they specify exactly that time.
183 Example: C<--x-grid HOUR:8:DAY:1:DAY:1:0:%A>
185 This places grid lines every 8 hours, major grid lines and labels
186 each day. The labels are placed exactly between two major grid lines
187 as they specify the complete day and not just midnight.
191 [B<-y>|B<--y-grid> I<grid step>B<:>I<label factor>]
193 [B<-y>|B<--y-grid> B<none>]
195 Y-axis grid lines appear at each I<grid step> interval. Labels are
196 placed every I<label factor> lines. You can specify C<-y none> to
197 skip the grid and labels altogether. The default for this option is
198 to automatically select sensible values.
200 [B<-Y>|B<--alt-y-grid>]
202 Place Y grid dynamically based on graph Y range. Algorithm ensures
203 that you always have grid, that there are enough but not too many
204 grid lines and the grid is metric. That is grid lines are placed
205 every 1, 2, 5 or 10 units. (contributed by Sasha Mikheev)
207 [B<-o>|B<--logarithmic>]
209 Logarithmic y-axis scaling.
211 [B<-X>|B<--units-exponent> I<value>]
213 This sets the 10**exponent scaling of the y-axis values. Normally
214 values will be scaled to the appropriate units (k, M, etc.). However
215 you may wish to display units always in k (Kilo, 10e3) even if the data
216 is in the M (Mega, 10e6) range for instance. Value should be an
217 integer which is a multiple of 3 between -18 and 18 inclusive. It is
218 the exponent on the units you which to use. For example, use 3 to
219 display the y-axis values in k (Kilo, 10e3, thousands), use -6 to
220 display the y-axis values in u (Micro, 10e-6, millionths). Use a value
221 of 0 to prevent any scaling of the y-axis values.
223 This option is very effective at confusing the heck out of the default
224 rrdtool autoscaler and grid painter. If rrdtool detects that it is not
225 successful in labeling the graph under the given circumstances, it will switch
226 to the more robust B<--alt-y-grid> mode.
228 [B<-L>|B<--units-length> I<value>]
230 How many digits should rrdtool assume the y-axis labels to be ? You may have to use this option
231 to make enough space once you start fideling with the y-axis labeling.
239 Only generate the graph, if the current graph is out of date or not
242 [B<-f>|B<--imginfo> I<printfstr>]
244 After the image has been created, the graph function uses printf
245 together with this format string to create output similar to the PRINT
246 function, only that the printf is supplied with the parameters
247 I<filename>, I<xsize> and I<ysize>. In order to generate an B<IMG> tag
248 suitable for including the graph into a web page, the command line
249 would look like this:
251 --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
253 [B<-c>|B<--color> I<COLORTAG>#I<rrggbb>[I<aa>]]
255 Override the default colors for the standard elements of the graph. The
256 I<COLORTAG> is one of C<BACK> background, C<CANVAS> for the background of
257 the actual graph, C<SHADEA> for the left and top border, C<SHADEB> for the
258 right and bottom border, C<GRID>, C<MGRID> for the major grid, C<FONT> for
259 the color of the font, C<AXIS> for the axis of the graph and finaly C<ARROW>
260 for the arrow head pointing to the future. Each color is composed out of
261 three hexadecimal numbers specifying its color component (00 is off, FF is
262 maximum) of red, green and blue. Optionally you may add another hexadecimal
263 number specifying the transparency (FF is solid). You may set this option
264 several times to alter multiple defaults.
266 A green arrow is made by: C<--color ARROW:00FF00>
268 [B<--zoom> I<factor>]
270 Zoom the graphics by the given amount ... The factor must be E<gt> 0
272 [B<-n>|B<--font> I<FONTTAG>B<:>I<size>B<:>I<font>]
274 Lets you customize which font to use for the various text elements on the
275 RRD graphs. C<DEFAULT> sets the default value for all elements C<TITLE>,
276 C<AXIS> for the axis labels, C<UNIT> for the vertical unit label, C<LEGEND>
277 for the graph legend.
279 Use Times for the title: C<--font TITLE:13:/usr/lib/fonts/times.ttf>
281 RRDtool comes with a preset default font. You can set the environment
282 variable C<RRD_DEFAULT_FONT> if you want to change this.
284 Truetype fonts are only supported for PNG output. See below.
286 [B<-a>|B<--imgformat> B<PNG>|B<SVG>|B<EPS>|B<PDF>]
288 Image format for the generated graph. For the vector formats you can choose among the standard Postscript fonts
289 Courier-Bold, Courier-BoldOblique, Courier-Oblique, Courier, Helvetica-Bold,
290 Helvetica-BoldOblique, Helvetica-Oblique, Helvetica, Symbol, Times-Bold, Times-BoldItalic,
291 Times-Italic, Times-Roman, ZapfDingbats
293 [B<-i>|B<--interlaced>]
295 If images are interlaced they become visible on browsers more quickly.
297 [B<-g>|B<--no-legend>]
299 Suppress generation of legend; only render the graph.
301 [B<-F>|B<--force-rules-legend>]
303 Force the generation of HRULE and VRULE legend even if those HRULE or VRULE will not be drawn because out of graph boundaries (mimics behaviour of pre 1.0.42 versions).
305 [B<-T>|B<--tabwidth> I<value>]
307 By default the tab-width is 40 pixels, use this option to change it.
309 [B<-b>|B<--base> I<value>]
311 If you are graphing memory (and NOT network traffic) this switch
312 should be set to 1024 so that one Kb is 1024 byte. For traffic
313 measurement, 1 kb/s is 1000 b/s.
315 =item Data and variables
317 B<DEF:>I<vname>B<=>I<rrdfile>B<:>I<ds-name>B<:>I<CF>[B<:step=>I<step>][B<:start=>I<time>][B<:end=>I<time>]
319 B<CDEF:>I<vname>B<=>I<RPN expression>
321 B<VDEF:>I<vname>B<=>I<RPN expression>
323 You need at least one B<DEF> statement to generate anything. The
324 other statements are useful but optional.
325 See L<rrdgraph_data> and L<rrdgraph_rpn> for exact format.
327 =item Graph and print elements
329 You need at least one graph element to generate an image and/or
330 at least one print statement to generate a report.
331 See L<rrdgraph_graph> for exact format.
335 L<rrdgraph> gives an overview of how B<rrdtool graph> works.
336 L<rrdgraph_data> describes B<DEF>,B<CDEF> and B<VDEF> in detail,
337 L<rrdgraph_rpn> describes the B<RPN> language used in the B<?DEF> statements,
338 L<rrdgraph_graph> page describes all of the graph and print functions.
340 Make sure to read L<rrdgraph_examples> for tipsE<amp>tricks.
344 Program by Tobias Oetiker E<lt>oetiker@ee.ethz.chE<gt>
346 This manual page by Alex van den Bogaerdt E<lt>alex@ergens.op.het.netE<gt>