X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Fcdeftutorial.pod;h=b2016a23c9a1308ced6ca4ecd67803f62c38a15a;hp=25ded60ef61d23a6de0fcb4f630a13694fdb3834;hb=c0783df3e5992e36de2722e9664e8beb20519740;hpb=7f4b880d9d5c7a48e273f52e8dfa54fae39006e3 diff --git a/doc/cdeftutorial.pod b/doc/cdeftutorial.pod index 25ded60..b2016a2 100644 --- a/doc/cdeftutorial.pod +++ b/doc/cdeftutorial.pod @@ -4,10 +4,15 @@ cdeftutorial - Alex van den Bogaerdt's CDEF tutorial =head1 DESCRIPTION -If you provide a question, I will try to provide an answer in the next -release of this tutorial. No feedback equals no changes! Additions to +Intention of this document: to provide some examples of the commonly +used parts of RRDtool's CDEF language. + +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 document are also welcome. -- Alex van den Bogaerdt -Ealex@ergens.op.het.netE +Ealex@vandenbogaerdt.nlE =head2 Why this tutorial? @@ -133,7 +138,7 @@ inbytes would have value 10, the stack would be: || -=back +=back Processing the stack (step 5) will retrieve one value from the stack (from the right at step 4). This is the operation multiply and this @@ -146,7 +151,7 @@ Generally speaking you have the following order: This is not very intuitive (at least most people don't think so). For the function f(A,B) you reverse the position of "f", but you do not -reverse the order of the variables. +reverse the order of the variables. =head1 Converting your wishes to RPN @@ -174,7 +179,7 @@ RRD router1.rrd) router1.rrd:link2in router2.rrd:link1in router3.rrd:link1in - router3.rrd:link2in + router3.rrd:link2in -------------------- + (outcome of the sum) @@ -212,7 +217,7 @@ 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 C which is -evaluated differently: +evaluated differently: push value of variable a on the stack: a push value of variable b on the stack: a b @@ -229,7 +234,7 @@ evaluated differently: and process it: S (where S == a+R) As you can see the RPN expression C will evaluate in -C<((((d+e)+c)+b)+a)> and it has the same outcome as C. +C<((((d+e)+c)+b)+a)> and it has the same outcome as C. This is called the commutative law of addition, but you may forget this right away, as long as you remember what it means. @@ -239,7 +244,7 @@ Now look at an expression that contains a multiplication: First in normal math: C. In this case you can't choose the order yourself, you have to start with the multiplication and then add a to it. You may alter the position of b and c, you must -not alter the position of a and b. +not alter the position of a and b. You have to take this in consideration when converting this expression into RPN. Read it as: "Add the outcome of b*c to a" and then it is @@ -253,7 +258,7 @@ easy to write it in RPN: C. Note that this is very similar to 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 +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 see what happens. Have the manual ready and pretend to be RRDtool. Just do all the math by hand to see what happens, I'm sure this will @@ -525,7 +530,7 @@ so lets do it quick: where x represents "time>937521357" where a represents the original value where b represents the outcome of the previous example - + time>937521357 --> TIME,937521357,GT if (x) then a else b --> x,a,b,IF @@ -612,7 +617,7 @@ numbers (or zero) only. Let's compile the complete CDEF: DEF:ds0=router1.rrd:AVERAGE - CDEF:ds0modified=TIME,begintime,GE,TIME,endtime,LE,*,UNKN,ds0,IF + CDEF:ds0modified=TIME,begintime,GT,TIME,endtime,LE,*,ds0,UNKN,IF This will return the value of ds0 if both comparisons return true. You could also do it the other way around: @@ -721,9 +726,12 @@ If you do so, you won't be able to use these next GPRINTs: =head2 Degrees Celsius vs. Degrees Fahrenheit +To convert Celsius into Fahrenheit use the formula +F=9/5*C+32 + rrdtool graph demo.png --title="Demo Graph" \ DEF:cel=demo.rrd:exhaust:AVERAGE \ - CDEF:far=cel,32,-,0.55555,* \ + CDEF:far=9,5,/,cel,*,32,+ \ LINE2:cel#00a000:"D. Celsius" \ LINE2:far#ff0000:"D. Fahrenheit\c" @@ -731,18 +739,16 @@ This example gets the DS called "exhaust" from database "demo.rrd" and puts the values in variable "cel". The CDEF used is evaluated as follows: - CDEF:far=cel,32,-,0.5555,* - 1. push variable "cel" - 2. push 32 - 3. push function "minus" and process it - The stack now contains values that are 32 less than "cel" - 4. push 0.5555 - 5. push function "multiply" and process it - 6. the resulting value is now "(cel-32)*0.55555" - -Note that if you take the Celsius to Fahrenheit function you should -be doing "5/9*(cel-32)" so 0.55555 is not exactly correct. It is close -enough for this purpose and it saves a calculation. + CDEF:far=9,5,/,cel,*,32,+ + 1. push 9, push 5 + 2. push function "divide" and process it + the stack now contains 9/5 + 3. push variable "cel" + 4. push function "multiply" and process it + the stack now contains 9/5*cel + 5. push 32 + 6. push function "plus" and process it + the stack contains now the temperature in Fahrenheit =head2 Changing unknown into zero @@ -760,9 +766,9 @@ These two CDEFs are built from several functions. It helps to split them when viewing what they do. Starting with the first CDEF we would get: - idat1,UN --> a - 0 --> b - idat1 --> c + idat1,UN --> a + 0 --> b + idat1 --> c if (a) then (b) else (c) The result is therefore "0" if it is true that "idat1" equals "UN". @@ -836,7 +842,7 @@ 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,*" - + =head2 Filtering data You may do some complex data filtering: @@ -856,7 +862,7 @@ You may do some complex data filtering: DEF:var=database.rrd:traffic:AVERAGE CDEF:prev1=PREV(var) - CDEF:time=TIME + CDEF:time=var,POP,TIME CDEF:prevtime=PREV(time) CDEF:derivate=var,prev1,-,time,prevtime,-,/ LINE3:derivate#000077:derivate @@ -869,7 +875,7 @@ This document was created from questions asked by either myself or by other people on the RRDtool mailing list. Please let me know if you find errors in it or if you have trouble understanding it. If you think there should be an addition, mail me: -Ealex@ergens.op.het.netE +Ealex@vandenbogaerdt.nlE Remember: B @@ -880,4 +886,4 @@ The RRDtool manpages =head1 AUTHOR Alex van den Bogaerdt -Ealex@ergens.op.het.netE +Ealex@vandenbogaerdt.nlE