![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/cdeftutorial.txt b/doc/cdeftutorial.txt
index c67ecaa0998a6884d6402220d829536dda137a0b..cab147dfa4c32b44e4e76a9962a881e327506b74 100644 (file)
--- a/doc/cdeftutorial.txt
+++ b/doc/cdeftutorial.txt
If you think some important feature is not explained properly, and if
adding it to this document would benefit most users, please do ask me
to add it. I will then try to provide an answer in the next release of
- this tutorial. No feedback equals no changes! Additions to this docu-
- ment are also welcome. -- Alex van den Bogaerdt <alex@vandenbo-
- gaerdt.nl>
-
- W\bWh\bhy\by t\bth\bhi\bis\bs t\btu\but\bto\bor\bri\bia\bal\bl?\b?
+ this tutorial. No feedback equals no changes! Additions to this
+ document are also welcome. -- Alex van den Bogaerdt
+ <alex@vandenbogaerdt.nl>
+ W\bWh\bhy\by t\bth\bhi\bis\bs t\btu\but\bto\bor\bri\bia\bal\bl?\b?
One of the powerful parts of RRDtool is its ability to do all sorts of
- calculations on the data retrieved from its databases. However, RRD-
- tool's many options and syntax make it difficult for the average user
- to understand. The manuals are good at explaining what these options
- do; however they do not (and should not) explain in detail why they are
- useful. As with my RRDtool tutorial: if you want a simple document in
- simple language you should read this tutorial. If you are happy with
- the official documentation, you may find this document too simple or
- even boring. If you do choose to read this tutorial, I also expect you
- to have read and fully understand my other tutorial.
-
- M\bMo\bor\bre\be r\bre\bea\bad\bdi\bin\bng\bg
-
+ calculations on the data retrieved from its databases. However,
+ RRDtool's many options and syntax make it difficult for the average
+ user to understand. The manuals are good at explaining what these
+ options do; however they do not (and should not) explain in detail why
+ they are useful. As with my RRDtool tutorial: if you want a simple
+ document in simple language you should read this tutorial. If you are
+ happy with the official documentation, you may find this document too
+ simple or even boring. If you do choose to read this tutorial, I also
+ expect you to have read and fully understand my other tutorial.
+
+ M\bMo\bor\bre\be r\bre\bea\bad\bdi\bin\bng\bg
If you have difficulties with the way I try to explain it please read
Steve Rader's rpntutorial. It may help you understand how this all
works.
reverse the order of the variables.
C\bCo\bon\bnv\bve\ber\brt\bti\bin\bng\bg y\byo\bou\bur\br w\bwi\bis\bsh\bhe\bes\bs t\bto\bo R\bRP\bPN\bN
- First, get a clear picture of what you want to do. Break down the prob-
- lem in smaller portions until they cannot be split anymore. Then it is
- rather simple to convert your ideas into RPN.
+ First, get a clear picture of what you want to do. Break down the
+ problem in smaller portions until they cannot be split anymore. Then it
+ is rather simple to convert your ideas into RPN.
Suppose you have several RRDs and would like to add up some counters in
them. These could be, for instance, the counters for every WAN link you
@@ -183,8 +181,8 @@ C\bCo\bon\bnv\bve\ber\brt\bti\bin\bng\bg y\byo\bou\bur\br w\bwi\bis\bsh\bhe\bes\bs t\bto\bo R\bRP\bPN\bN
This is correct but it can be made more clear to humans. It does not
matter if you add a to b and then add c to the result or first add b to
c and then add a to the result. This makes it possible to rewrite the
- RPN into "CDEF:result=a,b,c,d,e,+,+,+,+" which is evaluated differ-
- ently:
+ RPN into "CDEF:result=a,b,c,d,e,+,+,+,+" which is evaluated
+ differently:
push value of variable a on the stack: a
push value of variable b on the stack: a b
@@ -222,8 +220,8 @@ C\bCo\bon\bnv\bve\ber\brt\bti\bin\bng\bg y\byo\bou\bur\br w\bwi\bis\bsh\bhe\bes\bs t\bto\bo R\bRP\bPN\bN
also be converted into RPN. The parenthesis just tell you to first add
b and c, and then multiply a with the result. Again, now it is easy to
write it in RPN: "result=a,b,c,+,*". Note that this is very similar to
- one of the expressions in the previous paragraph, only the multiplica-
- tion and the addition changed places.
+ one of the expressions in the previous paragraph, only the
+ multiplication and the addition changed places.
When you have problems with RPN or when RRDtool is complaining, it's
usually a good thing to write down the stack on a piece of paper and
@@ -232,8 +230,7 @@ C\bCo\bon\bnv\bve\ber\brt\bti\bin\bng\bg y\byo\bou\bur\br w\bwi\bis\bsh\bhe\bes\bs t\bto\bo R\bRP\bPN\bN
solve most, if not all, problems you encounter.
S\bSo\bom\bme\be s\bsp\bpe\bec\bci\bia\bal\bl n\bnu\bum\bmb\bbe\ber\brs\bs
- T\bTh\bhe\be u\bun\bnk\bkn\bno\bow\bwn\bn v\bva\bal\blu\bue\be
-
+ T\bTh\bhe\be u\bun\bnk\bkn\bno\bow\bwn\bn v\bva\bal\blu\bue\be
Sometimes collecting your data will fail. This can be very common,
especially when querying over busy links. RRDtool can be configured to
allow for one (or even more) unknown value(s) and calculate the missing
CDP and the xff factor. As you can see from the previous text they
define the behavior of your RRA.
- W\bWo\bor\brk\bki\bin\bng\bg w\bwi\bit\bth\bh u\bun\bnk\bkn\bno\bow\bwn\bn d\bda\bat\bta\ba i\bin\bn y\byo\bou\bur\br d\bda\bat\bta\bab\bba\bas\bse\be
-
+ W\bWo\bor\brk\bki\bin\bng\bg w\bwi\bit\bth\bh u\bun\bnk\bkn\bno\bow\bwn\bn d\bda\bat\bta\ba i\bin\bn y\byo\bou\bur\br d\bda\bat\bta\bab\bba\bas\bse\be
As you have read in the previous chapter, entries in an RRA can be set
to the unknown value. If you do calculations with this type of value,
the result has to be unknown too. This means that an expression such as
There are some examples below that make this change.
- I\bIn\bnf\bfi\bin\bni\bit\bty\by
-
+ I\bIn\bnf\bfi\bin\bni\bit\bty\by
Infinite data is another form of a special number. It cannot be graphed
because by definition you would never reach the infinite value. You can
- think of positive and negative infinity depending on the position rela-
- tive to zero.
+ think of positive and negative infinity depending on the position
+ relative to zero.
- RRDtool is capable of representing (-not- graphing!) infinity by stop-
- ping at its current maximum (for positive infinity) or minimum (for
+ RRDtool is capable of representing (-not- graphing!) infinity by
+ stopping at its current maximum (for positive infinity) or minimum (for
negative infinity) without knowing this maximum (minimum).
Infinity in RRDtool is mostly used to draw an AREA without knowing its
current graph. This is probably a good way to approximate infinity and
it sure allows for some neat tricks. See below for examples.
- W\bWo\bor\brk\bki\bin\bng\bg w\bwi\bit\bth\bh u\bun\bnk\bkn\bno\bow\bwn\bn d\bda\bat\bta\ba a\ban\bnd\bd i\bin\bnf\bfi\bin\bni\bit\bty\by
-
+ W\bWo\bor\brk\bki\bin\bng\bg w\bwi\bit\bth\bh u\bun\bnk\bkn\bno\bow\bwn\bn d\bda\bat\bta\ba a\ban\bnd\bd i\bin\bnf\bfi\bin\bni\bit\bty\by
Sometimes you would like to discard unknown data and pretend it is zero
(or any other value for that matter) and sometimes you would like to
pretend that known data is unknown (to discard known-to-be-wrong data).
- This is why CDEFs have support for unknown data. There are also exam-
- ples available that show unknown data by using infinity.
+ This is why CDEFs have support for unknown data. There are also
+ examples available that show unknown data by using infinity.
S\bSo\bom\bme\be e\bex\bxa\bam\bmp\bpl\ble\bes\bs
- E\bEx\bxa\bam\bmp\bpl\ble\be:\b: u\bus\bsi\bin\bng\bg a\ba r\bre\bec\bce\ben\bnt\btl\bly\by c\bcr\bre\bea\bat\bte\bed\bd R\bRR\bRD\bD
-
+ E\bEx\bxa\bam\bmp\bpl\ble\be:\b: u\bus\bsi\bin\bng\bg a\ba r\bre\bec\bce\ben\bnt\btl\bly\by c\bcr\bre\bea\bat\bte\bed\bd R\bRR\bRD\bD
You are keeping statistics on your router for over a year now. Recently
you installed an extra router and you would like to show the combined
throughput for these two devices.
router2.rrd) for the bigger part of your stats. You could solve this in
a few ways:
- · While creating the new database, fill it with zeros from the start
+ · While creating the new database, fill it with zeros from the start
to now. You have to make the database start at or before the least
recent time in the other database.
- · Alternatively, you could use CDEF and alter unknown data to zero.
+ · Alternatively, you could use CDEF and alter unknown data to zero.
Both methods have their pros and cons. The first method is troublesome
and if you want to do that you have to figure it out yourself. It is
Eventually, when all unknown data is removed from the RRD, you may want
to remove this rule so that unknown data is properly displayed.
- E\bEx\bxa\bam\bmp\bpl\ble\be:\b: b\bbe\bet\btt\bte\ber\br h\bha\ban\bnd\bdl\bli\bin\bng\bg o\bof\bf u\bun\bnk\bkn\bno\bow\bwn\bn d\bda\bat\bta\ba,\b, b\bby\by u\bus\bsi\bin\bng\bg t\bti\bim\bme\be
-
+ E\bEx\bxa\bam\bmp\bpl\ble\be:\b: b\bbe\bet\btt\bte\ber\br h\bha\ban\bnd\bdl\bli\bin\bng\bg o\bof\bf u\bun\bnk\bkn\bno\bow\bwn\bn d\bda\bat\bta\ba,\b, b\bby\by u\bus\bsi\bin\bng\bg t\bti\bim\bme\be
The above example has one drawback. If you do log unknown data in your
- database after installing your new equipment, it will also be trans-
- lated into zero and therefore you won't see that there was a problem.
- This is not good and what you really want to do is:
+ database after installing your new equipment, it will also be
+ translated into zero and therefore you won't see that there was a
+ problem. This is not good and what you really want to do is:
- · If there is unknown data, look at the time that this sample was
+ · If there is unknown data, look at the time that this sample was
taken.
- · If the unknown value is before time xxx, make it zero.
+ · If the unknown value is before time xxx, make it zero.
- · If it is after time xxx, leave it as unknown data.
+ · If it is after time xxx, leave it as unknown data.
This is doable: you can compare the time that the sample was taken to
some known time. Assuming you started to monitor your device on Friday
You could also dump the database and see where the data starts to be
known. There are several other ways of doing this, just pick one.
- Now we have to create the magic that allows us to process unknown val-
- ues different depending on the time that the sample was taken. This is
- a three step process:
+ Now we have to create the magic that allows us to process unknown
+ values different depending on the time that the sample was taken. This
+ is a three step process:
1. If the timestamp of the value is after 937'521'357, leave it as is.
This looks very complex, however, as you can see, it was not too hard
to come up with.
- E\bEx\bxa\bam\bmp\bpl\ble\be:\b: P\bPr\bre\bet\bte\ben\bnd\bdi\bin\bng\bg w\bwe\bei\bir\brd\bd d\bda\bat\bta\ba i\bis\bsn\bn'\b't\bt t\bth\bhe\ber\bre\be
-
+ E\bEx\bxa\bam\bmp\bpl\ble\be:\b: P\bPr\bre\bet\bte\ben\bnd\bdi\bin\bng\bg w\bwe\bei\bir\brd\bd d\bda\bat\bta\ba i\bis\bsn\bn'\b't\bt t\bth\bhe\ber\bre\be
Suppose you have a problem that shows up as huge spikes in your graph.
- You know this happens and why, so you decide to work around the prob-
- lem. Perhaps you're using your network to do a backup at night and by
- doing so you get almost 10mb/s while the rest of your network activity
- does not produce numbers higher than 100kb/s.
+ You know this happens and why, so you decide to work around the
+ problem. Perhaps you're using your network to do a backup at night and
+ by doing so you get almost 10mb/s while the rest of your network
+ activity does not produce numbers higher than 100kb/s.
There are two options:
CDEF:result=number,100000,GT,UNKN,number,IF
CDEF:result=number,100000,GT,100000,number,IF
- E\bEx\bxa\bam\bmp\bpl\ble\be:\b: w\bwo\bor\brk\bki\bin\bng\bg o\bon\bn a\ba c\bce\ber\brt\bta\bai\bin\bn t\bti\bim\bme\be s\bsp\bpa\ban\bn
-
+ E\bEx\bxa\bam\bmp\bpl\ble\be:\b: w\bwo\bor\brk\bki\bin\bng\bg o\bon\bn a\ba c\bce\ber\brt\bta\bai\bin\bn t\bti\bim\bme\be s\bsp\bpa\ban\bn
If you want a graph that spans a few weeks, but would only want to see
some routers' data for one week, you need to "hide" the rest of the
time frame. Don't ask me when this would be useful, it's just here for
but, as Wataru Satoh pointed out, we can use the "*" or "+" functions
as logical AND and logical OR.
- For "*", the result will be zero (false) if either one of the two oper-
- ators is zero. For "+", the result will only be false (0) when two
+ For "*", the result will be zero (false) if either one of the two
+ operators is zero. For "+", the result will only be false (0) when two
false (0) operators will be added. Warning: *any* number not equal to
0 will be considered "true". This means that, for instance, "-1,1,+"
(which should be "true or true") will become FALSE ... In other words,
This will return an UNKNOWN if either comparison returns true.
- E\bEx\bxa\bam\bmp\bpl\ble\be:\b: Y\bYo\bou\bu s\bsu\bus\bsp\bpe\bec\bct\bt t\bto\bo h\bha\bav\bve\be p\bpr\bro\bob\bbl\ble\bem\bms\bs a\ban\bnd\bd w\bwa\ban\bnt\bt t\bto\bo s\bse\bee\be u\bun\bnk\bkn\bno\bow\bwn\bn d\bda\bat\bta\ba.\b.
-
+ E\bEx\bxa\bam\bmp\bpl\ble\be:\b: Y\bYo\bou\bu s\bsu\bus\bsp\bpe\bec\bct\bt t\bto\bo h\bha\bav\bve\be p\bpr\bro\bob\bbl\ble\bem\bms\bs a\ban\bnd\bd w\bwa\ban\bnt\bt t\bto\bo s\bse\bee\be u\bun\bnk\bkn\bno\bow\bwn\bn d\bda\bat\bta\ba.\b.
Suppose you add up the number of active users on several terminal
servers. If one of them doesn't give an answer (or an incorrect one)
you get "NaN" in the database ("Not a Number") and NaN is evaluated as
AREA:allusers#0000FF:combined user count
AREA:wrongdata#FF0000:unknown data
- S\bSa\bam\bme\be e\bex\bxa\bam\bmp\bpl\ble\be u\bus\bse\bef\bfu\bul\bl w\bwi\bit\bth\bh S\bST\bTA\bAC\bCK\bKe\bed\bd d\bda\bat\bta\ba:\b:
-
+ S\bSa\bam\bme\be e\bex\bxa\bam\bmp\bpl\ble\be u\bus\bse\bef\bfu\bul\bl w\bwi\bit\bth\bh S\bST\bTA\bAC\bCK\bKe\bed\bd d\bda\bat\bta\ba:\b:
If you use stack in the previous example (as I would do) then you don't
add up the values. Therefore, there is no relationship between the four
values and you don't get a single value to test. Suppose users3 would
You could combine the two CDEF lines into one (we don't use "allusers")
if you like. But there are good reasons for writing two CDEFS:
- · It improves the readability of the script.
+ · It improves the readability of the script.
- · It can be used inside GPRINT to display the total number of users.
+ · It can be used inside GPRINT to display the total number of users.
If you choose to combine them, you can substitute the "allusers" in the
second CDEF with the part after the equal sign from the first line:
GPRINT:allusers:LAST:"Current: %6.0lf\n"
T\bTh\bhe\be e\bex\bxa\bam\bmp\bpl\ble\bes\bs f\bfr\bro\bom\bm t\bth\bhe\be R\bRR\bRD\bD g\bgr\bra\bap\bph\bh m\bma\ban\bnu\bua\bal\bl p\bpa\bag\bge\be
- D\bDe\beg\bgr\bre\bee\bes\bs C\bCe\bel\bls\bsi\biu\bus\bs v\bvs\bs.\b. D\bDe\beg\bgr\bre\bee\bes\bs F\bFa\bah\bhr\bre\ben\bnh\bhe\bei\bit\bt
-
+ D\bDe\beg\bgr\bre\bee\bes\bs C\bCe\bel\bls\bsi\biu\bus\bs v\bvs\bs.\b. D\bDe\beg\bgr\bre\bee\bes\bs F\bFa\bah\bhr\bre\ben\bnh\bhe\bei\bit\bt
To convert Celsius into Fahrenheit use the formula F=9/5*C+32
rrdtool graph demo.png --title="Demo Graph" \
@@ -652,8 +639,8 @@ T\bTh\bhe\be e\bex\bxa\bam\bmp\bpl\ble\bes\bs f\bfr\bro\bom\bm t\bth\bhe\be R\bRR\bRD\bD g\bgr\bra\bap\bp
LINE2:far#ff0000:"D. Fahrenheit\c"
This example gets the DS called "exhaust" from database "demo.rrd" and
- puts the values in variable "cel". The CDEF used is evaluated as fol-
- lows:
+ puts the values in variable "cel". The CDEF used is evaluated as
+ follows:
CDEF:far=9,5,/,cel,*,32,+
1. push 9, push 5
@@ -666,8 +653,7 @@ T\bTh\bhe\be e\bex\bxa\bam\bmp\bpl\ble\bes\bs f\bfr\bro\bom\bm t\bth\bhe\be R\bRR\bRD\bD g\bgr\bra\bap\bp
6. push function "plus" and process it
the stack contains now the temperature in Fahrenheit
- C\bCh\bha\ban\bng\bgi\bin\bng\bg u\bun\bnk\bkn\bno\bow\bwn\bn i\bin\bnt\bto\bo z\bze\ber\bro\bo
-
+ C\bCh\bha\ban\bng\bgi\bin\bng\bg u\bun\bnk\bkn\bno\bow\bwn\bn i\bin\bnt\bto\bo z\bze\ber\bro\bo
rrdtool graph demo.png --title="Demo Graph" \
DEF:idat1=interface1.rrd:ds0:AVERAGE \
DEF:idat2=interface2.rrd:ds0:AVERAGE \
@@ -699,8 +685,7 @@ T\bTh\bhe\be e\bex\bxa\bam\bmp\bpl\ble\bes\bs f\bfr\bro\bom\bm t\bth\bhe\be R\bRR\bRD\bD g\bgr\bra\bap\bp
process we effectively ignored unknown values. The result is multiplied
by eight, most likely to convert bytes/s to bits/s.
- I\bIn\bnf\bfi\bin\bni\bit\bty\by d\bde\bem\bmo\bo
-
+ I\bIn\bnf\bfi\bin\bni\bit\bty\by d\bde\bem\bmo\bo
rrdtool graph example.png --title="INF demo" \
DEF:val1=some.rrd:ds0:AVERAGE \
DEF:val2=some.rrd:ds1:AVERAGE \
@@ -751,16 +736,15 @@ T\bTh\bhe\be e\bex\bxa\bam\bmp\bpl\ble\bes\bs f\bfr\bro\bom\bm t\bth\bhe\be R\bRR\bRD\bD g\bgr\bra\bap\bp
background. Suppose one of val1..val4 would be unknown, in that case
you end up with only three bars stacked on top of each other. You
don't want to see this because the data is only valid when all four
- variables are valid. This is why you use the second CDEF, it will over-
- lay the data with an AREA so the data cannot be seen anymore.
+ variables are valid. This is why you use the second CDEF, it will
+ overlay the data with an AREA so the data cannot be seen anymore.
If your data can also have negative values you also need to overwrite
the other half of your graph. This can be done in a relatively simple
way: what you need is the "wipeout" variable and place a negative sign
before it: "CDEF:wipeout2=wipeout,-1,*"
- F\bFi\bil\blt\bte\ber\bri\bin\bng\bg d\bda\bat\bta\ba
-
+ F\bFi\bil\blt\bte\ber\bri\bin\bng\bg d\bda\bat\bta\ba
You may do some complex data filtering:
MEDIAN FILTER: filters shot noise
@@ -773,6 +757,7 @@ T\bTh\bhe\be e\bex\bxa\bam\bmp\bpl\ble\bes\bs f\bfr\bro\bom\bm t\bth\bhe\be R\bRR\bRD\bD g\bgr\bra\bap\bp
LINE3:median#000077:filtered
LINE1:prev2#007700:'raw data'
+
DERIVATE:
DEF:var=database.rrd:traffic:AVERAGE
-1.3.99909060808 2009-02-21 CDEFTUTORIAL(1)
+1.3.999 2009-06-09 CDEFTUTORIAL(1)