rrdFilter module


The rrdFile Javascript module implements a set of classes that can be used to extract information from RRD archives loaded as binary file objects.


Overview

The rrdFilter module is allows filters to be applied to DSs (datasources) and RRA objects.

(These classes should have almost idential instantiations to their rrdFile module equivilents.)

For DSs, filters can either be a list of DSs to filter out (*FilterDS), or a user-created and customized filter object (*FilterOp - for example, mathematical functions like summing and averaging DSs).

THese classes are:

For RRAs, two things can be done - An RRA can be shifted by any number of seconds (for timezone selection, for instance) [RRDFilterShift], or any number of new RRAs can be created (based on other RRAs) with their data averaged [RRDRRAFilterAvg]. See individual classes for details.

These classes are:

Internal classes for Developers, Listed at the End:

  • RRDRRAFilterDS
  • RRDRRAFilterOp
  • RRDDSFilterOp
  • RRAFilterAvg
  • RRAInfoFilterAvg.

    Main Classes:


    RRD Filter Classes:

    Class RRDFilterDS

    This class filters out a subset of DSs from an RRD identified by index or name.

    This class implements the following methods:

    Method

    Description

    getMinSteps()

    Return the base interval in seconds that was used to feed the RRD file.

    getLastUpdate()

    Return the timestamp of the last update.

    getNrDSs()

    Return the number of Data Sources present in the RRD file.

    getDSNames()

    Return the names of the Data Sources present in the RRD file.

    getDS(id)

    If id is a number, return an object of type RRDDS holding the information about the id-th Data Source.

    If id is a string, return an object of type RRDDS holding the information about the Data Source with the requested name.

    getNrRRAs()

    Return the number of Round Robin Archives present in the RRD file.

    getRRAInfo(n)

    Return an object of type RRDRRAInfo holding the information about the n-th Round Robin Archive.

    getRRA(n)

    Return an object of type RRDRRA that can be used to access the values stored in the n-th Round Robin Archive.

    Class RRDFilterOp

    This class filters all of the DSs in an RRD by a list of filter objects.

     The filter object must implement the following interface
       getName()               - Symbolic name give to this function
       getDSName()             - list of DSs used in computing the result (names or indexes)
       computeResult(val_list) - val_list contains the values of the requested DSs (in the same order) 
    
     Example classes that implement the interface:
       function DoNothing(ds_name) { //Leaves the DS alone.
         this.getName = function() {return ds_name;}
         this.getDSNames = function() {return [ds1_name];}
         this.computeResult = function(val_list) {return val_list[0];}
       }
       function sumDS(ds1_name,ds2_name) { //Sums the two DSs.
         this.getName = function() {return ds1_name+"+"+ds2_name;}
         this.getDSNames = function() {return [ds1_name,ds2_name];}
         this.computeResult = function(val_list) {return val_list[0]+val_list[1];}
       }
    
     Lets say you have 2 DSs. To add a summed DS of DS1 and DS2: 
     var ds0_name = rrd_data.getDS(0).getName();
     var ds1_name = rrd_data.getDS(1).getName();
     rrd_data = new RRDFilterOp(rrd_data, [new DoNothing(ds0_name), 
                         DoNothing(ds1_name), sumDS(ds0_name, ds1_name]);
    

    Its arguments are: rrd_file and op_obj_list (list of ds filters).

    This class implements the following methods:

    Method

    Description

    getMinSteps()

    Return the base interval in seconds that was used to feed the RRD file.

    getLastUpdate()

    Return the timestamp of the last update.

    getNrDSs()

    Return the number of Data Sources present in the RRD file.

    getDSNames()

    Return the names of the Data Sources present in the RRD file.

    getDS(id)

    If id is a number, return an object of type RRDDS holding the information about the id-th Data Source.

    If id is a string, return an object of type RRDDS holding the information about the Data Source with the requested name.

    getNrRRAs()

    Return the number of Round Robin Archives present in the RRD file.

    getRRAInfo(n)

    Return an object of type RRDRRAInfo holding the information about the n-th Round Robin Archive.

    getRRA(n)

    Return an object of type RRDRRA that can be used to access the values stored in the n-th Round Robin Archive.


    RRA Filters:

    Class RRAFilterShift

    This class creates new, time-shifted RRAs. Originally developed for timezone shifting.

    Arguments:

    This class implements the following methods:

    Method

    Description

    getMinSteps()

    Return the base interval in seconds that was used to feed the RRD file.

    getLastUpdate()

    Return the timestamp of the last update.

    getNrDSs()

    Return the number of Data Sources present in the RRD file.

    getDSNames()

    Return the names of the Data Sources present in the RRD file.

    getDS(id)

    If id is a number, return an object of type RRDDS holding the information about the id-th Data Source.

    If id is a string, return an object of type RRDDS holding the information about the Data Source with the requested name.

    getNrRRAs()

    Return the number of Round Robin Archives present in the RRD file.

    getRRAInfo(n)

    Return an object of type RRDRRAInfo holding the information about the n-th Round Robin Archive.

    getRRA(n)

    Return an object of type RRDRRA that can be used to access the values stored in the n-th Round Robin Archive.


    Class RRDRRAFilterAvg

    This class creates new RRAs (based on original RRAs in the RRD File) that have different time steps. This is useful for creating new RRA graphs with different time steps without actually creating and filling new RRAs.

    Arguments:

    Examples of RRA Filter Objects:

          //This RRA Filter object leaves the original RRA unchanged.
          function RRADoNothing(rra_idx) {
             this.getIdx = function() {return rra_idx;}
             this.getStep = function() {return null;} 
          }
          
          /* This Filter creates a new RRA with a different step size 
          / based on another RRA, whose data the new RRA averages. 
          / rra_idx should be index of RRA with largest step size 
          / that doesn't exceed new step size. */ 
    
          function RRA_Avg(rra_idx,new_step_in_seconds) {
             this.getIdx = function() {return rra_idx;}
             this.getStep = function() {return new_step_in_seconds;}
          }
    

    For instance, if you have 3 RRAs with 5 second, 60 second and 3600 second intervals, and would like an RRA with 1800 second steps along with them, create:

     new RRDRRAFilterAvg(rrd_file, object_list);
          object_list = [new RRADoNothing(0), new RRADoNothing(1), new RRADoNothing(2), new RRA_Avg(1,1800)].  
    

    It's best to use the RRA with the next smallest step size as a basis. It's also best to make steps integer multiples of the original RRA step sizes. For instance, using a 45 minute step, a 6 hour (= 45mins x 8) step would be better than 4 hour step (=45 mins x 5.33...).

    This class implements the following methods:

    Method

    Description

    getMinSteps()

    Return the base interval in seconds that was used to feed the RRD file.

    getLastUpdate()

    Return the timestamp of the last update.

    getNrDSs()

    Return the number of Data Sources present in the RRD file.

    getDSNames()

    Return the names of the Data Sources present in the RRD file.

    getDS(id)

    If id is a number, return an object of type RRDDS holding the information about the id-th Data Source.

    If id is a string, return an object of type RRDDS holding the information about the Data Source with the requested name.

    getNrRRAs()

    Return the number of Round Robin Archives present in the RRD file.

    getRRAInfo(n)

    Return an object of type RRDRRAInfo holding the information about the n-th Round Robin Archive.

    getRRA(n)

    Return an object of type RRDRRA that can be used to access the values stored in the n-th Round Robin Archive.


    Internal Methods for Developers

    For RRDFilterDS:

    Class RRDRRAFilterDS

    This class filters out a subset of DSs from an RRA identified by index or name.

    The constructor has two arguments: rrd_rra (the RRA) and ds_list (the list of DSs to filter).

    This class implements the following methods:

    Method

    Description

    getIdx()

    Return which RRA it is in the RRD file.

    getNrRows()

    Return the number of rows in the RRA.

    getNrDSs()

    Return the number of DSs in the RRD file.

    getStep()

    Return the number of seconds between rows.

    getCFName()

    Return the Consolidation Function used by the RRA.

    getEl(r,d)

    Return the value for the d-th DS in the r-th row.

    getElFast(r,d)

    Return the low-precision value for the d-th DS in the r-th row.

    Class RRDDSFilterOp

    This class filters DSs from an RRD by using a user-provided filter object.

    This class has three arguments: rrd_file, op_object (the filter object) and my_idx (index of new DS in case old one was modified by a filter).

    This class implements the following methods:

    Method

    Description

    getIdx()

    Return which DS it is in the RRD file.

    getName()

    Return the name of the data source.

    getType()

    Return the type of the data source.

    getMin()

    Return the minimum and maximum value the data source can contain.

    If either is not defined, undefined is returned.

    getMax()

    getRealDSList()

    Returns which DSs is being used in the Filter.

    ComputeResult()

    Return the computed result of the filter object on the DSs.


    For RRDRRAFilterAvg:

    Class RRAFilterAvg

    The constructor has two arguments: the RRA and the Filter object for that RRA.

    The filter changes the NrRows (number of rows) and the way the elements are fetched (getEl and getElFast).

    All other attributes are copied from the base RRA (the rra given in the arguments).

    Method

    Description

    getIdx()

    Return which RRA it is in the RRD file (real index, not base RRA index).

    getNrRows()

    Return the number of rows in the RRA.

    getNrDSs()

    Return the number of DSs in the RRD file.

    getStep()

    Return the number of seconds between rows.

    getCFName()

    Return the Consolidation Function used by the RRA.

    getEl(r,d)

    Return the value for the d-th DS in the r-th row, modified by the filter.

    getElFast(r,d)

    Return the low-precision value for the d-th DS in the r-th row, modified by the filter.

    Class RRAInfoFilterAvg

    This class implements the methods needed to access the new RRA. The filter only changes the PdpPerRow.

    Method

    Description

    getIdx()

    Return which RRA it is in the RRD file.

    getNrRows()

    Return the number of rows in the RRA.

    getStep()

    Return the number of seconds between rows.

    getCFName()

    Return the Consolidation Function used by the RRA.

    getPdpPerRow()

    Return number of slots used for consolidation.


    This module is part of the javascriptRRD package hosted at http://javascriptrrd.sourceforge.net.
    It is licensed under the MIT license.