6bb25bc92343feb5e3251312887bd6c0fa1ef545
1 RRDGRAPH(1) rrdtool RRDGRAPH(1)
6 rrdgraph - Round Robin Database tool grapher functions
9 r\brr\brd\bdt\bto\boo\bol\bl g\bgr\bra\bap\bph\bh|\b|g\bgr\bra\bap\bph\bhv\bv _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be [_\bo_\bp_\bt_\bi_\bo_\bn ...] [_\bd_\ba_\bt_\ba _\bd_\be_\bf_\bi_\bn_\bi_\bt_\bi_\bo_\bn ...]
10 [_\bd_\ba_\bt_\ba _\bc_\ba_\bl_\bc_\bu_\bl_\ba_\bt_\bi_\bo_\bn ...] [_\bv_\ba_\br_\bi_\ba_\bb_\bl_\be _\bd_\be_\bf_\bi_\bn_\bi_\bt_\bi_\bo_\bn ...] [_\bg_\br_\ba_\bp_\bh _\be_\bl_\be_\bm_\be_\bn_\bt ...]
14 The g\bgr\bra\bap\bph\bh function of R\bRR\bRD\bDt\bto\boo\bol\bl is used to present the data from an R\bRR\bRD\bD
15 to a human viewer. Its main purpose is to create a nice graphical rep-
16 resentation, but it can also generate a numerical report.
19 r\brr\brd\bdt\bto\boo\bol\bl g\bgr\bra\bap\bph\bh needs data to work with, so you must use one or more d\bda\bat\bta\ba
20 d\bde\bef\bfi\bin\bni\bit\bti\bio\bon\bn statements to collect this data. You are not limited to one
21 database, it's perfectly legal to collect data from two or more
22 databases (one per statement, though).
24 If you want to display averages, maxima, percentiles, etcetera it is
25 best to collect them now using the v\bva\bar\bri\bia\bab\bbl\ble\be d\bde\bef\bfi\bin\bni\bit\bti\bio\bon\bn statement. Cur-
26 rently this makes no difference, but in a future version of rrdtool you
27 may want to collect these values before consolidation.
29 The data fetched from the R\bRR\bRA\bA is then c\bco\bon\bns\bso\bol\bli\bid\bda\bat\bte\bed\bd so that there is
30 exactly one datapoint per pixel in the graph. If you do not take care
32 that case the first and/or last pixel may very well become unknown!
34 Sometimes data is not exactly in the format you would like to display
36 display b\bbi\bit\bts\bs per second. This is what the d\bda\bat\bta\ba c\bca\bal\blc\bcu\bul\bla\bat\bti\bio\bon\bn command is
37 designed for. After c\bco\bon\bns\bso\bol\bli\bid\bda\bat\bti\bin\bng\bg the data, a copy is made and this
40 When you are done fetching and processing the data, it is time to graph
43 Use g\bgr\bra\bap\bph\bhv\bv instead of g\bgr\bra\bap\bph\bh to get detailed information about the graph
44 geometry and data once it is drawn. See the bottom of the document for
45 more information.
50 The name and path of the graph to generate. It is recommended to end
54 other output is generated.
58 [-\b-s\bs|-\b--\b-s\bst\bta\bar\brt\bt _\bt_\bi_\bm_\be] [-\b-e\be|-\b--\b-e\ben\bnd\bd _\bt_\bi_\bm_\be] [-\b-S\bS|-\b--\b-s\bst\bte\bep\bp _\bs_\be_\bc_\bo_\bn_\bd_\bs]
60 The start and end of the time series you would like to display, and
63 in several formats, see AT-STYLE TIME SPECIFICATION and rrdgraph_exam-
64 ples. By default, r\brr\brd\bdt\bto\boo\bol\bl g\bgr\bra\bap\bph\bh calculates the width of one pixel in
66 With the s\bst\bte\bep\bp option you can alter this behaviour. If you want r\brr\brd\bdt\bto\boo\bol\bl
67 g\bgr\bra\bap\bph\bh to get data at a one-hour resolution from the R\bRR\bRD\bD, set s\bst\bte\bep\bp to
68 3'600. Note: a step smaller than one pixel will silently be ignored.
72 [-\b-t\bt|-\b--\b-t\bti\bit\btl\ble\be _\bs_\bt_\br_\bi_\bn_\bg] [-\b-v\bv|-\b--\b-v\bve\ber\brt\bti\bic\bca\bal\bl-\b-l\bla\bab\bbe\bel\bl _\bs_\bt_\br_\bi_\bn_\bg]
74 A horizontal string at the top of the graph and/or a vertically placed
75 string at the left hand side of the graph.
79 [-\b-w\bw|-\b--\b-w\bwi\bid\bdt\bth\bh _\bp_\bi_\bx_\be_\bl_\bs] [-\b-h\bh|-\b--\b-h\bhe\bei\big\bgh\bht\bt _\bp_\bi_\bx_\be_\bl_\bs] [-\b-j\bj|-\b--\b-o\bon\bnl\bly\by-\b-g\bgr\bra\bap\bph\bh]
83 actual data and such). This defaults to 400 pixels by 100 pixels.
85 If you specify the -\b--\b-f\bfu\bul\bll\bl-\b-s\bsi\biz\bze\be-\b-m\bmo\bod\bde\be option, the width and height spec-
86 ify the final dimensions of the output image and the canvas is automat-
87 ically resized to fit.
89 If you specify the -\b--\b-o\bon\bnl\bly\by-\b-g\bgr\bra\bap\bph\bh option and set the height < 32 pixels
90 you will get a tiny graph image (thumbnail) to use as an icon for use
91 in an overview, for example. All labeling will be stripped off the
92 graph.
96 [-\b-u\bu|-\b--\b-u\bup\bpp\bpe\ber\br-\b-l\bli\bim\bmi\bit\bt _\bv_\ba_\bl_\bu_\be] [-\b-l\bl|-\b--\b-l\blo\bow\bwe\ber\br-\b-l\bli\bim\bmi\bit\bt _\bv_\ba_\bl_\bu_\be] [-\b-r\br|-\b--\b-r\bri\big\bgi\bid\bd]
98 By default the graph will be autoscaling so that it will adjust the
99 y-axis to the range of the data. You can change this behaviour by
100 explicitly setting the limits. The displayed y-axis will then range at
101 least from l\blo\bow\bwe\ber\br-\b-l\bli\bim\bmi\bit\bt to u\bup\bpp\bpe\ber\br-\b-l\bli\bim\bmi\bit\bt. Autoscaling will still permit
106 Sometimes the default algorithm for selecting the y-axis scale is not
107 satisfactory. Normally the scale is selected from a predefined set of
108 ranges and this fails miserably when you need to graph something like
109 "260 + 0.001 * sin(x)". This option calculates the minimum and maximum
110 y-axis from the actual minimum and maximum data values. Our example
111 would display slightly less than "260-0.001" to slightly more than
112 "260+0.001" (this feature was contributed by Sasha Mikheev).
116 Where "--alt-autoscale" will modify both the absolute maximum AND mini-
117 mum values, this option will only affect the minimum value. The maximum
118 value, if not defined on the command line, will be 0. This option can
119 be useful when graphing router traffic when the WAN line uses compres-
120 sion, and thus the throughput may be higher than the WAN line speed.
124 Where "--alt-autoscale" will modify both the absolute maximum AND mini-
125 mum values, this option will only affect the maximum value. The minimum
126 value, if not defined on the command line, will be 0. This option can
127 be useful when graphing router traffic when the WAN line uses compres-
128 sion, and thus the throughput may be higher than the WAN line speed.
132 In order to avoid anti-aliasing blurring effects rrdtool snaps points
133 to device resolution pixels, this results in a crisper appearance. If
134 this is not to your liking, you can use this switch to turn this
135 behaviour off.
137 Gridfitting is turned off for PDF, EPS, SVG output by default.
141 [-\b-x\bx|-\b--\b-x\bx-\b-g\bgr\bri\bid\bd _\bG_\bT_\bM:\b:_\bG_\bS_\bT:\b:_\bM_\bT_\bM:\b:_\bM_\bS_\bT:\b:_\bL_\bT_\bM:\b:_\bL_\bS_\bT:\b:_\bL_\bP_\bR:\b:_\bL_\bF_\bM]
145 The x-axis label is quite complex to configure. If you don't have very
146 special needs it is probably best to rely on the autoconfiguration to
147 get this right. You can specify the string "none" to suppress the grid
148 and labels altogether.
151 positions. You can choose from "SECOND", "MINUTE", "HOUR", "DAY",
152 "WEEK", "MONTH" or "YEAR". Then you define how many of these should
156 _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be format string in _\bL_\bF_\bM. _\bL_\bP_\bR defines where each label will be
157 placed. If it is zero, the label will be placed right under the corre-
158 sponding line (useful for hours, dates etcetera). If you specify a
159 number of seconds here the label is centered on this interval (useful
160 for Monday, January etcetera).
162 --x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X
164 This places grid lines every 10 minutes, major grid lines every hour,
165 and labels every 4 hours. The labels are placed under the major grid
166 lines as they specify exactly that time.
168 --x-grid HOUR:8:DAY:1:DAY:1:86400:%A
170 This places grid lines every 8 hours, major grid lines and labels each
171 day. The labels are placed exactly between two major grid lines as they
172 specify the complete day and not just midnight.
176 [-\b-y\by|-\b--\b-y\by-\b-g\bgr\bri\bid\bd _\bg_\br_\bi_\bd _\bs_\bt_\be_\bp:\b:_\bl_\ba_\bb_\be_\bl _\bf_\ba_\bc_\bt_\bo_\br]
181 every _\bl_\ba_\bb_\be_\bl _\bf_\ba_\bc_\bt_\bo_\br lines. You can specify "-y none" to suppress the
182 grid and labels altogether. The default for this option is to automat-
183 ically select sensible values.
185 If you have set --y-grid to 'none' not only the labels get suppressed,
186 also the space reserved for the labels is removed. You can still add
187 space manually if you use the --units-length command to explicitly
188 reserve space.
192 Place the Y grid dynamically based on the graph's Y range. The algo-
193 rithm ensures that you always have a grid, that there are enough but
194 not too many grid lines, and that the grid is metric. That is the grid
195 lines are placed every 1, 2, 5 or 10 units. This parameter will also
196 ensure that you get enough decimals displayed even if your graph goes
197 from 69.998 to 70.001. (contributed by Sasha Mikheev).
201 Logarithmic y-axis scaling.
203 [-\b-X\bX|-\b--\b-u\bun\bni\bit\bts\bs-\b-e\bex\bxp\bpo\bon\bne\ben\bnt\bt _\bv_\ba_\bl_\bu_\be]
205 This sets the 10**exponent scaling of the y-axis values. Normally, val-
206 ues will be scaled to the appropriate units (k, M, etc.). However, you
207 may wish to display units always in k (Kilo, 10e3) even if the data is
208 in the M (Mega, 10e6) range, for instance. Value should be an integer
209 which is a multiple of 3 between -18 and 18 inclusively. It is the
210 exponent on the units you wish to use. For example, use 3 to display
211 the y-axis values in k (Kilo, 10e3, thousands), use -6 to display the
212 y-axis values in u (Micro, 10e-6, millionths). Use a value of 0 to
213 prevent any scaling of the y-axis values.
215 This option is very effective at confusing the heck out of the default
216 rrdtool autoscaler and grid painter. If rrdtool detects that it is not
217 successful in labeling the graph under the given circumstances, it will
222 How many digits should rrdtool assume the y-axis labels to be? You may
223 have to use this option to make enough space once you start fiddling
224 with the y-axis labeling.
228 With this option y-axis values on logarithmic graphs will be scaled to
229 the appropriate units (k, M, etc.) instead of using exponential nota-
230 tion. Note that for linear graphs, SI notation is used by default.
234 [-\b--\b-r\bri\big\bgh\bht\bt-\b-a\bax\bxi\bis\bs _\bs_\bc_\ba_\bl_\be:\b:_\bs_\bh_\bi_\bf_\bt] [-\b--\b-r\bri\big\bgh\bht\bt-\b-a\bax\bxi\bis\bs-\b-l\bla\bab\bbe\bel\bl _\bl_\ba_\bb_\be_\bl]
236 A second axis will be drawn to the right of the graph. It is tied to
237 the left axis via the scale and shift parameters. You can also define a
238 label for the right axis.
240 [-\b--\b-r\bri\big\bgh\bht\bt-\b-a\bax\bxi\bis\bs-\b-f\bfo\bor\brm\bma\bat\bt _\bf_\bo_\br_\bm_\ba_\bt_\b-_\bs_\bt_\br_\bi_\bn_\bg]
242 By default the format of the axis lables gets determined automatically.
243 If you want todo this your self, use this option with the same %lf
244 arguments you know from the PRING and GPRINT commands.
250 Suppress generation of the legend; only render the graph.
254 Force the generation of HRULE and VRULE legends even if those HRULE or
255 VRULE will not be drawn because out of graph boundaries (mimics
256 behaviour of pre 1.0.42 versions).
260 Place the legend at the given side of the graph. The default is south.
261 In west or east position it is necessary to add line breaks manually.
265 Place the legend items in the given vertical order. The default is top-
266 down. Using bottomup the legend items appear in the same vertical
267 order as a stack of lines or areas.
273 Only generate the graph if the current graph is out of date or not
274 existent. Note, that all the calculations will happen regardless so
275 that the output of PRINT and graphv will be complete regardless. Note
276 that the behaviour of lazy in this regard has seen several changes over
277 time. The only thing you can realy rely on before rrdtool 1.3.7 is that
278 lazy will not generate the graph when it is already there and up to
279 date, and also that it will output the size of the graph.
283 Address of the rrdcached daemon. If specified, a "flush" command is
284 sent to the server before reading the RRD files. This allows the graph
285 to contain fresh data even if the daemon is configured to cache values
287 the rrdcached manual.
289 rrdtool graph [...] --daemon unix:/var/run/rrdcached.sock [...]
293 After the image has been created, the graph function uses printf
294 together with this format string to create output similar to the PRINT
295 function, only that the printf function is supplied with the parameters
296 _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be, _\bx_\bs_\bi_\bz_\be and _\by_\bs_\bi_\bz_\be. In order to generate an I\bIM\bMG\bG tag suitable for
297 including the graph into a web page, the command line would look like
298 this:
300 --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
302 [-\b-c\bc|-\b--\b-c\bco\bol\blo\bor\br _\bC_\bO_\bL_\bO_\bR_\bT_\bA_\bG#_\br_\br_\bg_\bg_\bb_\bb[_\ba_\ba]]
304 Override the default colors for the standard elements of the graph. The
306 the actual graph, "SHADEA" for the left and top border, "SHADEB" for
307 the right and bottom border, "GRID", "MGRID" for the major grid, "FONT"
308 for the color of the font, "AXIS" for the axis of the graph, "FRAME"
309 for the line around the color spots, and finally "ARROW" for the arrow
310 head pointing up and forward. Each color is composed out of three hex-
311 adecimal numbers specifying its rgb color component (00 is off, FF is
312 maximum) of red, green and blue. Optionally you may add another hex-
313 adecimal number specifying the transparency (FF is solid). You may set
314 this option several times to alter multiple defaults.
316 A green arrow is made by: "--color ARROW#00FF00"
320 Zoom the graphics by the given amount. The factor must be > 0
322 [-\b-n\bn|-\b--\b-f\bfo\bon\bnt\bt _\bF_\bO_\bN_\bT_\bT_\bA_\bG:\b:_\bs_\bi_\bz_\be:\b:[_\bf_\bo_\bn_\bt]]
324 This lets you customize which font to use for the various text elements
325 on the RRD graphs. "DEFAULT" sets the default value for all elements,
326 "TITLE" for the title, "AXIS" for the axis labels, "UNIT" for the ver-
327 tical unit label, "LEGEND" for the graph legend, "WATERMARK" for the
328 watermark on the edge of the graph.
330 Use Times for the title: "--font TITLE:13:Times"
332 If you do not give a font string you can modify just the size of the
333 default font: "--font TITLE:13:".
335 If you specify the size 0 then you can modify just the font without
336 touching the size. This is especially useful for altering the default
337 font without resetting the default fontsizes: "--font
338 DEFAULT:0:Courier".
340 RRDtool comes with a preset default font. You can set the environment
341 variable "RRD_DEFAULT_FONT" if you want to change this.
343 RRDtool uses Pango for its font handling. This means you can to use the
344 full Pango syntax when selecting your font:
346 The font name has the form "[_\bF_\bA_\bM_\bI_\bL_\bY_\b-_\bL_\bI_\bS_\bT] [_\bS_\bT_\bY_\bL_\bE_\b-_\bO_\bP_\bT_\bI_\bO_\bN_\bS] [_\bS_\bI_\bZ_\bE]",
347 where _\bF_\bA_\bM_\bI_\bL_\bY_\b-_\bL_\bI_\bS_\bT is a comma separated list of families optionally ter-
348 minated by a comma, _\bS_\bT_\bY_\bL_\bE_\b__\bO_\bP_\bT_\bI_\bO_\bN_\bS is a whitespace separated list of
349 words where each WORD describes one of style, variant, weight, stretch,
351 followed by the unit modifier "px" for absolute size. Any one of the
352 options may be absent.
354 [-\b-R\bR|-\b--\b-f\bfo\bon\bnt\bt-\b-r\bre\ben\bnd\bde\ber\br-\b-m\bmo\bod\bde\be {n\bno\bor\brm\bma\bal\bl,l\bli\big\bgh\bht\bt,m\bmo\bon\bno\bo}]
356 There are 3 font render modes:
364 [-\b-B\bB|-\b--\b-f\bfo\bon\bnt\bt-\b-s\bsm\bmo\boo\bot\bth\bhi\bin\bng\bg-\b-t\bth\bhr\bre\bes\bsh\bho\bol\bld\bd _\bs_\bi_\bz_\be]
366 (this gets ignored in 1.3 for now!)
368 This specifies the largest font size which will be rendered bitmapped,
369 that is, without any font smoothing. By default, no text is rendered
370 bitmapped.
374 All text in rrdtool is rendered using Pango. With the -\b--\b-p\bpa\ban\bng\bgo\bo-\b-m\bma\bar\brk\bku\bup\bp
375 option, all text will be processed by pango markup. This allows to
376 embed some simple html like markup tags using
378 <span key="value">text</span>
380 Apart from the verbose syntax, there are also the following short tags
381 available.
383 b Bold
384 big Makes font relatively larger, equivalent to <span size="larger">
385 i Italic
386 s Strikethrough
387 sub Subscript
388 sup Superscript
389 small Makes font relatively smaller, equivalent to <span size="smaller">
390 tt Monospace font
391 u Underline
393 More details on <http://developer.gnome.org/doc/API/2.0/pango/Pango-
394 MarkupFormat.html>.
396 [-\b-G\bG|-\b--\b-g\bgr\bra\bap\bph\bh-\b-r\bre\ben\bnd\bde\ber\br-\b-m\bmo\bod\bde\be {n\bno\bor\brm\bma\bal\bl,m\bmo\bon\bno\bo}]
398 There are 2 render modes:
406 RRDtool graphs are composed of stair case curves by default. This is in
407 line with the way RRDtool calculates its data. Some people favor a more
408 'organic' look for their graphs even though it is not all that true.
410 [-\b-a\ba|-\b--\b-i\bim\bmg\bgf\bfo\bor\brm\bma\bat\bt P\bPN\bNG\bG|S\bSV\bVG\bG|E\bEP\bPS\bS|P\bPD\bDF\bF]
412 Image format for the generated graph. For the vector formats you can
413 choose among the standard Postscript fonts Courier-Bold,
414 Courier-BoldOblique, Courier-Oblique, Courier, Helvetica-Bold, Hel-
415 vetica-BoldOblique, Helvetica-Oblique, Helvetica, Symbol, Times-Bold,
416 Times-BoldItalic, Times-Italic, Times-Roman, and ZapfDingbats.
420 (this gets ignored in 1.3 for now!)
422 If images are interlaced they become visible on browsers more quickly.
426 By default the tab-width is 40 pixels, use this option to change it.
430 If you are graphing memory (and NOT network traffic) this switch should
431 be set to 1024 so that one Kb is 1024 byte. For traffic measurement, 1
432 kb/s is 1000 b/s.
436 Adds the given string as a watermark, horizontally centered, at the
437 bottom of the graph.
441 D\bDE\bEF\bF:\b:_\bv_\bn_\ba_\bm_\be=\b=_\br_\br_\bd_\bf_\bi_\bl_\be:\b:_\bd_\bs_\b-_\bn_\ba_\bm_\be:\b:_\bC_\bF[:\b:s\bst\bte\bep\bp=\b=_\bs_\bt_\be_\bp][:\b:s\bst\bta\bar\brt\bt=\b=_\bt_\bi_\bm_\be][:\b:e\ben\bnd\bd=\b=_\bt_\bi_\bm_\be]
443 C\bCD\bDE\bEF\bF:\b:_\bv_\bn_\ba_\bm_\be=\b=_\bR_\bP_\bN _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn
445 V\bVD\bDE\bEF\bF:\b:_\bv_\bn_\ba_\bm_\be=\b=_\bR_\bP_\bN _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn
448 statements are useful but optional. See rrdgraph_data and rrdgraph_rpn
449 for the exact format.
453 You need at least one graph element to generate an image and/or at
454 least one print statement to generate a report. See rrdgraph_graph for
455 the exact format.
459 Calling rrdtool with the graphv option will return information in the
460 rrdtool info format. On the command line this means that all output
461 will be in key=value format. When used from the Perl and Ruby bindings
462 a hash pointer will be returned from the call.
464 When the filename '-' is given, the contents of the graph itself will
465 also be returned through this interface (hash key 'image'). On the com-
466 mand line the output will look like this:
468 print[0] = "0.020833"
469 print[1] = "0.0440833"
470 graph_left = 51
471 graph_top = 22
472 graph_width = 400
473 graph_height = 100
474 graph_start = 1232908800
475 graph_end = 1232914200
476 image_width = 481
477 image_height = 154
478 value_min = 0.0000000000e+00
479 value_max = 4.0000000000e-02
480 image = BLOB_SIZE:8196
481 [... 8196 bytes of image data ...]
483 There is more information returned than in the standard interface.
484 Especially the 'graph_*' keys are new. They help applications that want
485 to know what is where on the graph.
488 The following environment variables may be used to change the behavior
489 of "rrdtool graph":
492 If this environment variable is set it will have the same effect as
493 specifying the "--daemon" option on the command line. If both are
494 present, the command line argument takes precedence.
497 rrdgraph gives an overview of how r\brr\brd\bdt\bto\boo\bol\bl g\bgr\bra\bap\bph\bh works. rrdgraph_data
498 describes D\bDE\bEF\bF,C\bCD\bDE\bEF\bF and V\bVD\bDE\bEF\bF in detail. rrdgraph_rpn describes the R\bRP\bPN\bN
500 all of the graph and print functions.
502 Make sure to read rrdgraph_examples for tips&tricks.
505 Program by Tobias Oetiker <tobi@oetiker.ch>
507 This manual page by Alex van den Bogaerdt <alex@vandenbogaerdt.nl> with
508 corrections and/or additions by several people
512 1.3.99909060808 2009-05-21 RRDGRAPH(1)