rrdFilter module

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:

• RRDFilterDS
• RRDFilterOp

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:

• RRDFilterShift
• RRDRRAFilterAvg

Internal classes for Developers, Listed at the End:

• RRDRRAFilterDS
• RRDRRAFilterOp
• RRDDSFilterOp
• RRAFilterAvg
• RRAInfoFilterAvg.

Main Classes:

RRD Filter Classes:

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 Itentity(ds_name) { //Leaves the DS alone.
     this.getName = function() {return ds_name;}
     this.getDSNames = function() {return [ds_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 Identity(ds0_name), 
                     new Itentity(ds1_name), new sumDS(ds0_name, ds1_name]);

If a string is passed, it is assumed to be the name of a DS, and the Identity transformation is applied.
If an integer is passed, it is assumed to be the index or a DS, and the Identity equivalent is applied.
So this gives an equivalent result:

 rrd_data = new RRDFilterOp(rrd_data, [ds0_name,1, new sumDS(ds0_name, ds1_name]);

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

This class implements the following methods:

RRA Filters:

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:

• 1. The RRD File
• 2. List of Filter Objects. Each object must instantiate getIdx, which returns the index of the RRA to use in the RRD File, and getStep, which returns the step size of the RRA. (If getStep returns null, the filter will use the original step size given by the RRA specified by getIdx).

Examples of RRA Filter Objects:

      //This RRA Filter object leaves the original RRA unchanged.
      function RRAIdentity(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:

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

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...).

Given that the above classes are likely the most useful ones, the user can use an integer instead of a RRAIdentity object, and an Array(2) instead of the RRA_Avg object:

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

This class implements the following methods:

Class RRDFilterDS

Note: This class is deprecated. Use RRDFilterOp instead.

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

This class implements the following methods:

Class RRAFilterShift

This class creates new, time-shifted RRAs. Originally developed for timezone shifting. Currently to be considered deprecated.

Arguments:

• 1. The RRD File
• 2. Shift Int - the number of seconds to shift by (1 hour = 3600s).
• 3. RRA index List - A list of the RRAs (by their indicies) to be shifted; usually all RRAs in the File are included.

This class implements the following methods:

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:

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:

For RRDRRAFilterAvg:

Class RRAFilterAvg

Class RRAInfoFilterAvg

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