RRDGRAPH(1) RRDtool RRDGRAPH(1)
NNAAMMEE
rrdgraph - Create a graph based on data from one or several RRD
SSYYNNOOPPSSIISS
rrrrddttooooll ggrraapphh _f_i_l_e_n_a_m_e [--ss|----ssttaarrtt _s_e_c_o_n_d_s] [--ee|----eenndd _s_e_c_o_n_d_s]
[--xx|----xx--ggrriidd _x_-_a_x_i_s _g_r_i_d _a_n_d _l_a_b_e_l] [--yy|----yy--ggrriidd _y_-_a_x_i_s _g_r_i_d _a_n_d _l_a_b_e_l]
[--YY|----aalltt--yy--ggrriidd] [--RR|----aalltt--yy--mmrrttgg] [--AA|----aalltt--aauuttoossccaallee]
[--MM|----aalltt--aauuttoossccaallee--mmaaxx] [--NN|----nnoo--mmiinnoorr] [--XX|----uunniittss--eexxppoonneenntt] _v_a_l_u_e]>
[--LL|----uunniittss--lleennggtthh] _v_a_l_u_e]> [--vv|----vveerrttiiccaall--llaabbeell _t_e_x_t]
[--ww|----wwiiddtthh _p_i_x_e_l_s] [--hh|----hheeiigghhtt _p_i_x_e_l_s] [--ii|----iinntteerrllaacceedd]
[--ff|----iimmggiinnffoo _f_o_r_m_a_t_s_t_r_i_n_g] [--aa|----iimmggffoorrmmaatt GGIIFF|PPNNGG|GGDD]
[--BB|----bbaacckkggrroouunndd _v_a_l_u_e] [--OO|----oovveerrllaayy _v_a_l_u_e] [--UU|----uunniitt _v_a_l_u_e]
[--zz|----llaazzyy] [--oo|----llooggaarriitthhmmiicc] [--uu|----uuppppeerr--lliimmiitt _v_a_l_u_e]
[--ll|----lloowweerr--lliimmiitt _v_a_l_u_e] [--gg|----nnoo--lleeggeenndd] [--jj|----oonnllyy--ggrraapphh]
[--FF|----ffoorrccee--rruulleess--lleeggeenndd] [--rr|----rriiggiidd] [--SS|----sstteepp _v_a_l_u_e]
[--bb|----bbaassee _v_a_l_u_e] [--cc|----ccoolloorr _C_O_L_O_R_T_A_G##_r_r_g_g_b_b] [--tt|----ttiittllee _t_i_t_l_e]
[DDEEFF::_v_n_a_m_e==_r_r_d::_d_s_-_n_a_m_e::_C_F] [CCDDEEFF::_v_n_a_m_e==_r_p_n_-_e_x_p_r_e_s_s_i_o_n]
[PPRRIINNTT::_v_n_a_m_e::_C_F::_f_o_r_m_a_t] [GGPPRRIINNTT::_v_n_a_m_e::_C_F::_f_o_r_m_a_t] [CCOOMMMMEENNTT::_t_e_x_t]
[HHRRUULLEE::_v_a_l_u_e##_r_r_g_g_b_b[::_l_e_g_e_n_d]] [VVRRUULLEE::_t_i_m_e##_r_r_g_g_b_b[::_l_e_g_e_n_d]]
[LLIINNEE{11|22|33}::_v_n_a_m_e[##_r_r_g_g_b_b[::_l_e_g_e_n_d]]] [AARREEAA::_v_n_a_m_e[##_r_r_g_g_b_b[::_l_e_g_e_n_d]]]
[SSTTAACCKK::_v_n_a_m_e[##_r_r_g_g_b_b[::_l_e_g_e_n_d]]]
DDEESSCCRRIIPPTTIIOONN
The ggrraapphh functions main purpose is to create graphical representations
of the data stored in one or several RRRRDDs. Apart from generating
graphs, it can also extract numerical reports.
_f_i_l_e_n_a_m_e
The name of the graph to generate. Since RRRRDDTTooooll outputs GIFs and
PNGs, it's recommended that the filename end in either _._g_i_f or
_._p_n_g. RRRRDDTTooooll does not enforce this, however. If the _f_i_l_e_n_a_m_e is
set to '-' the image file will be written to standard out. All
other output will get suppressed.
PNG output is recommended, since it takes up to 40% less disk space
and 20-30% less time to generate than a GIF file.
If no graph functions are called, the graph will not be created.
--ss|----ssttaarrtt _s_e_c_o_n_d_s (default end-1day)
The time when the graph should begin. Time in seconds since epoch
(1970-01-01) is required. Negative numbers are relative to the
current time. By default one day worth of data will be graphed.
See also AT-STYLE TIME SPECIFICATION section in the _r_r_d_f_e_t_c_h
documentation for a detailed explanation on how to specify time.
--ee|----eenndd _s_e_c_o_n_d_s (default now)
The time when the graph should end. Time in seconds since epoch.
See also AT-STYLE TIME SPECIFICATION section in the _r_r_d_f_e_t_c_h
documentation for a detailed explanation of ways to specify time.
--xx|----xx--ggrriidd _x_-_a_x_i_s _g_r_i_d _a_n_d _l_a_b_e_l (default autoconfigure)
The x-axis label is quite complex to configure. So if you don't
have very special needs, you can rely on the autoconfiguration to
get this right.
If you want no x-grid at all, use the magic setting nnoonnee.
The x-axis label and grid can be configured, using the following
format:
_G_T_M::_G_S_T::_M_T_M::_M_S_T::_L_T_M:_L_S_T::_L_P_R::_L_F_M
You have to configure three elements making up the x-axis labels
and grid. The base grid (_G_?_?), the major grid (_M_?_?) and the labels
(_L_?_?). The configuration is based on the idea that you first
specify a well known amount of time (_?_T_M) and then say how many
times it has to pass between each grid line or label (_?_S_T). For the
label you have to define two additional items: The precision of the
label in seconds (_L_P_R) and the strftime format used to generate the
text of the label (_L_F_M).
The _?_T_M elements must be one of the following keywords: SSEECCOONNDD,
MMIINNUUTTEE, HHOOUURR, DDAAYY, WWEEEEKK, MMOONNTTHH or YYEEAARR.
If you wanted a graph with a base grid every 10 minutes and a major
one every hour, with labels every hour you would use the following
x-axis definition.
"MINUTE:10:HOUR:1:HOUR:1:0:%X"
The precision in this example is 0 because the %X format is exact.
If the label was the name of the day, we would have had a precision
of 24 hours, because when you say something like 'Monday' you mean
the whole day and not Monday morning 00:00. Thus the label should
be positioned at noon. By defining a precision of 24 hours or
rather 86400 seconds, you make sure that this happens.
If you want to alter the generated text to another language, use
the LC_TIME environment variable to set the locale you prefer prior
to calling the graph function.
--yy|----yy--ggrriidd _g_r_i_d _s_t_e_p:_l_a_b_e_l _f_a_c_t_o_r (default autoconfigure)
Makes vertical grid lines appear at _g_r_i_d _s_t_e_p interval. Every _l_a_b_e_l
_f_a_c_t_o_r gridstep, a major grid line is printed, along with label
showing the value of the grid line.
If you want no y-grid at all set specify the magic word nnoonnee.
--YY|----aalltt--yy--ggrriidd
Place Y grid dynamically based on graph Y range. Algorithm ensures
that you always have grid, that there are enough but not too many
grid lines and the grid is metric. That is grid lines are placed
every 1, 2, 5 or 10 units. (contributed by Sasha Mikheev)
----nnoo--mmiinnoorr
Turn off the minor grid lines. This is particularly useful for
small graphs which can be cluttered with the minor grid lines.
(contributed by Travis Brown)
--RR|----aalltt--yy--mmrrttgg
Y grid placed on graph Y range mimics MRTG's (rateup-generated)
graphs. Currently axis is split into 4 parts, just as rateup does.
--AA|----aalltt--aauuttoossccaallee
Compute Y range based on function absolute minimum and maximum
values. Default algorithm uses predefined set of ranges. This is
good in many cases but it fails miserably when you need to graph
something like 260 + 0.001 * sin(x). Default algorithm will use Y
range from 250 to 300 and on the graph you will see almost straight
line. With --alt-autoscale Y range will be from slightly less the
260 - 0.001 to slightly more then 260 + 0.001 and periodic behavior
will be seen. (contributed by Sasha Mikheev)
--MM|----aalltt--aauuttoossccaallee--mmaaxx
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.
--XX|----uunniittss--eexxppoonneenntt _v_a_l_u_e (default autoconfigure)
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
inclusive. It is the exponent on the units you which 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.
--LL|----uunniittss--lleennggtthh _v_a_l_u_e (default 9 characters)
This sets the character width on the left side of the graph for
y-axis values.
--vv|----vveerrttiiccaall--llaabbeell _t_e_x_t
vertical label on the left side of the graph. This is normally used
to specify the units used.
--ww|----wwiiddtthh _p_i_x_e_l_s (default 400 pixel)
Width of the drawing area within the graph. This affects the size
of the gif.
--hh|----hheeiigghhtt _p_i_x_e_l_s (default 100 pixel)
Height of the drawing area within the graph. This affects the size
of the gif.
--ii|----iinntteerrllaacceedd (default: false)
If you set this option, then the resulting GIF will be interlaced.
Most web browsers display these incrementally as they load. If you
do not use this option, the GIFs default to being progressive
scanned. The only effect of this option is to control the format of
the GIF on disk. It makes no changes to the layout or contents of
the graph.
--ff|----iimmggiinnffoo _f_o_r_m_a_t_s_t_r_i_n_g
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 is supplied with the
parameters _f_i_l_e_n_a_m_e, _x_s_i_z_e and _y_s_i_z_e. In order to generate an IIMMGG
tag suitable for including the graph into a web page, the command
line would look like this:
--imginfo ''
--aa|----iimmggffoorrmmaatt GGIIFF|PPNNGG|GGDD (default: GIF)
Allows you to produce PNG or GD output from RRDTool.
--BB|----bbaacckkggrroouunndd _v_a_l_u_e
You could use image in (currently only) GD format for background.
It is used as background at the very beginning of graph creation.
--OO|----oovveerrllaayy _v_a_l_u_e
You could use image in (currently only) GD format as overlay. It is
placed over created graph so that white pixel (color 255,255,255)
is considered transparent, all other is replacing corresponding
pixel in created graph.
--UU|----uunniitt _v_a_l_u_e
You could use unit to be displayed on y axis. It is wise to use
only short units on graph, however.
--zz|----llaazzyy (default: false)
Only generate the graph, if the current gif is out of date or not
existent.
--uu|----uuppppeerr--lliimmiitt _v_a_l_u_e (default autoconfigure)
Defines the value normally located at the upper border of the
graph. If the graph contains higher values, the upper border will
move upwards to accommodate these values as well.
If you want to define an upper-limit which will not move in any
event you have to set the ----rriiggiidd option as well.
--ll|----lloowweerr--lliimmiitt _v_a_l_u_e (default autoconfigure)
This is not the lower limit of a graph. But rather, this is the
maximum lower bound of a graph. For example, the value -100 will
result in a graph that has a lower limit of -100 or less. Use this
keyword to expand graphs down.
--rr|----rriiggiidd
rigid boundaries mode. Normally rrrrddggrraapphh will automatically expand
the lower and upper limit if the graph contains a value outside the
valid range. With the r option you can disable this behavior
--bb|----bbaassee _v_a_l_u_e
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.
--oo|----llooggaarriitthhmmiicc
logarithmic y-axis scaling
--cc|----ccoolloorr _C_O_L_O_R_T_A_G##_r_r_g_g_b_b (default colors)
override the colors for the standard elements of the graph. The
_C_O_L_O_R_T_A_G must be one of the following symbolic names: BBAACCKK ground,
CCAANNVVAASS, SSHHAADDEEAA left/top border, SSHHAADDEEBB right/bottom border, GGRRIIDD,
MMGGRRIIDD major grid, FFOONNTT, FFRRAAMMEE and axis of the graph or AARRRROOWW. This
option can be called multiple times to set several colors.
--gg|----nnoo--lleeggeenndd
Suppress generation of legend; only render the graph.
--jj|----oonnllyy--ggrraapphh
Suppress anything but the graph.
--FF|----ffoorrccee--rruulleess--lleeggeenndd
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).
--tt|----ttiittllee _t_e_x_t (default no title)
Define a title to be written into the graph
--SS|----sstteepp _v_a_l_u_e (default automatic)
By default rrrrddggrraapphh calculates the width of one pixel in the time
domain and tries to get data at that resolution from the RRD. With
this switch you can override this behavior. If you want rrrrddggrraapphh to
get data at 1 hour resolution from the RRD, then you can set the
step to 3600 seconds. Note, that a step smaller than 1 pixel will
be silently ignored.
DDEEFF::_v_n_a_m_e==_r_r_d::_d_s_-_n_a_m_e::_C_F
Define virtual name for a data source. This name can then be used
in the functions explained below. The DEF call automatically
chooses an RRRRAA which contains _C_F consolidated data in a resolution
appropriate for the size of the graph to be drawn. Ideally this
means that one data point from the RRRRAA should be represented by one
pixel in the graph. If the resolution of the RRRRAA is higher than
the resolution of the graph, the data in the RRA will be further
consolidated according to the consolidation function (_C_F) chosen.
CCDDEEFF::_v_n_a_m_e==_r_p_n_-_e_x_p_r_e_s_s_i_o_n
Create a new virtual data source by evaluating a mathematical
expression, specified in Reverse Polish Notation (RPN). If you have
ever used a traditional HP calculator you already know RPN. The
idea behind RPN notation is, that you have a stack and push your
data onto this stack. When ever you execute an operation, it takes
as many data values from the stack as needed. The pushing of data
is implicit, so when ever you specify a number or a variable, it
gets pushed automatically.
If this is all a big load of incomprehensible words for you, maybe
an example helps (a more complete explanation is given in [1]): The
expression _v_n_a_m_e_+_3_/_2 becomes "vname,3,2,/,+" in RPN. First the
three values get pushed onto the stack (which now contains (the
current value of) vname, a 3 and a 2). Then the / operator pops
two values from the stack (3 and 2), divides the first argument by
the second (3/2) and pushes the result (1.5) back onto the stack.
Then the + operator pops two values (vname and 1.5) from the stack;
both values are added up and the result gets pushes back onto the
stack. In the end there is only one value left on the stack: The
result of the expression.
The _r_p_n_-_e_x_p_r_e_s_s_i_o_n in the CCDDEEFF function takes both, constant values
as well as _v_n_a_m_e variables. The following operators can be used on
these values:
+, -, *, /, %
pops two values from the stack applies the selected operator
and pushes the result back onto the stack. The % operator
stands for the modulo operation.
SIN, COS, LOG, EXP, FLOOR, CEIL
pops one value from the stack, applies the selected function
and pushes the result back onto the stack.
LT, LE, GT, GE, EQ
pops two values from the stack, compares them according to the
selected condition and pushes either 1 back onto the stack if
the condition is true and 0 if the condition was not true.
IF pops three values from the stack. If the last value is not 0,
the second value will be pushed back onto the stack, otherwise
the first value is pushed back.
If the stack contains the values A, B, C, D, E are presently on
the stack, the IF operator will pop the values E D and C of the
stack. It will look at C and if it is not 0 it will push D back
onto the stack, otherwise E will be sent back to the stack.
MIN, MAX
selects the lesser or larger of the two top stack values
respectively
LIMIT
replaces the value with _*_U_N_K_N_O_W_N_* if it is outside the limits
specified by the two values above it on the stack.
CDEF:a=alpha,0,100,LIMIT
DUP, EXC, POP
These manipulate the stack directly. DUP will duplicate the
top of the stack, pushing the result back onto the stack. EXC
will exchange the top two elements of the stack, and POP will
pop off the top element of the stack. Having insufficient
elements on the stack for these operations is an error.
UN Pops one value off the stack, if it is _*_U_N_K_N_O_W_N_*, 1 will be
pushed back otherwise 0.
UNKN
Push an _*_U_N_K_N_O_W_N_* value onto the stack.
PREV
Push _*_U_N_K_N_O_W_N_* if its at the first value of a data set or
otherwise the value of this CDEF at the previous time step.
This allows you to perform calculations across the data.
PREV(vname)
Push _*_U_N_K_N_O_W_N_* if its at the first value of the data set named
vname or otherwise the value of the CDEF named vname at the
previous time step. This allows you to perform complex
calculations across the data.
INF, NEGINF
Push a positive or negative infinite (oo) value onto the stack.
When drawing an infinite number it appears right at the top or
bottom edge of the graph, depending whether you have a positive
or negative infinite number.
NOW Push the current (real world) time onto the stack.
TIME
Push the time the current sample was taken onto the stack. This
is the number of non-skip seconds since 0:00:00 January 1,
1970.
LTIME
This is like TIME ++ ccuurrrreenntt ttiimmeezzoonnee ooffffsseett iinn sseeccoonnddss. The
current offset takes daylight saving time into account, given
your OS supports this. If you were looking at a sample, in
Zurich, in summer, the offset would be 2*3600 seconds, as
Zurich at that time of year is 2 hours ahead of UTC.
Note that the timezone offset is always calculated for the time
the current sample was taken at. It has nothing to do with the
time you are doing the calculation.
Please note that you may only use _v_n_a_m_e variables that you
previously defined by either DDEEFF or CCDDEEFF. Furthermore, as of this
writing (version 0.99.25), you must use at least one _v_n_a_m_e per
expression, that is "CDEF:fourtytwo=2,40,+" will yield an error
message but not a _v_n_a_m_e fourtytwo that's always equal to 42.
PPRRIINNTT::_v_n_a_m_e::_C_F::_f_o_r_m_a_t
Calculate the chosen consolidation function _C_F over the data-source
variable _v_n_a_m_e and "printf" the result to stdout using _f_o_r_m_a_t. In
the _f_o_r_m_a_t string there should be a '%lf', '%lg' or '%le' marker in
the place where the number should be printed.
If an additional '%s' is found AFTER the marker, the value will be
scaled and an appropriate SI magnitude unit will be printed in
place of the '%s' marker. The scaling will take the '--base'
argument into consideration!
If a '%S' is used instead of a '%s', then instead of calculating
the appropriate SI magnitude unit for this value, the previously
calculated SI magnitude unit will be used. This is useful if you
want all the values in a PRINT statement to have the same SI
magnitude unit. If there was no previous SI magnitude calculation
made, then '%S' behaves like a '%s', unless the value is 0, in
which case it does not remember a SI magnitude unit and a SI
magnitude unit will only be calculated when the next '%s' is seen
or the next '%S' for a non-zero value.
If you want to put a '%' into your PRINT string, use '%%' instead.
GGPPRRIINNTT::_v_n_a_m_e::_C_F::_f_o_r_m_a_t
Same as PPRRIINNTT but the result is printed into the graph below the
legend.
CCaavveeaatt:: When using the PPRRIINNTT and GGRRPPRRIINNTT functions to calculate data
summaries over time periods bounded by the current time, it is
important to note that the last sample will almost always yield a value
of UNKNOWN as it lies after the last update time. This can result in
slight data skewing, particularly with the AAVVEERRAAGGEE function. In order
to avoid this, make sure that your end time is at least one heartbeat
prior to the current time.
CCOOMMMMEENNTT::_t_e_x_t
Like GGPPRRIINNTT but the _t_e_x_t is simply printed into the graph.
HHRRUULLEE::_v_a_l_u_e##_r_r_g_g_b_b[::_l_e_g_e_n_d]
Draw a horizontal rule into the graph and optionally add a legend
VVRRUULLEE::_t_i_m_e##_r_r_g_g_b_b[::_l_e_g_e_n_d]
Draw a vertical rule into the graph and optionally add a legend
LLIINNEE{11|22|33}::_v_n_a_m_e[##_r_r_g_g_b_b[::_l_e_g_e_n_d]]
Plot for the requested data, using the color specified. Write a
legend into the graph. The 3 possible keywords LLIINNEE11, LLIINNEE22, and
LLIINNEE33 generate increasingly wide lines. If no color is defined, the
drawing is done 'blind' this is useful in connection with the SSTTAACCKK
function when you want to ADD the values of two data-sources
without showing it in the graph.
AARREEAA:_v_n_a_m_e[##_r_r_g_g_b_b[::_l_e_g_e_n_d]]
Does the same as LLIINNEE??, but the area between 0 and the graph will
be filled with the color specified.
SSTTAACCKK:_v_n_a_m_e[##_r_r_g_g_b_b[::_l_e_g_e_n_d]]
Does the same as LLIINNEE??, but the graph gets stacked on top of the
previous LLIINNEE??, AARREEAA or SSTTAACCKK graph. Depending on the type of the
previous graph, the SSTTAACCKK will be either a LLIINNEE?? or an AARREEAA. This
obviously implies that the first SSTTAACCKK must be preceded by an AARREEAA
or LLIINNEE?? -- you need something to stack something onto in the first
place ;)
Note, that when you STACK onto *UNKNOWN* data, RRDTool will not
draw any graphics ... *UNKNOWN* is not zero ... if you want it to
zero then you might want to use a CDEF argument with IF and UN
functions to turn *UNKNOWN* into zero ...
NNOOTTEESS oonn lleeggeenndd aarrgguummeennttss
EEssccaappiinngg tthhee ccoolloonn
In a ':' in a _l_e_g_e_n_d argument will mark the end of the legend. To enter
a ':' into a legend, the colon must be escaped with a backslash '\:'.
Beware, that many environments look for backslashes themselves, so it
may be necessary to write two backslashes so that one is passed onto
rrrrddggrraapphh.
SSttrriinngg FFoorrmmaattttiinngg
The text printed below the actual graph can be formated by appending
special escaped characters at the end of a text. When ever such a
character occurs, all pending text is pushed onto the graph according
to the character specified.
Valid markers are: \\jj for justified, \\ll for left aligned, \\rr for right
aligned and \\cc for centered. In the next section there is an example
showing how to use centered formating.
Normally there are two space characters inserted between every two
items printed into the graph. The space following a string can be
suppressed by putting a \\gg at the end of the string. The \\gg also
squashes any space inside the string if it is at the very end of the
string. This can be used in connection with %%ss to suppress empty unit
strings.
GPRINT:a:MAX:%lf%s\g
A special case is COMMENT:\\ss this inserts some additional vertical
space before placing the next row of legends.
When text has to be formated without special instructions from your
side, RRDTool will automatically justify the text as soon as one string
goes over the right edge. If you want to prevent the justification
without forcing a newline, you can use the special tag \\JJ at the end of
the string to disable the auto justification.
NNOOTTEE oonn RReettuurrnn VVaalluueess
Whenever rrrrddggrraapphh gets called, it prints a line telling the size of the
gif it has just created to STDOUT. This line looks like this:
XSIZExYSIZE.
EEXXAAMMPPLLEE 11
rrdtool graph demo.gif --title="Demo Graph" \
DEF:cel=demo.rrd:exhaust:AVERAGE \
"CDEF:far=cel,1.8,*,32,+"" \
LINE2:cel#00a000:"D. Celsius" \
LINE2:far#ff0000:"D. Fahrenheit\c"
EEXXAAMMPPLLEE 22
This example demonstrates the syntax for using IF and UN to set
_*_U_N_K_N_O_W_N_* values to 0. This technique is useful if you are aggregating
interface data where the start dates of the data sets doesn't match.
rrdtool graph demo.gif --title="Demo Graph" \
DEF:idat1=interface1.rrd:ds0:AVERAGE \
DEF:idat2=interface2.rrd:ds0:AVERAGE \
DEF:odat1=interface1.rrd:ds1:AVERAGE \
DEF:odat2=interface2.rrd:ds1:AVERAGE \
CDEF:agginput=idat1,UN,0,idat1,IF,idat2,UN,0,idat2,IF,+,8,* \
CDEF:aggoutput=odat1,UN,0,odat1,IF,odat2,UN,0,odat2,IF,+,8,* \
AREA:agginput#00cc00:Input Aggregate \
LINE1:aggoutput#0000FF:Output Aggregate
Assuming that idat1 has a data value of _*_U_N_K_N_O_W_N_*, the CDEF expression
idat1,UN,0,idat1,IF
leaves us with a stack with contents of 1,0,NaN and the IF function
will pop off the 3 values and replace them with 0. If idat1 had a real
value like 7942099, then the stack would have 0,0,7942099 and the real
value would be the replacement.
EEXXAAMMPPLLEE 33
This example shows two ways to use the INF function. First it makes the
background change color during half of the hours. Then, it uses AREA
and STACK to draw a picture. If one of the inputs was UNKNOWN, all
inputs are overlaid with another AREA.
rrdtool graph example.png --title="INF demo" \
DEF:val1=some.rrd:ds0:AVERAGE \
DEF:val2=some.rrd:ds1:AVERAGE \
DEF:val3=some.rrd:ds2:AVERAGE \
DEF:val4=other.rrd:ds0:AVERAGE \
CDEF:background=val4,POP,TIME,7200,%,3600,LE,INF,UNKN,IF \
CDEF:wipeout=val1,val2,val3,val4,+,+,+,UN,INF,UNKN,IF \
AREA:background#F0F0F0 \
AREA:val1#0000FF:Value1 \
STACK:val2#00C000:Value2 \
STACK:val3#FFFF00:Value3 \
STACK:val4#FFC000:Value4 \
AREA:wipeout#FF0000:Unknown
The first CDEF uses val4 as a dummy value. It's value is removed
immediately from the stack. Then a decision is made based on the time
that a sample was taken. If it is an even hour (UTC time !) then the
area will be filled. If it is not, the value is set to UNKN and is not
plotted.
The second CDEF looks if any of val1,val2,val3,val4 is unknown. It does
so by checking the outcome of sum(val1,val2,val3,val4). Again, INF is
returned when the condition is true, UNKN is used to not plot the data.
The different items are plotted in a particular order. First do the
background, then use a normal area to overlay it with data. Stack the
other data until they are all plotted. Last but not least, overlay
everything with eye-hurting red to signal any unknown data.
Note that this example assumes that your data is in the positive half
of the y-axis otherwise you would have to add NEGINF in order to extend
the coverage of the rea to whole graph.
AAUUTTHHOORR
Tobias Oetiker
RREEFFEERREENNCCEESS
[1] http://www.dotpoint.com/xnumber/rpn_or_adl.htm
1.0.50 2004-11-08 RRDGRAPH(1)