How to use Filters to customise your Measurement Collection¶

1. Prerequisites¶

• Make sure that you understand how OMF works from a user's point of view.
• Make sure that you have completed and understood the basic "Hello World" tutorial.

2. Goal¶

• This tutorial shows you how to use Filters within your Experiment Description.
• A Filter allows you to perform some pre-processing on a specific measurement stream at the resource that produces it. The resulting pre-processed measurements are then sent to the measurement collection server.
• Such pre-processing can help you dramatically reduce the volume of collected measurement by only collecting integrated metrics, such as average or standard-deviation over a specific range of samples.

• About Filters:
  • They are defined and made available to you by the OML Client Library, which should be installed on your resources.
  • OML has a set of Filters which you can use: OML list of available filters
  • You can also define your own Filter, as described on the Developing OML Filter page

3. Scenario¶

• Here we are using the same simple scenario as in the basic "Hello World" tutorial.
• We add a few properties to that simple experiment, similar to what we did in the "How to pass parameter to your experiment" tutorial.
• However, instead of collecting all the measurements as in the "Hello World" tutorial, here we use the "avg" (average) and "sum" filters to pre-process them and to only collect the resulting integrated measurements.

4. The New "Hello World" Experiment Description¶

The Experiment Description (ED) describing this simple experiment is (download it here: using-filters.rb):

 1 defProperty('theSender', 'omf.nicta.node1', "ID of sender node")
 2 defProperty('theReceiver', 'omf.nicta.node2', "ID of receiver node")
 3 defProperty('packetsize', 256, "Packet size (byte) from the sender node")
 4 defProperty('runtime', 30, "Time in second for the experiment is to run")
 5 
 6 defGroup('Sender',property.theSender) do |node|
 7   node.addApplication("test:app:otg2") do |app|
 8     app.setProperty('udp:local_host', '192.168.0.2')
 9     app.setProperty('udp:dst_host', '192.168.0.3')
10     app.setProperty('udp:dst_port', 3000)
11     app.setProperty('cbr:size', property.packetsize)
12     app.measure('udp_out', :samples => 3) do |mp|
13       mp.filter('seq_no', 'avg')
14     end
15   end
16   node.net.w0.mode = "adhoc" 
17   node.net.w0.type = 'g'
18   node.net.w0.channel = "6" 
19   node.net.w0.essid = "helloworld" 
20   node.net.w0.ip = "192.168.0.2" 
21 end
22 
23 defGroup('Receiver',property.theReceiver) do |node|
24   node.addApplication("test:app:otr2") do |app|
25     app.setProperty('udp:local_host', '192.168.0.3')
26     app.setProperty('udp:local_port', 3000)
27     app.measure('udp_in', :samples => 2) do |mp|
28       mp.filter('pkt_length', 'sum')
29       mp.filter('seq_no', 'avg')
30     end
31   end
32   node.net.w0.mode = "adhoc" 
33   node.net.w0.type = 'g'
34   node.net.w0.channel = "6" 
35   node.net.w0.essid = "helloworld" 
36   node.net.w0.ip = "192.168.0.3" 
37 end
38 
39 onEvent(:ALL_UP_AND_INSTALLED) do |event|
40   wait 10
41   allGroups.startApplications
42   wait property.runtime / 2
43   property.packetsize = 512
44   wait property.runtime / 2
45   allGroups.stopApplications
46   Experiment.done
47 end

The Experiment Description (ED) describing this simple experiment is (download it here: using-filters.rb):

• Line 12-14: we define the measurement to collect and an associated filter to apply:
  • Line 12: similar to the "Hello World" tutorial, we request the collection of measurements from the "udp_out" Measurement Point (MP) at regular intervals of 3 samples.
  • Line 13: we define a filter to apply to these measurements (i.e. pre-processing on the node before collection by the OML server)
    • here we want to apply the filter to the seq_no metric within a measurement
    • the filter to apply is the avg one, which will return the average value of the selected metric (seq_no) over the sampling interval (= 3 here)
    • thus, every 3 samples, we will collect only the average of the seq_no metric over these last 3 samples.

• Line 27-30: same as above but with different metrics and filters

