doc/rrdgraph_rpn.src

   1 =head1 NAME
   2
   3 =cut
   4
   5 WARNING: DO NOT EDIT THE POD FILES. THEY ARE AUTO-GENERATED
   6
   7 =pod
   8
   9 rrdgraph_rpn - About RPN Math in rrdtool graph
  10
  11 =head1 SYNOPSIS
  12
  13 I<RPN expression>:=I<vname>|I<operator>|I<value>[,I<RPN expression>]
  14
  15 =head1 DESCRIPTION
  16
  17 If you have ever used a traditional HP calculator you already know
  18 B<RPN>. The idea behind B<RPN> is that you have a stack and push
  19 your data onto this stack. Whenever you execute an operation, it
  20 takes as many elements from the stack as needed. Pushing is done
  21 implicit so whenever you specify a number or a variable, it gets
  22 pushed automatically.
  23
  24 At the end of the calculation there should be one and exactly one
  25 value left on the stack.  This is the outcome of the function and
  26 this is what is put into the I<vname>.  For B<CDEF> instructions,
  27 the stack is processed for each data point on the graph. B<VDEF>
  28 instructions work on an entire data set in one run.
  29
  30 Example: C<VDEF:maximum=mydata,MAXIMUM>
  31
  32 This will set variable "maximum" which you now can use in the rest
  33 of your RRD script.
  34
  35 Example: C<CDEF:mydatabits=mydata,8,*>
  36
  37 This means:  push variable I<mydata>, push the number 8, execute
  38 the operator I<+>. The operator needs two elements and uses those
  39 to return one value.  This value is then stored in I<mydatabits>.
  40 As you may have guessed, this instruction means nothing more than
  41 I<mydatabits = mydata * 8>.  The real power of B<RPN> lies in the
  42 fact that it is always clear in which order to process the input.
  43 For expressions like C<a = b + 3 * 5> you need to multiply 3 with
  44 5 first before you add I<b> to get I<a>. However, with parentheses
  45 you could change this order: C<a = (b + 3) * 5>. In B<RPN>, you
  46 would do C<a = b, 3, +, 5, *> and need no parentheses.
  47
  48 =head1 OPERATORS
  49
  50 =over 4
  51
  52 =item Boolean operators
  53
  54 B<LT, LE, GT, GE, EQ, NE>
  55
  56 Pop two elements from the stack, compare them for the selected condition
  57 and return 1 for true or 0 for false. Comparing an I<unknown> or an
  58 I<infinite> value will always result in 0 (false).
  59
  60 B<UN, ISINF>
  61
  62 Pop one element from the stack, compare this to I<unknown> respectively
  63 to I<positive or negative infinity>. Returns 1 for true or 0 for false.
  64
  65 B<IF>
  66
  67 Pops three elements from the stack.  If the last element is 0 (false),
  68 the first value is pushed back onto the stack, otherwise the second
  69 popped value is pushed back. This does, indeed, mean that any value
  70 other than 0 is considered to be true.
  71
  72 Example: C<A,B,C,IF> should be read as C<if (A) then (B) else (C)>
  73
  74 Z<>
  75
  76 =item Comparing values
  77
  78 B<MIN, MAX>
  79
  80 Pops two elements from the stack and returns the lesser or larger.
  81 The two numbers shouldn't be I<infinite> or I<unknown>, if they are
  82 that value is pushed back onto the stack as the result.
  83
  84 B<LIMIT>
  85
  86 Pops two elements from the stack and uses them to define a range.
  87 Then it pops another element and if it falls inside the range, it
  88 is pushed back. If not, an I<unknown> is pushed.
  89
  90 The range defined includes the two boundaries (so: a number equal
  91 to one of the boundaries will be pushed back). If any of the three
  92 numbers involved is either I<unknown> or I<infinite> this function
  93 will always return an I<unknown>
  94
  95 Example: C<CDEF:a=alpha,0,100,LIMIT> will return I<unknown> if
  96 alpha is lower than 0 or if it is higher than 100.
  97
  98 Z<>
  99
 100 =item Arithmetics
 101
 102 B<+, -, *, /, %>
 103
 104 Add, subtract, multiply, divide, modulo
 105
 106 B<SIN, COS, LOG, EXP, SQRT>
 107
 108 Sine, cosine (input in radians), log, exp (natural logarithm), square root
 109
 110 B<ATAN>
 111
 112 Arctangent. Output in radians.
 113
 114 B<FLOOR, CEIL>
 115
 116 Round down,up to the nearest integer
 117
 118 Z<>
 119
 120 =item Set Operations
 121
 122 B<SORT, REV>
 123
 124 Pop one element from the stack.  This is the I<count> of items to be sorted
 125 (or reversed).  The top I<count> of the remaining elements are then sorted
 126 (or reversed) in place on the stack.
 127
 128 Example: C<CDEF:x=v1,v2,v3,v4,v5,v6,6,SORT,POP,5,REV,POP,+,+,+,4,/> will
 129 compute the average of the values v1..v6 after removing the smallest and
 130 largest.
 131
 132 B<TREND>
 133
 134 Create a "sliding window" average of another data series.
 135
 136 Usage:
 137 CDEF:smoothed=x,1800,TREND
 138
 139 This will create a half-hour (1800 second) sliding window average of x.  The
 140 average is essentially computed as shown here:
 141
 142                  +---!---!---!---!---!---!---!---!--->
 143                                                      now
 144                        delay     t0
 145                  <--------------->
 146                          delay       t1
 147                      <--------------->
 148                               delay      t2
 149                          <--------------->
 150
 151
 152      Value at sample (t0) will be the average between (t0-delay) and  (t0)
 153      Value at sample (t1) will be the average between (t1-delay) and  (t1)
 154      Value at sample (t2) will be the average between (t2-delay) and  (t2)
 155
 156 =item Special values
 157
 158 B<UNKN>
 159
 160 Pushes an unknown value on the stack
 161
 162 B<INF, NEGINF>
 163
 164 Pushes a positive or negative infinite value on the stack. When
 165 such a value is graphed, it appears at the top or bottom of the
 166 graph, no matter what the actual value on the y-axis is.
 167
 168 B<PREV>
 169
 170 Pushes an I<unknown> value if this is the first value of a data
 171 set or otherwise the result of this B<CDEF> at the previous time
 172 step. This allows you to do calculations across the data.  This
 173 function cannot be used in B<VDEF> instructions.
 174
 175 B<PREV(vname)>
 176
 177 Pushes an I<unknown> value if this is the first value of a data
 178 set or otherwise the result of vname variable at the previous time
 179 step. This allows you to do calculations across the data.  This
 180 function cannot be used in B<VDEF> instructions.
 181
 182 B<COUNT>
 183
 184 Pushes the number 1 if this is the first value of the data set, the
 185 number 2 if it is the second, and so on. This special value, allows
 186 you to make calculations based on the position of the value within
 187 the data set. This function cannot be used in B<VDEF> instructions.
 188
 189 Z<>
 190
 191 =item Time
 192
 193 Time inside RRDtool is measured in seconds since the epoch. This
 194 epoch is defined to be S<C<Thu Jan  1 00:00:00 UTC 1970>>.
 195
 196 B<NOW>
 197
 198 Pushes the current time on the stack.
 199
 200 B<TIME>
 201
 202 Pushes the time the currently processed value was taken onto the stack.
 203
 204 B<LTIME>
 205
 206 Takes the time as defined by B<TIME>, applies the time zone offset
 207 valid at that time including daylight saving time if your OS supports
 208 it, and pushes the result on the stack.  There is an elaborate example
 209 in the examples section on how to use this.
 210
 211 =item Processing the stack directly
 212
 213 B<DUP, POP, EXC>
 214
 215 Duplicate the top element, remove the top element, exchange the two
 216 top elements.
 217
 218 Z<>
 219
 220 =back
 221
 222 =head1 VARIABLES
 223
 224 These operators work only on B<VDEF> statements.
 225
 226 =over 4
 227
 228 =item MAXIMUM, MINIMUM, AVERAGE
 229
 230 Return the corresponding value, MAXIMUM and MINIMUM also return
 231 the first occurrence of that value in the time component.
 232
 233 Example: C<VDEF:avg=mydata,AVERAGE>
 234
 235 =item LAST, FIRST
 236
 237 Return the last,first value including its time.  The time for
 238 FIRST is actually the start of the corresponding interval, where
 239 the LAST time component returns the end of the corresponding interval.
 240
 241 Example: C<VDEF:first=mydata,FIRST>
 242
 243 =item TOTAL
 244
 245 Returns the rate from each defined time slot multiplied with the
 246 step size.  This can for instance return total bytes transfered
 247 when you have logged bytes per second. The time component returns
 248 the amount of seconds
 249
 250 Example: C<VDEF:total=mydata,TOTAL>
 251
 252 =item PERCENT
 253
 254 Should follow a B<DEF> or B<CDEF> I<vname>. This I<vname> is popped,
 255 another number is popped which is a certain percentage (0..100). The
 256 data set is then sorted and the value returned is chosen such that
 257 I<percentage> percent of the values is lower or equal than the result.
 258 I<Unknown> values are considered lower than any finite number for this
 259 purpose so if this operator returns an I<unknown> you have quite a lot
 260 of them in your data.  B<Inf>inite numbers are lesser, or more, than the
 261 finite numbers and are always more than the I<Unknown> numbers.
 262 (NaN E<lt> -INF E<lt> finite values E<lt> INF)
 263
 264 Example: C<VDEF:perc95=mydata,95,PERCENT>
 265
 266 =back
 267
 268 =include see_also