![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdgraph.txt b/doc/rrdgraph.txt
index 51a0b5ffa3379e6184d7091399039f8e4d4d0b07..692d0fdb96953ba87bf48049bb215c8a3d4f3efe 100644 (file)
--- a/doc/rrdgraph.txt
+++ b/doc/rrdgraph.txt
O\bOP\bPT\bTI\bIO\bON\bNS\bS
g\bgr\bra\bap\bph\bhv\bv
- This alternate version of g\bgr\bra\bap\bph\bh takes the same arguments and per-
- forms the same function. The _\bv stands for _\bv_\be_\br_\bb_\bo_\bs_\be, which describes
- the output returned. g\bgr\bra\bap\bph\bhv\bv will return a lot of information about
- the graph using the same format as rrdtool info (key = value). See
- the bottom of the document for more information.
-
- filename
- The name and path of the graph to generate. It is recommended to
- end this in ".png", ".svg" or ".eps", but R\bRR\bRD\bDt\bto\boo\bol\bl does not enforce
- this.
-
- _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be can be '"-"' to send the image to "stdout". In this case,
- no other output is generated.
-
- Time range
- [-\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]
-
- The start and end of the time series you would like to display, and
- which R\bRR\bRA\bA the data should come from. Defaults are: 1 day ago until
- now, with the best possible resolution. S\bSt\bta\bar\brt\bt and e\ben\bnd\bd can be speci-
- fied in several formats, see AT-STYLE TIME SPECIFICATION and rrd-
- graph_examples. By default, r\brr\brd\bdt\bto\boo\bol\bl g\bgr\bra\bap\bph\bh calculates the width of
- one pixel in the time domain and tries to get data from an R\bRR\bRA\bA with
- that resolution. With the s\bst\bte\bep\bp option you can alter this
- behaviour. If you want r\brr\brd\bdt\bto\boo\bol\bl 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 3'600. Note: a step smaller
- than one pixel will silently be ignored.
-
- Labels
- [-\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]
-
- A horizontal string at the top of the graph and/or a vertically
- placed string at the left hand side of the graph.
-
- Size
- [-\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]
- [-\b-D\bD|-\b--\b-f\bfu\bul\bll\bl-\b-s\bsi\biz\bze\be-\b-m\bmo\bod\bde\be]
-
- By default, the width and height of the c\bca\ban\bnv\bva\bas\bs (the part with the
- actual data and such). This defaults to 400 pixels by 100 pixels.
-
- 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
- specify the final dimensions of the output image and the canvas is
- automatically resized to fit.
-
- If you specify the -\b--\b-o\bon\bnl\bly\by-\b-g\bgr\bra\bap\bph\bh option and set the height < 32 pix-
- els you will get a tiny graph image (thumbnail) to use as an icon
- for use in an overview, for example. All labeling will be stripped
- off the graph.
-
- Limits
- [-\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]
-
- By default the graph will be autoscaling so that it will adjust the
- y-axis to the range of the data. You can change this behaviour by
- explicitly setting the limits. The displayed y-axis will then range
- at 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 those boundaries to be stretched unless the r\bri\big\bgi\bid\bd option is
- set.
-
- [-\b-A\bA|-\b--\b-a\bal\blt\bt-\b-a\bau\but\bto\bos\bsc\bca\bal\ble\be]
-
- Sometimes the default algorithm for selecting the y-axis scale is
- not satisfactory. Normally the scale is selected from a predefined
- set of ranges and this fails miserably when you need to graph some-
- thing like "260 + 0.001 * sin(x)". This option calculates the mini-
- mum and maximum y-axis from the actual minimum and maximum data
- values. Our example would display slightly less than "260-0.001" to
- slightly more than "260+0.001" (this feature was contributed by
- Sasha Mikheev).
-
- [-\b-J\bJ|-\b--\b-a\bal\blt\bt-\b-a\bau\but\bto\bos\bsc\bca\bal\ble\be-\b-m\bmi\bin\bn]
-
- Where "--alt-autoscale" will modify both the absolute maximum AND
- minimum values, this option will only affect the minimum value. The
- maximum value, if not defined on the command line, will be 0. This
- option can be useful when graphing router traffic when the WAN line
- uses compression, and thus the throughput may be higher than the
- WAN line speed.
-
- [-\b-M\bM|-\b--\b-a\bal\blt\bt-\b-a\bau\but\bto\bos\bsc\bca\bal\ble\be-\b-m\bma\bax\bx]
-
- Where "--alt-autoscale" will modify both the absolute maximum AND
- minimum values, this option will only affect the maximum value. The
- minimum value, if not defined on the command line, will be 0. This
- option can be useful when graphing router traffic when the WAN line
- uses compression, and thus the throughput may be higher than the
- WAN line speed.
-
- [-\b-N\bN|-\b--\b-n\bno\bo-\b-g\bgr\bri\bid\bdf\bfi\bit\bt]
-
- In order to avoid anti-aliasing blurring effects rrdtool snaps
- points to device resolution pixels, this results in a crisper aper-
- ance. If this is not to your liking, you can use this switch to
- turn this behaviour off.
-
- Gridfitting is turned off for PDF, EPS, SVG output by default.
-
- Grid
- X-Axis
- [-\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]
-
- [-\b-x\bx|-\b--\b-x\bx-\b-g\bgr\bri\bid\bd n\bno\bon\bne\be]
-
- The x-axis label is quite complex to configure. If you don't
- have very special needs it is probably best to rely on the
- autoconfiguration to get this right. You can specify the string
- "none" to suppress the grid and labels altogether.
-
- The grid is defined by specifying a certain amount of time in
- the _\b?_\bT_\bM positions. You can choose from "SECOND", "MINUTE",
- "HOUR", "DAY", "WEEK", "MONTH" or "YEAR". Then you define how
- many of these should pass between each line or label. This
- pair (_\b?_\bT_\bM_\b:_\b?_\bS_\bT) needs to be specified for the base grid (_\bG_\b?_\b?),
- the major grid (_\bM_\b?_\b?) and the labels (_\bL_\b?_\b?). For the labels you
- also must define a precision in _\bL_\bP_\bR and a _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be format
- string in _\bL_\bF_\bM. _\bL_\bP_\bR defines where each label will be placed. If
- it is zero, the label will be placed right under the corre-
- sponding line (useful for hours, dates etcetera). If you spec-
- ify a number of seconds here the label is centered on this
- interval (useful for Monday, January etcetera).
-
- --x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X
-
- This places grid lines every 10 minutes, major grid lines every
- hour, and labels every 4 hours. The labels are placed under the
- major grid lines as they specify exactly that time.
-
- --x-grid HOUR:8:DAY:1:DAY:1:86400:%A
-
- This places grid lines every 8 hours, major grid lines and
- labels each day. The labels are placed exactly between two
- major grid lines as they specify the complete day and not just
- midnight.
-
- Y-Axis
- [-\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]
-
- [-\b-y\by|-\b--\b-y\by-\b-g\bgr\bri\bid\bd n\bno\bon\bne\be]
-
- Y-axis grid lines appear at each _\bg_\br_\bi_\bd _\bs_\bt_\be_\bp interval. Labels
- are placed every _\bl_\ba_\bb_\be_\bl _\bf_\ba_\bc_\bt_\bo_\br lines. You can specify "-y none"
- to suppress the grid and labels altogether. The default for
- this option is to automatically select sensible values.
-
- If you have set --y-grid to 'none' not only the labels get
- supressed, also the space reserved for the labels is removed.
- You can still add space manually if you use the --units-length
- command to explicitly reserve space.
-
- [-\b-Y\bY|-\b--\b-a\bal\blt\bt-\b-y\by-\b-g\bgr\bri\bid\bd]
-
- Place the Y grid dynamically based on the graph's Y range. The
- algorithm ensures that you always have a grid, that there are
- enough but not too many grid lines, and that the grid is met-
- ric. That is the grid lines are placed every 1, 2, 5 or 10
- units. This parameter will also ensure that you get enough dec-
- imals displayed even if your graph goes from 69.998 to 70.001.
- (contributed by Sasha Mikheev).
- [-\b-o\bo|-\b--\b-l\blo\bog\bga\bar\bri\bit\bth\bhm\bmi\bic\bc]
-
- Logarithmic y-axis scaling.
-
- [-\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]
-
- This sets the 10**exponent scaling of the y-axis values. Nor-
- mally, values will be scaled to the appropriate units (k, M,
- etc.). However, you may wish to display units always in k
- (Kilo, 10e3) even if the data is in the M (Mega, 10e6) range,
- for instance. Value should be an integer which is a multiple of
- 3 between -18 and 18 inclusively. It is the exponent on the
- units you wish to use. For example, use 3 to display the y-axis
- values in k (Kilo, 10e3, thousands), use -6 to display the
- y-axis values in u (Micro, 10e-6, millionths). Use a value of
- 0 to prevent any scaling of the y-axis values.
+ This alternate version of g\bgr\bra\bap\bph\bh takes the same arguments and performs
+ the same function. The _\bv stands for _\bv_\be_\br_\bb_\bo_\bs_\be, which describes the output
+ returned. g\bgr\bra\bap\bph\bhv\bv will return a lot of information about the graph using
+ the same format as rrdtool info (key = value). See the bottom of the
+ document for more information.
- This option is very effective at confusing the heck out of the
- default rrdtool autoscaler and grid painter. If rrdtool detects
- that it is not successful in labeling the graph under the given
- circumstances, it will switch to the more robust -\b--\b-a\bal\blt\bt-\b-y\by-\b-g\bgr\bri\bid\bd
- mode.
+ _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
- [-\b-L\bL|-\b--\b-u\bun\bni\bit\bts\bs-\b-l\ble\ben\bng\bgt\bth\bh _\bv_\ba_\bl_\bu_\be]
+ The name and path of the graph to generate. It is recommended to end
+ this in ".png", ".svg" or ".eps", but R\bRR\bRD\bDt\bto\boo\bol\bl does not enforce this.
- How many digits should rrdtool assume the y-axis labels to be?
- You may have to use this option to make enough space once you
- start fideling with the y-axis labeling.
+ _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be can be '"-"' to send the image to "stdout". In this case, no
+ other output is generated.
- [-\b--\b-u\bun\bni\bit\bts\bs=\b=s\bsi\bi]
+ T\bTi\bim\bme\be r\bra\ban\bng\bge\be
- With this option y-axis values on logarithmic graphs will be
- scaled to the appropriate units (k, M, etc.) instead of using
- exponential notation. Note that for linear graphs, SI notation
- is used by default.
+ [-\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]
- Miscellaneous
- [-\b-z\bz|-\b--\b-l\bla\baz\bzy\by]
+ The start and end of the time series you would like to display, and
+ which R\bRR\bRA\bA the data should come from. Defaults are: 1 day ago until
+ now, with the best possible resolution. S\bSt\bta\bar\brt\bt and e\ben\bnd\bd can be specified
+ in several formats, see AT-STYLE TIME SPECIFICATION and rrdgraph_exam-
+ ples. By default, r\brr\brd\bdt\bto\boo\bol\bl g\bgr\bra\bap\bph\bh calculates the width of one pixel in
+ the time domain and tries to get data from an R\bRR\bRA\bA with that resolution.
+ With the s\bst\bte\bep\bp option you can alter this behaviour. If you want r\brr\brd\bdt\bto\boo\bol\bl
+ 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
+ 3'600. Note: a step smaller than one pixel will silently be ignored.
- Only generate the graph if the current graph is out of date or not
- existent.
+ L\bLa\bab\bbe\bel\bls\bs
- [-\b-f\bf|-\b--\b-i\bim\bmg\bgi\bin\bnf\bfo\bo _\bp_\br_\bi_\bn_\bt_\bf_\bs_\bt_\br]
+ [-\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]
- After the image has been created, the graph function uses printf
- together with this format string to create output similar to the
- PRINT function, only that the printf function is supplied with the
- parameters _\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 including the graph into a web page, the command
- line would look like this:
+ A horizontal string at the top of the graph and/or a vertically placed
+ string at the left hand side of the graph.
- --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
+Right Axis
+[-\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]
- [-\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]]
+A second axis will be drawn to the right of the graph. It is tied to the left
+axis via the scale and shift parameters. You can also define a label for the
+right axis.
- Override the default colors for the standard elements of the graph.
- The _\bC_\bO_\bL_\bO_\bR_\bT_\bA_\bG is one of "BACK" background, "CANVAS" for the back-
- ground of the actual graph, "SHADEA" for the left and top border,
- "SHADEB" for the right and bottom border, "GRID", "MGRID" for the
- major grid, "FONT" for the color of the font, "AXIS" for the axis
- of the graph, "FRAME" for the line around the color spots and
- finally "ARROW" for the arrow head pointing up and forward. Each
- color is composed out of three hexadecimal numbers specifying its
- rgb color component (00 is off, FF is maximum) of red, green and
- blue. Optionally you may add another hexadecimal number specifying
- the transparency (FF is solid). You may set this option several
- times to alter multiple defaults.
+[-\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]
- A green arrow is made by: "--color ARROW#00FF00"
+By default the format of the axis lables gets determined automatically. If you
+want todo this your self, use this option with the same %lf arguments you know
+from the PRING and GPRINT commands.
- [-\b--\b-z\bzo\boo\bom\bm _\bf_\ba_\bc_\bt_\bo_\br]
+S\bSi\biz\bze\be
- Zoom the graphics by the given amount. The factor must be > 0
+[-\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]
+[-\b-D\bD|-\b--\b-f\bfu\bul\bll\bl-\b-s\bsi\biz\bze\be-\b-m\bmo\bod\bde\be]
- [-\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]]
+By default, the width and height of the c\bca\ban\bnv\bva\bas\bs (the part with the actual data
+and such). This defaults to 400 pixels by 100 pixels.
- This lets you customize which font to use for the various text ele-
- ments on the RRD graphs. "DEFAULT" sets the default value for all
- elements, "TITLE" for the title, "AXIS" for the axis labels, "UNIT"
- for the vertical unit label, "LEGEND" for the graph legend.
+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 specify the
+final dimensions of the output image and the canvas is automatically resized
+to fit.
- Use Times for the title: "--font TITLE:13:Times"
+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 you will
+get a tiny graph image (thumbnail) to use as an icon for use in an overview,
+for example. All labeling will be stripped off the graph.
- If you do not give a font string you can modify just the sice of
- the default font: "--font TITLE:13:".
+L\bLi\bim\bmi\bit\bts\bs
- If you specify the size 0 then you can modify just the font without
- touching the size. This is especially usefull for altering the
- default font without resetting the default fontsizes: "--font
- DEFAULT:0:Courier".
+[-\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]
- RRDtool comes with a preset default font. You can set the environ-
- ment variable "RRD_DEFAULT_FONT" if you want to change this.
+By default the graph will be autoscaling so that it will adjust the y-axis to
+the range of the data. You can change this behaviour by explicitly setting the
+limits. The displayed y-axis will then range at 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 those boundaries to be stretched
+unless the r\bri\big\bgi\bid\bd option is set.
- RRDtool uses Pango for its font handling. This means you can to use
- the full Pango syntax when selecting your font:
+[-\b-A\bA|-\b--\b-a\bal\blt\bt-\b-a\bau\but\bto\bos\bsc\bca\bal\ble\be]
- 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]",
- where _\bF_\bA_\bM_\bI_\bL_\bY_\b-_\bL_\bI_\bS_\bT is a comma separated list of families optionally
- terminated by a comma, _\bS_\bT_\bY_\bL_\bE_\b__\bO_\bP_\bT_\bI_\bO_\bN_\bS is a whitespace separated list
- of words where each WORD describes one of style, variant, weight,
- stretch, or gravity, and _\bS_\bI_\bZ_\bE is a decimal number (size in points)
- or optionally followed by the unit modifier "px" for absolute size.
- Any one of the options may be absent.
+Sometimes the default algorithm for selecting the y-axis scale is not satis-
+factory. Normally the scale is selected from a predefined set of ranges and
+this fails miserably when you need to graph something like "260 + 0.001 *
+sin(x)". This option calculates the minimum and maximum y-axis from the actual
+minimum and maximum data values. Our example would display slightly less than
+"260-0.001" to slightly more than "260+0.001" (this feature was contributed by
+Sasha Mikheev).
- [-\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}]
+[-\b-J\bJ|-\b--\b-a\bal\blt\bt-\b-a\bau\but\bto\bos\bsc\bca\bal\ble\be-\b-m\bmi\bin\bn]
- There are 3 font render modes:
+Where "--alt-autoscale" will modify both the absolute maximum AND minimum
+values, this option will only affect the minimum value. The maximum value, if
+not defined on the command line, will be 0. This option can be useful when
+graphing router traffic when the WAN line uses compression, and thus the
+throughput may be higher than the WAN line speed.
- n\bno\bor\brm\bma\bal\bl: Full Hinting and Antialiasing (default)
+[-\b-M\bM|-\b--\b-a\bal\blt\bt-\b-a\bau\but\bto\bos\bsc\bca\bal\ble\be-\b-m\bma\bax\bx]
- l\bli\big\bgh\bht\bt: Slight Hinting and Antialiasing
+Where "--alt-autoscale" will modify both the absolute maximum AND minimum val-
+ues, this option will only affect the maximum value. The minimum value, if not
+defined on the command line, will be 0. This option can be useful when graph-
+ing router traffic when the WAN line uses compression, and thus the throughput
+may be higher than the WAN line speed.
- m\bmo\bon\bno\bo: Full Hinting and NO Antialiasing
+[-\b-N\bN|-\b--\b-n\bno\bo-\b-g\bgr\bri\bid\bdf\bfi\bit\bt]
- [-\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]
+In order to avoid anti-aliasing blurring effects rrdtool snaps points to
+device resolution pixels, this results in a crisper aperance. If this is not
+to your liking, you can use this switch to turn this behaviour off.
- (this gets ignored in 1.3 for now!)
+Gridfitting is turned off for PDF, EPS, SVG output by default.
- This specifies the largest font size which will be rendered
- bitmapped, that is, without any font smoothing. By default, no text
- is rendered bitmapped.
+G\bGr\bri\bid\bd
- [-\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}]
- There are 2 render modes:
+X-Axis
+ [-\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]
- n\bno\bor\brm\bma\bal\bl: Graphs are fully Antialiased (default)
+ [-\b-x\bx|-\b--\b-x\bx-\b-g\bgr\bri\bid\bd n\bno\bon\bne\be]
- m\bmo\bon\bno\bo: No Antialiasing
+ The x-axis label is quite complex to configure. If you don't have very
+ special needs it is probably best to rely on the autoconfiguration to get
+ this right. You can specify the string "none" to suppress the grid and
+ labels altogether.
- [-\b-E\bE|-\b--\b-s\bsl\blo\bop\bpe\be-\b-m\bmo\bod\bde\be]
+ The grid is defined by specifying a certain amount of time in the _\b?_\bT_\bM
+ positions. You can choose from "SECOND", "MINUTE", "HOUR", "DAY", "WEEK",
+ "MONTH" or "YEAR". Then you define how many of these should pass between
+ each line or label. This pair (_\b?_\bT_\bM_\b:_\b?_\bS_\bT) needs to be specified for the
+ base grid (_\bG_\b?_\b?), the major grid (_\bM_\b?_\b?) and the labels (_\bL_\b?_\b?). For the labels
+ you also must define a precision in _\bL_\bP_\bR and a _\bs_\bt_\br_\bf_\bt_\bi_\bm_\be format string in
+ _\bL_\bF_\bM. _\bL_\bP_\bR defines where each label will be placed. If it is zero, the
+ label will be placed right under the corresponding line (useful for hours,
+ dates etcetera). If you specify a number of seconds here the label is
+ centered on this interval (useful for Monday, January etcetera).
- RRDtool graphs are composed of stair case curves by default. This
- is in line with the way RRDtool calculates its data. Some people
- favor a more 'organic' look for their graphs even though it is not
- all that true.
+ --x-grid MINUTE:10:HOUR:1:HOUR:4:0:%X
- [-\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]
+ This places grid lines every 10 minutes, major grid lines every hour, and
+ labels every 4 hours. The labels are placed under the major grid lines as
+ they specify exactly that time.
- Image format for the generated graph. For the vector formats you
- can choose among the standard Postscript fonts Courier-Bold,
- Courier-BoldOblique, Courier-Oblique, Courier, Helvetica-Bold, Hel-
- vetica-BoldOblique, Helvetica-Oblique, Helvetica, Symbol,
- Times-Bold, Times-BoldItalic, Times-Italic, Times-Roman, and ZapfD-
- ingbats.
+ --x-grid HOUR:8:DAY:1:DAY:1:86400:%A
- [-\b-i\bi|-\b--\b-i\bin\bnt\bte\ber\brl\bla\bac\bce\bed\bd]
+ This places grid lines every 8 hours, major grid lines and labels each
+ day. The labels are placed exactly between two major grid lines as they
+ specify the complete day and not just midnight.
- (this gets ignored in 1.3 for now!)
+Y-Axis
+ [-\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]
- If images are interlaced they become visible on browsers more
- quickly.
+ [-\b-y\by|-\b--\b-y\by-\b-g\bgr\bri\bid\bd n\bno\bon\bne\be]
- [-\b-g\bg|-\b--\b-n\bno\bo-\b-l\ble\beg\bge\ben\bnd\bd]
+ Y-axis grid lines appear at each _\bg_\br_\bi_\bd _\bs_\bt_\be_\bp interval. Labels are placed
+ every _\bl_\ba_\bb_\be_\bl _\bf_\ba_\bc_\bt_\bo_\br lines. You can specify "-y none" to suppress the grid
+ and labels altogether. The default for this option is to automatically
+ select sensible values.
- Suppress generation of the legend; only render the graph.
+ If you have set --y-grid to 'none' not only the labels get supressed, also
+ the space reserved for the labels is removed. You can still add space man-
+ ually if you use the --units-length command to explicitly reserve space.
- [-\b-F\bF|-\b--\b-f\bfo\bor\brc\bce\be-\b-r\bru\bul\ble\bes\bs-\b-l\ble\beg\bge\ben\bnd\bd]
+ [-\b-Y\bY|-\b--\b-a\bal\blt\bt-\b-y\by-\b-g\bgr\bri\bid\bd]
- Force the generation of HRULE and VRULE legends even if those HRULE
- or VRULE will not be drawn because out of graph boundaries (mimics
- behaviour of pre 1.0.42 versions).
+ Place the Y grid dynamically based on the graph's Y range. The algorithm
+ ensures that you always have a grid, that there are enough but not too
+ many grid lines, and that the grid is metric. That is the grid lines are
+ placed every 1, 2, 5 or 10 units. This parameter will also ensure that you
+ get enough decimals displayed even if your graph goes from 69.998 to
+ 70.001. (contributed by Sasha Mikheev).
- [-\b-T\bT|-\b--\b-t\bta\bab\bbw\bwi\bid\bdt\bth\bh _\bv_\ba_\bl_\bu_\be]
+ [-\b-o\bo|-\b--\b-l\blo\bog\bga\bar\bri\bit\bth\bhm\bmi\bic\bc]
- By default the tab-width is 40 pixels, use this option to change
- it.
+ Logarithmic y-axis scaling.
- [-\b-b\bb|-\b--\b-b\bba\bas\bse\be _\bv_\ba_\bl_\bu_\be]
+ [-\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]
- If you are graphing memory (and NOT network traffic) this switch
- should be set to 1024 so that one Kb is 1024 byte. For traffic mea-
- surement, 1 kb/s is 1000 b/s.
+ This sets the 10**exponent scaling of the y-axis values. Normally, values
+ will be scaled to the appropriate units (k, M, etc.). However, you may
+ wish to display units always in k (Kilo, 10e3) even if the data is in the
+ M (Mega, 10e6) range, for instance. Value should be an integer which is a
+ multiple of 3 between -18 and 18 inclusively. It is the exponent on the
+ units you wish to use. For example, use 3 to display the y-axis values in
+ k (Kilo, 10e3, thousands), use -6 to display the y-axis values in u
+ (Micro, 10e-6, millionths). Use a value of 0 to prevent any scaling of
+ the y-axis values.
- [-\b-W\bW|-\b--\b-w\bwa\bat\bte\ber\brm\bma\bar\brk\bk _\bs_\bt_\br_\bi_\bn_\bg]
+ This option is very effective at confusing the heck out of the default
+ rrdtool autoscaler and grid painter. If rrdtool detects that it is not
+ successful in labeling the graph under the given circumstances, it will
+ switch to the more robust -\b--\b-a\bal\blt\bt-\b-y\by-\b-g\bgr\bri\bid\bd mode.
- Adds the given string as a watermark, horizontally centred, at the
- bottom of the graph.
+ [-\b-L\bL|-\b--\b-u\bun\bni\bit\bts\bs-\b-l\ble\ben\bng\bgt\bth\bh _\bv_\ba_\bl_\bu_\be]
- Data and variables
- 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]
+ How many digits should rrdtool assume the y-axis labels to be? You may
+ have to use this option to make enough space once you start fideling with
+ the y-axis labeling.
- 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
+ [-\b--\b-u\bun\bni\bit\bts\bs=\b=s\bsi\bi]
- 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
+ With this option y-axis values on logarithmic graphs will be scaled to the
+ appropriate units (k, M, etc.) instead of using exponential notation.
+ Note that for linear graphs, SI notation is used by default.
- You need at least one D\bDE\bEF\bF statement to generate anything. The other
- statements are useful but optional. See rrdgraph_data and rrd-
- graph_rpn for the exact format.
+M\bMi\bis\bsc\bce\bel\bll\bla\ban\bne\beo\bou\bus\bs
- Graph and print elements
- You need at least one graph element to generate an image and/or at
- least one print statement to generate a report. See rrdgraph_graph
- for the exact format.
+[-\b-z\bz|-\b--\b-l\bla\baz\bzy\by]
- Markup
- All text in rrdtool is rendered using Pango markup. This means text
- can contain embeded markup instructions. Simple html markup using
+Only generate the graph if the current graph is out of date or not existent.
+Note, that only the image size will be returned, if you run with lazy even
+when using graphv and even when using PRINT.
- <span key="value">text</span>
+[-\b-f\bf|-\b--\b-i\bim\bmg\bgi\bin\bnf\bfo\bo _\bp_\br_\bi_\bn_\bt_\bf_\bs_\bt_\br]
- can be used. Apart from the verbose syntax, there are also the fol-
- lowing short tags available.
+After the image has been created, the graph function uses printf together with
+this format string to create output similar to the PRINT function, only that
+the printf function is supplied with the parameters _\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 including the graph into a web
+page, the command line would look like this:
- b Bold
- big Makes font relatively larger, equivalent to <span size="larger">
- i Italic
- s Strikethrough
- sub Subscript
- sup Superscript
- small Makes font relatively smaller, equivalent to <span size="smaller">
- tt Monospace font
- u Underline
+ --imginfo '<IMG SRC="/img/%s" WIDTH="%lu" HEIGHT="%lu" ALT="Demo">'
- More details on http://developer.gnome.org/doc/API/2.0/pango/Pango-
- MarkupFormat.html.
+[-\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]]
- g\bgr\bra\bap\bph\bhv\bv
+Override the default colors for the standard elements of the graph. The _\bC_\bO_\bL_\b-
+_\bO_\bR_\bT_\bA_\bG is one of "BACK" background, "CANVAS" for the background of the actual
+graph, "SHADEA" for the left and top border, "SHADEB" for the right and bottom
+border, "GRID", "MGRID" for the major grid, "FONT" for the color of the font,
+"AXIS" for the axis of the graph, "FRAME" for the line around the color spots,
+and finally "ARROW" for the arrow head pointing up and forward. Each color is
+composed out of three hexadecimal numbers specifying its rgb color component
+(00 is off, FF is maximum) of red, green and blue. Optionally you may add
+another hexadecimal number specifying the transparency (FF is solid). You may
+set this option several times to alter multiple defaults.
+
+A green arrow is made by: "--color ARROW#00FF00"
+
+[-\b--\b-z\bzo\boo\bom\bm _\bf_\ba_\bc_\bt_\bo_\br]
+
+Zoom the graphics by the given amount. The factor must be > 0
+
+[-\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]]
+
+This lets you customize which font to use for the various text elements on the
+RRD graphs. "DEFAULT" sets the default value for all elements, "TITLE" for the
+title, "AXIS" for the axis labels, "UNIT" for the vertical unit label, "LEG-
+END" for the graph legend, "WATERMARK" for the watermark on the edge of the
+graph.
+
+Use Times for the title: "--font TITLE:13:Times"
+
+If you do not give a font string you can modify just the sice of the default
+font: "--font TITLE:13:".
+
+If you specify the size 0 then you can modify just the font without touching
+the size. This is especially usefull for altering the default font without
+resetting the default fontsizes: "--font DEFAULT:0:Courier".
+
+RRDtool comes with a preset default font. You can set the environment variable
+"RRD_DEFAULT_FONT" if you want to change this.
+
+RRDtool uses Pango for its font handling. This means you can to use the full
+Pango syntax when selecting your font:
+
+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]", where _\bF_\bA_\bM_\b-
+_\bI_\bL_\bY_\b-_\bL_\bI_\bS_\bT is a comma separated list of families optionally terminated by a
+comma, _\bS_\bT_\bY_\bL_\bE_\b__\bO_\bP_\bT_\bI_\bO_\bN_\bS is a whitespace separated list of words where each WORD
+describes one of style, variant, weight, stretch, or gravity, and _\bS_\bI_\bZ_\bE is a
+decimal number (size in points) or optionally followed by the unit modifier
+"px" for absolute size. Any one of the options may be absent.
+
+[-\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}]
+
+There are 3 font render modes:
+
+n\bno\bor\brm\bma\bal\bl: Full Hinting and Antialiasing (default)
+
+l\bli\big\bgh\bht\bt: Slight Hinting and Antialiasing
+
+m\bmo\bon\bno\bo: Full Hinting and NO Antialiasing
+
+[-\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]
+
+(this gets ignored in 1.3 for now!)
+
+This specifies the largest font size which will be rendered bitmapped, that
+is, without any font smoothing. By default, no text is rendered bitmapped.
+
+[-\b-P\bP|-\b--\b-p\bpa\ban\bng\bgo\bo-\b-m\bma\bar\brk\bku\bup\bp]
+
+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 option,
+all text will be processed by pango markup. This allows to embed some simple
+html like markup tags using
+
+ <span key="value">text</span>
+
+Apart from the verbose syntax, there are also the following short tags avail-
+able.
+
+ b Bold
+ big Makes font relatively larger, equivalent to <span size="larger">
+ i Italic
+ s Strikethrough
+ sub Subscript
+ sup Superscript
+ small Makes font relatively smaller, equivalent to <span size="smaller">
+ tt Monospace font
+ u Underline
+
+More details on <http://developer.gnome.org/doc/API/2.0/pango/PangoMarkupFor-
+mat.html>.
+
+[-\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}]
+
+There are 2 render modes:
+
+n\bno\bor\brm\bma\bal\bl: Graphs are fully Antialiased (default)
+
+m\bmo\bon\bno\bo: No Antialiasing
+
+[-\b-E\bE|-\b--\b-s\bsl\blo\bop\bpe\be-\b-m\bmo\bod\bde\be]
+
+RRDtool graphs are composed of stair case curves by default. This is in line
+with the way RRDtool calculates its data. Some people favor a more 'organic'
+look for their graphs even though it is not all that true.
+
+[-\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]
+
+Image format for the generated graph. For the vector formats you can choose
+among the standard Postscript fonts Courier-Bold, Courier-BoldOblique,
+Courier-Oblique, Courier, Helvetica-Bold, Helvetica-BoldOblique, Hel-
+vetica-Oblique, Helvetica, Symbol, Times-Bold, Times-BoldItalic, Times-Italic,
+Times-Roman, and ZapfDingbats.
+
+[-\b-i\bi|-\b--\b-i\bin\bnt\bte\ber\brl\bla\bac\bce\bed\bd]
+
+(this gets ignored in 1.3 for now!)
+
+If images are interlaced they become visible on browsers more quickly.
+
+[-\b-g\bg|-\b--\b-n\bno\bo-\b-l\ble\beg\bge\ben\bnd\bd]
+
+Suppress generation of the legend; only render the graph.
+
+[-\b-F\bF|-\b--\b-f\bfo\bor\brc\bce\be-\b-r\bru\bul\ble\bes\bs-\b-l\ble\beg\bge\ben\bnd\bd]
+
+Force the generation of HRULE and VRULE legends even if those HRULE or VRULE
+will not be drawn because out of graph boundaries (mimics behaviour of pre
+1.0.42 versions).
+
+[-\b-T\bT|-\b--\b-t\bta\bab\bbw\bwi\bid\bdt\bth\bh _\bv_\ba_\bl_\bu_\be]
+
+By default the tab-width is 40 pixels, use this option to change it.
+
+[-\b-b\bb|-\b--\b-b\bba\bas\bse\be _\bv_\ba_\bl_\bu_\be]
+
+If you are graphing memory (and NOT network traffic) this switch should be set
+to 1024 so that one Kb is 1024 byte. For traffic measurement, 1 kb/s is 1000
+b/s.
+
+[-\b-W\bW|-\b--\b-w\bwa\bat\bte\ber\brm\bma\bar\brk\bk _\bs_\bt_\br_\bi_\bn_\bg]
+
+Adds the given string as a watermark, horizontally centred, at the bottom of
+the graph.
+
+D\bDa\bat\bta\ba a\ban\bnd\bd v\bva\bar\bri\bia\bab\bbl\ble\bes\bs
+
+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]
+
+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
+
+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
+
+You need at least one D\bDE\bEF\bF statement to generate anything. The other statements
+are useful but optional. See rrdgraph_data and rrdgraph_rpn for the exact
+format.
+
+NOTE: G\bGr\bra\bap\bph\bh a\ban\bnd\bd p\bpr\bri\bin\bnt\bt e\bel\ble\bem\bme\ben\bnt\bts\bs
+
+You need at least one graph element to generate an image and/or at least one
+print statement to generate a report. See rrdgraph_graph for the exact for-
+mat.
+
+g\bgr\bra\bap\bph\bhv\bv
+
+Calling rrdtool with the graphv option will return information in the rrdtool
+info format. On the command line this means that all output will be in
+key=value format. When used from the perl and ruby bindings a hash pointer
+will be returned from the call.
+
+When the filename '-' is given, the contents of the graph itself will also be
+returned through this interface (hash key 'image'). On the command line the
+output will look like this:
+
+ print[0] = "0.020833"
+ print[1] = "0.0440833"
+ graph_left = 51
+ graph_top = 22
+ graph_width = 400
+ graph_height = 100
+ image_width = 481
+ image_height = 154
+ value_min = 0.0000000000e+00
+ value_max = 4.0000000000e-02
+ image = BLOB_SIZE:8196
+ [... 8196 bytes of image data ...]
- Calling rrdtool with the graphv option will return information in the
- rrdtool info format. On the command line this means that all output
- will be in key=value format. When used from the perl and ruby bindings
- a hash pointer will be returned from the call.
-
- When the filename '-' is given, the contents of the graph itself will
- also be returned through this interface (hash key 'image'). On the com-
- mand line the output will look like this:
-
- print[0] = "0.020833"
- print[1] = "0.0440833"
- graph_left = 51
- graph_top = 22
- graph_width = 400
- graph_height = 100
- image_width = 481
- image_height = 154
- value_min = 0.0000000000e+00
- value_max = 4.0000000000e-02
- image = BLOB_SIZE:8196
- [... 8196 bytes of image data ...]
-
- There is more information returned than in the standard interface.
- Especially the 'graph_*' keys are new. They help applications that want
- to know what is where on the graph.
+There is more information returned than in the standard interface. Especially
+the 'graph_*' keys are new. They help applications that want to know what is
+where on the graph.
S\bSE\bEE\bE A\bAL\bLS\bSO\bO
rrdgraph gives an overview of how r\brr\brd\bdt\bto\boo\bol\bl g\bgr\bra\bap\bph\bh works. rrdgraph_data
-1.3rc4 2008-04-21 RRDGRAPH(1)
+1.3.5 2008-12-09 RRDGRAPH(1)