• The syntax for collecting measurements with/without using filters is:

1) - Collect all the metrics from a given Measurement Point:
Syntax:  measure(measurementPoint, samplingWindow)

  - measurementPoint : the name of the Measurement Point, as defined by the application
  - samplingWindow   : the size of the sampling window, either in 'samples' or 'interval'
                     - 'samples => X'  : return measurements for every X samples
                     - 'interval => X' : return measurements for every X seconds

  Example: app.measure('udp_in', :interval => 3)
  which will collect every 3 sec all the metrics from the 'udp_in' Measurement Point. 

2) - Collect only some metrics and applies filters to them:
Syntax:  measure(measurementPoint, samplingWindow) do |mp|
           mp.filter(metric, type)
           ...
         end

  - type   : the type of filter to apply. Currently only 6 types are available:
             - 'avg'    : return the average over the sampling window
             - 'stddev' : return the standard deviation over the sampling window
             - 'first'  : return the 1st measurement over the sampling window
             - 'last'   : return the last measurement over the sampling window
             - 'sum'    : return the sum over the sampling window
             - 'delta'  : return the difference between the 1st and last sample over the sampling window
  - metric : the name of the metric on which to apply the filter, as defined by
             the Measurement Point (which is itself defined by the application)

  Example: 
           app.measure('udp_out', :samples => 4) do |mp|
             mp.filter('pkt_length', 'sum')
             mp.filter('seq_no', 'last')
           end
  which will collect for every 4 samples, the sum of the 'pkt_length' metric over the 4 samples, 
  and the 'seq_no' of the last sample 

• Finally... Please refer to the basic "Hello World" tutorial if you do not understand the other lines of the above ED.

5. More about Measurements and Filters:¶

• How do I find out which Measurement Points and metrics are available for an application?
  • Measurement Points and metrics are defined in the OMF Application Definition of your application
  • An example of such Application Definition is given on the "How to use applications" tutorial

• How do I add Measurement Points to my own application?
  • You have 2 options:
    • 1) add OML support (and Measurement Points) to the source code of your application
      • follow "the Quick Start with OML" tutorial:http://mytestbed.net/wiki/oml/Quick_Start_Tutorial from the OML project
    • 2) write a wrapper that takes your application's output and provides them as Measurement Points to your experiment
      • follow the "How to write an OML wrapper" tutorial

• Where can I find more information on OML, Measurement Points, and filters?
  • Please refer to the OML project documentation pages
  • To see the currently available filters: OML list of filters
  • To write your own filter: "How to develop your OML Filter" tutorial

• OML has a set of Filters which you can use: OML list of available filters
• You can also define your own Filter, as described on the Developing OML Filter page

5. Running the experiment¶

To run this experiment you should use the exact same commands and instructions as for the "Hello World" tutorial.

You should also see a similar type of output as for the "Hello World" tutorial.

6. The Results¶

Please refer to the "Hello World" tutorial to learn how to access the result database from your experiment.

A sample database from a typical run of this experiment is attached here: myDatabase

When comparing this database with the one from the "Hello World" tutorial, you may notice that:

• the otg2_udp_out table has only the 3 fields avg,_min_,_max_ for the seq_no metric (see line 13 in the above ED)
• the otg2_udp_out table has few number of entries, since we requested an interval of 4 samples
• similarly the otr2_udp_in table has only the values for the summed pkt_length metric and averaged seq_no metric (see lines 28 and 29 in the above ED).

7. What is Next?¶

Now that you know how to filters on your collected measurements, you may want to read the following basic OMF tutorials. Each one of them is introducing an OMF feature, using the simple "Hello World" experiment as a base. You do not need to follow them in the order suggested below.

• How to describe and run a simple wireless experiment - (wired version)

• How to pass parameters to your experiment, and change them at run-time

• How to configure or address all resources within a defined group, and use simple substitutions

• How to use your own or a 3rd party application with OMF

• How to use Measurement Filters to customise your Measurement

• How to use Prototypes to specify particular Applications

• How to save a disk image

• How to load a disk image

And finally, a "Conference Room" scenario which combines all of the above features:

• The Conference Room tutorial

---