doc/rrdgraph_rpn.txt

   1 RRDGRAPH_RPN(1)                     rrdtool                    RRDGRAPH_RPN(1)
   2
   3
   4
   5 N\bNA\bAM\bME\bE
   6        rrdgraph_rpn - About RPN Math in rrdtool graph
   7
   8 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
   9        _\bR_\bP_\bN _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn:=_\bv_\bn_\ba_\bm_\be|_\bo_\bp_\be_\br_\ba_\bt_\bo_\br|_\bv_\ba_\bl_\bu_\be[,_\bR_\bP_\bN _\be_\bx_\bp_\br_\be_\bs_\bs_\bi_\bo_\bn]
  10
  11 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  12        If you have ever used a traditional HP calculator you already know R\bRP\bPN\bN
  13        (Reverse Polish Notation).  The idea behind R\bRP\bPN\bN is that you have a
  14        stack and push your data onto this stack. Whenever you execute an
  15        operation, it takes as many elements from the stack as needed. Pushing
  16        is done implicitly, so whenever you specify a number or a variable, it
  17        gets pushed onto the stack automatically.
  18
  19        At the end of the calculation there should be one and only one value
  20        left on the stack.  This is the outcome of the function and this is
  21        what is put into the _\bv_\bn_\ba_\bm_\be.  For C\bCD\bDE\bEF\bF instructions, the stack is
  22        processed for each data point on the graph. V\bVD\bDE\bEF\bF instructions work on
  23        an entire data set in one run. Note, that currently V\bVD\bDE\bEF\bF instructions
  24        only support a limited list of functions.
  25
  26        Example: "VDEF:maximum=mydata,MAXIMUM"
  27
  28        This will set variable "maximum" which you now can use in the rest of
  29        your RRD script.
  30
  31        Example: "CDEF:mydatabits=mydata,8,*"
  32
  33        This means:  push variable _\bm_\by_\bd_\ba_\bt_\ba, push the number 8, execute the
  34        operator _\b*. The operator needs two elements and uses those to return
  35        one value.  This value is then stored in _\bm_\by_\bd_\ba_\bt_\ba_\bb_\bi_\bt_\bs.  As you may have
  36        guessed, this instruction means nothing more than _\bm_\by_\bd_\ba_\bt_\ba_\bb_\bi_\bt_\bs _\b= _\bm_\by_\bd_\ba_\bt_\ba _\b*
  37        _\b8.  The real power of R\bRP\bPN\bN lies in the fact that it is always clear in
  38        which order to process the input.  For expressions like "a = b + 3 * 5"
  39        you need to multiply 3 with 5 first before you add _\bb to get _\ba. However,
  40        with parentheses you could change this order: "a = (b + 3) * 5". In
  41        R\bRP\bPN\bN, you would do "a = b, 3, +, 5, *" without the need for parentheses.
  42
  43 O\bOP\bPE\bER\bRA\bAT\bTO\bOR\bRS\bS
  44        Boolean operators
  45            L\bLT\bT,\b, L\bLE\bE,\b, G\bGT\bT,\b, G\bGE\bE,\b, E\bEQ\bQ,\b, N\bNE\bE
  46
  47            Pop two elements from the stack, compare them for the selected
  48            condition and return 1 for true or 0 for false. Comparing an
  49            _\bu_\bn_\bk_\bn_\bo_\bw_\bn or an _\bi_\bn_\bf_\bi_\bn_\bi_\bt_\be value will result in _\bu_\bn_\bk_\bn_\bo_\bw_\bn returned ...
  50            which will also be treated as false by the I\bIF\bF call.
  51
  52            U\bUN\bN,\b, I\bIS\bSI\bIN\bNF\bF
  53
  54            Pop one element from the stack, compare this to _\bu_\bn_\bk_\bn_\bo_\bw_\bn
  55            respectively to _\bp_\bo_\bs_\bi_\bt_\bi_\bv_\be _\bo_\br _\bn_\be_\bg_\ba_\bt_\bi_\bv_\be _\bi_\bn_\bf_\bi_\bn_\bi_\bt_\by. Returns 1 for true
  56            or 0 for false.
  57
  58            I\bIF\bF
  59
  60            Pops three elements from the stack.  If the element popped last is
  61            0 (false), the value popped first is pushed back onto the stack,
  62            otherwise the value popped second is pushed back. This does,
  63            indeed, mean that any value other than 0 is considered to be true.
  64
  65            Example: "A,B,C,IF" should be read as "if (A) then (B) else (C)"
  66
  67
  68
  69        Comparing values
  70            M\bMI\bIN\bN,\b, M\bMA\bAX\bX
  71
  72            Pops two elements from the stack and returns the smaller or larger,
  73            respectively.  Note that _\bi_\bn_\bf_\bi_\bn_\bi_\bt_\be is larger than anything else.  If
  74            one of the input numbers is _\bu_\bn_\bk_\bn_\bo_\bw_\bn then the result of the
  75            operation will be _\bu_\bn_\bk_\bn_\bo_\bw_\bn too.
  76
  77            L\bLI\bIM\bMI\bIT\bT
  78
  79            Pops two elements from the stack and uses them to define a range.
  80            Then it pops another element and if it falls inside the range, it
  81            is pushed back. If not, an _\bu_\bn_\bk_\bn_\bo_\bw_\bn is pushed.
  82
  83            The range defined includes the two boundaries (so: a number equal
  84            to one of the boundaries will be pushed back). If any of the three
  85            numbers involved is either _\bu_\bn_\bk_\bn_\bo_\bw_\bn or _\bi_\bn_\bf_\bi_\bn_\bi_\bt_\be this function will
  86            always return an _\bu_\bn_\bk_\bn_\bo_\bw_\bn
  87
  88            Example: "CDEF:a=alpha,0,100,LIMIT" will return _\bu_\bn_\bk_\bn_\bo_\bw_\bn if alpha is
  89            lower than 0 or if it is higher than 100.
  90
  91
  92
  93        Arithmetics
  94            +\b+,\b, -\b-,\b, *\b*,\b, /\b/,\b, %\b%
  95
  96            Add, subtract, multiply, divide, modulo
  97
  98            A\bAD\bDD\bDN\bNA\bAN\bN
  99
 100            NAN-safe addition. If one parameter is NAN/UNKNOWN it'll be treated
 101            as zero. If both parameters are NAN/UNKNOWN, NAN/UNKNOWN will be
 102            returned.
 103
 104            S\bSI\bIN\bN,\b, C\bCO\bOS\bS,\b, L\bLO\bOG\bG,\b, E\bEX\bXP\bP,\b, S\bSQ\bQR\bRT\bT
 105
 106            Sine and cosine (input in radians), log and exp (natural
 107            logarithm), square root.
 108
 109            A\bAT\bTA\bAN\bN
 110
 111            Arctangent (output in radians).
 112
 113            A\bAT\bTA\bAN\bN2\b2
 114
 115            Arctangent of y,x components (output in radians).  This pops one
 116            element from the stack, the x (cosine) component, and then a
 117            second, which is the y (sine) component.  It then pushes the
 118            arctangent of their ratio, resolving the ambiguity between
 119            quadrants.
 120
 121            Example: "CDEF:angle=Y,X,ATAN2,RAD2DEG" will convert "X,Y"
 122            components into an angle in degrees.
 123
 124            F\bFL\bLO\bOO\bOR\bR,\b, C\bCE\bEI\bIL\bL
 125
 126            Round down or up to the nearest integer.
 127
 128            D\bDE\bEG\bG2\b2R\bRA\bAD\bD,\b, R\bRA\bAD\bD2\b2D\bDE\bEG\bG
 129
 130            Convert angle in degrees to radians, or radians to degrees.
 131
 132            A\bAB\bBS\bS
 133
 134            Take the absolute value.
 135
 136        Set Operations
 137            S\bSO\bOR\bRT\bT,\b, R\bRE\bEV\bV
 138
 139            Pop one element from the stack.  This is the _\bc_\bo_\bu_\bn_\bt of items to be
 140            sorted (or reversed).  The top _\bc_\bo_\bu_\bn_\bt of the remaining elements are
 141            then sorted (or reversed) in place on the stack.
 142
 143            Example: "CDEF:x=v1,v2,v3,v4,v5,v6,6,SORT,POP,5,REV,POP,+,+,+,4,/"
 144            will compute the average of the values v1 to v6 after removing the
 145            smallest and largest.
 146
 147            A\bAV\bVG\bG
 148
 149            Pop one element (_\bc_\bo_\bu_\bn_\bt) from the stack. Now pop _\bc_\bo_\bu_\bn_\bt elements and
 150            build the average, ignoring all UNKNOWN values in the process.
 151
 152            Example: "CDEF:x=a,b,c,d,4,AVG"
 153
 154            T\bTR\bRE\bEN\bND\bD,\b, T\bTR\bRE\bEN\bND\bDN\bNA\bAN\bN
 155
 156            Create a "sliding window" average of another data series.
 157
 158            Usage: CDEF:smoothed=x,1800,TREND
 159
 160            This will create a half-hour (1800 second) sliding window average
 161            of x.  The average is essentially computed as shown here:
 162
 163                             +---!---!---!---!---!---!---!---!--->
 164                                                                 now
 165                                   delay     t0
 166                             <--------------->
 167                                     delay       t1
 168                                 <--------------->
 169                                          delay      t2
 170                                     <--------------->
 171
 172
 173                 Value at sample (t0) will be the average between (t0-delay) and (t0)
 174                 Value at sample (t1) will be the average between (t1-delay) and (t1)
 175                 Value at sample (t2) will be the average between (t2-delay) and (t2)
 176
 177            TRENDNAN is - in contrast to TREND - NAN-safe. If you use TREND and
 178            one source value is NAN the complete sliding window is affected.
 179            The TRENDNAN operation ignores all NAN-values in a sliding window
 180            and computes the average of the remaining values.
 181
 182            P\bPR\bRE\bED\bDI\bIC\bCT\bT,\b, P\bPR\bRE\bED\bDI\bIC\bCT\bTS\bSI\bIG\bGM\bMA\bA
 183
 184            Create a "sliding window" average/sigma of another data series,
 185            that also shifts the data series by given amounts of of time as
 186            well
 187
 188            Usage - explicit stating shifts: CDEF:predict=<shift n>,...,<shift
 189            1>,n,<window>,x,PREDICT CDEF:sigma=<shift n>,...,<shift
 190            1>,n,<window>,x,PREDICTSIGMA
 191
 192            Usage - shifts defined as a base shift and a number of time this is
 193            applied CDEF:predict=<shift multiplier>,-n,<window>,x,PREDICT
 194            CDEF:sigma=<shift multiplier>,-n,<window>,x,PREDICTSIGMA
 195
 196            Example: CDEF:predict=172800,86400,2,1800,x,PREDICT
 197
 198            This will create a half-hour (1800 second) sliding window
 199            average/sigma of x, that average is essentially computed as shown
 200            here:
 201
 202             +---!---!---!---!---!---!---!---!---!---!---!---!---!---!---!---!---!--->
 203                                                                                 now
 204                                                              shift 1        t0
 205                                                     <----------------------->
 206                                           window
 207                                     <--------------->
 208                                                   shift 2
 209                             <----------------------------------------------->
 210                   window
 211             <--------------->
 212                                                                  shift 1        t1
 213                                                         <----------------------->
 214                                               window
 215                                         <--------------->
 216                                                        shift 2
 217                                 <----------------------------------------------->
 218                       window
 219                 <--------------->
 220
 221             Value at sample (t0) will be the average between (t0-shift1-window) and (t0-shift1)
 222                                                  and between (t0-shift2-window) and (t0-shift2)
 223             Value at sample (t1) will be the average between (t1-shift1-window) and (t1-shift1)
 224                                                  and between (t1-shift2-window) and (t1-shift2)
 225
 226            The function is by design NAN-safe.  This also allows for
 227            extrapolation into the future (say a few days) - you may need to
 228            define the data series whit the optional start= parameter, so that
 229            the source data series has enough data to provide prediction also
 230            at the beginning of a graph...
 231
 232            Here an example, that will create a 10 day graph that also shows
 233            the prediction 3 days into the future with its uncertainty value
 234            (as defined by avg+-4*sigma) This also shows if the prediction is
 235            exceeded at a certain point.
 236
 237            rrdtool graph image.png --imgformat=PNG \
 238             --start=-7days --end=+3days --width=1000 --height=200
 239            --alt-autoscale-max \
 240             DEF:value=value.rrd:value:AVERAGE:start=-14days \
 241             LINE1:value#ff0000:value \
 242             CDEF:predict=86400,-7,1800,value,PREDICT \
 243             CDEF:sigma=86400,-7,1800,value,PREDICTSIGMA \
 244             CDEF:upper=predict,sigma,3,*,+ \
 245             CDEF:lower=predict,sigma,3,*,- \
 246             LINE1:predict#00ff00:prediction \
 247             LINE1:upper#0000ff:upper\ certainty\ limit \
 248             LINE1:lower#0000ff:lower\ certainty\ limit \
 249             CDEF:exceeds=value,UN,0,value,lower,upper,LIMIT,UN,IF \
 250             TICK:exceeds#aa000080:1
 251
 252            Note: Experience has shown that a factor between 3 and 5 to scale
 253            sigma is a good discriminator to detect abnormal behavior. This
 254            obviously depends also on the type of data and how "noisy" the data
 255            series is.
 256
 257            This prediction can only be used for short term extrapolations -
 258            say a few days into the future-
 259
 260        Special values
 261            U\bUN\bNK\bKN\bN
 262
 263            Pushes an unknown value on the stack
 264
 265            I\bIN\bNF\bF,\b, N\bNE\bEG\bGI\bIN\bNF\bF
 266
 267            Pushes a positive or negative infinite value on the stack. When
 268            such a value is graphed, it appears at the top or bottom of the
 269            graph, no matter what the actual value on the y-axis is.
 270
 271            P\bPR\bRE\bEV\bV
 272
 273            Pushes an _\bu_\bn_\bk_\bn_\bo_\bw_\bn value if this is the first value of a data set or
 274            otherwise the result of this C\bCD\bDE\bEF\bF at the previous time step. This
 275            allows you to do calculations across the data.  This function
 276            cannot be used in V\bVD\bDE\bEF\bF instructions.
 277
 278            P\bPR\bRE\bEV\bV(\b(v\bvn\bna\bam\bme\be)\b)
 279
 280            Pushes an _\bu_\bn_\bk_\bn_\bo_\bw_\bn value if this is the first value of a data set or
 281            otherwise the result of the vname variable at the previous time
 282            step. This allows you to do calculations across the data. This
 283            function cannot be used in V\bVD\bDE\bEF\bF instructions.
 284
 285            C\bCO\bOU\bUN\bNT\bT
 286
 287            Pushes the number 1 if this is the first value of the data set, the
 288            number 2 if it is the second, and so on. This special value allows
 289            you to make calculations based on the position of the value within
 290            the data set. This function cannot be used in V\bVD\bDE\bEF\bF instructions.
 291
 292        Time
 293            Time inside RRDtool is measured in seconds since the epoch. The
 294            epoch is defined to be "Thu Jan  1 00:00:00 UTC 1970".
 295
 296            N\bNO\bOW\bW
 297
 298            Pushes the current time on the stack.
 299
 300            T\bTI\bIM\bME\bE
 301
 302            Pushes the time the currently processed value was taken at onto the
 303            stack.
 304
 305            L\bLT\bTI\bIM\bME\bE
 306
 307            Takes the time as defined by T\bTI\bIM\bME\bE, applies the time zone offset
 308            valid at that time including daylight saving time if your OS
 309            supports it, and pushes the result on the stack.  There is an
 310            elaborate example in the examples section below on how to use this.
 311
 312        Processing the stack directly
 313            D\bDU\bUP\bP,\b, P\bPO\bOP\bP,\b, E\bEX\bXC\bC
 314
 315            Duplicate the top element, remove the top element, exchange the two
 316            top elements.
 317
 318
 319
 320 V\bVA\bAR\bRI\bIA\bAB\bBL\bLE\bES\bS
 321        These operators work only on V\bVD\bDE\bEF\bF statements. Note that currently ONLY
 322        these work for V\bVD\bDE\bEF\bF.
 323
 324        MAXIMUM, MINIMUM, AVERAGE
 325            Return the corresponding value, MAXIMUM and MINIMUM also return the
 326            first occurrence of that value in the time component.
 327
 328            Example: "VDEF:avg=mydata,AVERAGE"
 329
 330        STDEV
 331            Returns the standard deviation of the values.
 332
 333            Example: "VDEF:stdev=mydata,STDEV"
 334
 335        LAST, FIRST
 336            Return the last/first non-nan or infinite value for the selected
 337            data stream, including its timestamp.
 338
 339            Example: "VDEF:first=mydata,FIRST"
 340
 341        TOTAL
 342            Returns the rate from each defined time slot multiplied with the
 343            step size.  This can, for instance, return total bytes transferred
 344            when you have logged bytes per second. The time component returns
 345            the number of seconds.
 346
 347            Example: "VDEF:total=mydata,TOTAL"
 348
 349        PERCENT, PERCENTNAN
 350            This should follow a D\bDE\bEF\bF or C\bCD\bDE\bEF\bF _\bv_\bn_\ba_\bm_\be. The _\bv_\bn_\ba_\bm_\be is popped,
 351            another number is popped which is a certain percentage (0..100).
 352            The data set is then sorted and the value returned is chosen such
 353            that _\bp_\be_\br_\bc_\be_\bn_\bt_\ba_\bg_\be percent of the values is lower or equal than the
 354            result.  For PERCENTNAN _\bU_\bn_\bk_\bn_\bo_\bw_\bn values are ignored, but for PERCENT
 355            _\bU_\bn_\bk_\bn_\bo_\bw_\bn values are considered lower than any finite number for this
 356            purpose so if this operator returns an _\bu_\bn_\bk_\bn_\bo_\bw_\bn you have quite a lot
 357            of them in your data.  I\bIn\bnf\bfinite numbers are lesser, or more, than
 358            the finite numbers and are always more than the _\bU_\bn_\bk_\bn_\bo_\bw_\bn numbers.
 359            (NaN < -INF < finite values < INF)
 360
 361            Example: "VDEF:perc95=mydata,95,PERCENT"
 362                     "VDEF:percnan95=mydata,95,PERCENTNAN"
 363
 364        LSLSLOPE, LSLINT, LSLCORREL
 365            Return the parameters for a L\bLeast S\bSquares L\bLine _\b(_\by _\b= _\bm_\bx _\b+_\bb_\b) which
 366            approximate the provided dataset.  LSLSLOPE is the slope _\b(_\bm_\b) of the
 367            line related to the COUNT position of the data.  LSLINT is the
 368            y-intercept _\b(_\bb_\b), which happens also to be the first data point on
 369            the graph. LSLCORREL is the Correlation Coefficient (also know as
 370            Pearson's Product Moment Correlation Coefficient).  It will range
 371            from 0 to +/-1 and represents the quality of fit for the
 372            approximation.
 373
 374            Example: "VDEF:slope=mydata,LSLSLOPE"
 375
 376 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
 377        rrdgraph gives an overview of how r\brr\brd\bdt\bto\boo\bol\bl g\bgr\bra\bap\bph\bh works.  rrdgraph_data
 378        describes D\bDE\bEF\bF,C\bCD\bDE\bEF\bF and V\bVD\bDE\bEF\bF in detail.  rrdgraph_rpn describes the R\bRP\bPN\bN
 379        language used in the ?\b?D\bDE\bEF\bF statements.  rrdgraph_graph page describes
 380        all of the graph and print functions.
 381
 382        Make sure to read rrdgraph_examples for tips&tricks.
 383
 384 A\bAU\bUT\bTH\bHO\bOR\bR
 385        Program by Tobias Oetiker <tobi@oetiker.ch>
 386
 387        This manual page by Alex van den Bogaerdt <alex@vandenbogaerdt.nl> with
 388        corrections and/or additions by several people
 389
 390
 391
 392 1.4.8                             2013-05-23                   RRDGRAPH_RPN(1)