History

This page and its sub-pages presents some information related to the previous OMF 5.2 release

Please visit the pages linked from the Main User Guide page for the documentation on the latest OMF version

How to use Measurement Filters to customise your Measurement¶

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 and example.

2. Goal¶

This tutorial shows you how to define and use Measurement Filters within your Experiment Description.

A Measurement Filter allows you to perform some pre-processing on a given measurement stream on the resource that originates it. The resulting pre-processed measurement are then sent to the measurement collection server.

Such pre-processing can help you dramatically reduce the volume of measurement collected from a resource, and only collect integrated metrics, such as average or standard-deviation over a specific range of samples.

3. Scenario¶

Here we are extending the simple scenario presented in the Basic "Hello World" tutorial and example.

We add a few properties to that simple experiment, similar to what we did in the "How to pass parameter" tutorial and example.

We then modify this example, to allow us to request some pre-processing of the measurement taken on a resource, directly on the resource itself, before the measurement is sent to the collection server.

4. The New "Hello World" Experiment Description¶

 1 defProperty('packetsize', 256, "Packet size (byte) from the sender node")
 2 defProperty('bitrate', 2048, "Bitrate (bit/s) from the sender node")
 3 defProperty('runtime', 30, "Time in second for the experiment is to run")
 4 
 5 defGroup('Sender', [1,2]) {|node|
 6   node.addApplication("test:app:otg2") {|app|
 7     app.setProperty('udp:local_host', '192.168.0.2')
 8     app.setProperty('udp:dst_host', '192.168.0.3')
 9     app.setProperty('udp:dst_port', 3000)
10     app.setProperty('cbr:rate', property.bitrate)
11     app.setProperty('cbr:size', property.packetsize)
12     app.measure('udp_out', :samples => 4) { |mp|
13       mp.filter('myFilterA', 'avg', :input => 'pkt_length')
14     }
15   }
16   node.net.w0.mode = "master" 
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 }
22 
23 defGroup('Receiver', [1,3]) {|node|
24   node.addApplication("test:app:otr2") {|app|
25     app.setProperty('udp:local_host', '192.168.0.3')
26     app.setProperty('udp:local_port', 3000)
27     app.measure('udp_in', :interval => 3) 
28   }
29   node.net.w0.mode = "managed" 
30   node.net.w0.type = 'g'
31   node.net.w0.channel = "6" 
32   node.net.w0.essid = "helloworld" 
33   node.net.w0.ip = "192.168.0.3" 
34 }
35 
36 whenAllInstalled() {|node|
37   wait 10
38   allGroups.startApplications
39   wait property.runtime / 2
40   property.packetsize = 512
41   wait property.runtime / 2
42   allGroups.stopApplications
43   Experiment.done
44 }

Line 1-3: we define the 3 properties for our simple experiment
- This is similar to what we did in the "How to pass parameter" tutorial and example
- The comments in these 3 lines explain the use of each properties
- Please refer to the previous "How to pass parameter" tutorial for more information on these lines

Line 12-14 and 27: this is where we define the measurements to collect and any filters to use!
- Line 27: Similar to the previous Basic "Hello World" tutorial, we request the collection of measurements coming from the "udp_in" Measurement Point (MP) at intervals of 3 sec.
- Line 12-24: Here we want the collection of measurements from the "upd_out" MP every 4 samples, however instead of having all the metrics sent to us (e.g. packet length, destination address, port, sequence number, etc...), we are only interested in one integrated metrics, which is the average packet length over a window of 4 samples.

# 1) We want to collect all the metrics/measurements from 
# the Measurement Point "udp_in", at intervals of 3 sec

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)

# 2) We want to collect only "the average packet length over a window of 4 samples" 
#

Syntax:  filter(name, type, inputs)

  - name   : the name you wish to give to this filter, this will defined the column 
             names in the resulting measurement database
  - type   : the type of filter to apply. Currently only 3 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
  - inputs : the name of the metric(s) 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) { |mp|
             mp.filter('myFilterA', 'avg', :input => 'pkt_length')
           }

Doing more with measurements:
- How do I find out which Measurement Point and metrics are available for an application?
  - Measurement Points and metrics are defined in the OMF Application Definition of your application
  - Follow the previous tutorial on using applications to learn more about Application Definition
- How do I add Measurement Points to my application?
  - Measurement Points to be collected are added to the source code of the application
  - Measurements can also be collected from a wrapper around an application for which you do not have the source code
  - Follow the Quick Start OML Tutorial from the OML project to learn how to do these
- Where can I find more information on OML, Measurement Points, and filters?
  - Please refer to the OML project documentation pages
- Can I create my own filters?
  - Yes, please refer to the OML project documentation pages to learn how to do this

Finally...
- Please refer to the Basic "Hello World" tutorial and the "How to pass parameter" tutorial if you do not understand the remaining lines of the above Experiment Description.

5. Running the experiment¶

5.1. How to run it¶

Please refer to the Basic "Hello World" tutorial and example and the Getting Started page if you do not know how to run an experiment with OMF.

Assuming you have the above Experiment Description saved in the file named "myExp.rb", you can run this experiment using the command line:

omf exec myExp.rb

4.2. What you should see on the console:¶

You should see an output similar to the following on the command line:

 1  INFO NodeHandler: init OMF Experiment Controller 5.2.408
 2  INFO NodeHandler: init Experiment ID: npc_2010_04_01_14_20_57
 3  INFO NodeHandler: Web interface available at: http://norbit.npc.nicta.com.au:4000
 4  INFO Experiment: load system:exp:stdlib
 5  INFO property.resetDelay: value = 210 (Fixnum)
 6  INFO property.resetTries: value = 1 (Fixnum)
 7  INFO Experiment: load exp.rb
 8  INFO property.packetsize: value = 256 (Fixnum)
 9  INFO property.bitrate: value = 2048 (Fixnum)
10  INFO property.runtime: value = 30 (Fixnum)
11  INFO n_1_3: Device 'net/w0' reported Not-Associated
12  INFO whenAll: *: 'apps/app/status/@value' fires
13  INFO exp: Request from Experiment Script: Wait for 10s....
14  INFO n_1_2: Device 'net/w0' reported 00:0B:6B:57:BC:1B
15  INFO n_1_3: Device 'net/w0' reported 00:0B:6B:57:BC:1B
16  INFO exp: Request from Experiment Script: Wait for 15s....
17  INFO property.packetsize: value = 512 (Fixnum)
18  INFO exp: Request from Experiment Script: Wait for 15s....
19  INFO Experiment: DONE!
20  INFO NodeHandler: Shutting down experiment, please wait...
21  INFO run: Experiment npc_2010_04_01_14_20_57 finished after 1:13

6. The Results¶

Here is an an example of what you could do with the measurement from this experiment:

First, you should retrieve a dump of your measurement database from the experiment you just ran. Please refer to the detailed steps in the Basic "Hello World" tutorial and example if you do not know how to access your experiment result.

Assuming you have your measurement database in the file "myDatabase", you can look at the schema of the SQL tables:

## Assuming you have sqlite3 installed, and a dump of your database in MyDatabase
## Look at the schema of the available tables, using the command:

sqlite3 -init myDatabase db1 ".schema" 

# which should return:

CREATE TABLE _experiment_metadata (key TEXT PRIMARY KEY, value TEXT);
CREATE TABLE _senders (name TEXT PRIMARY KEY, id INTEGER UNIQUE);
CREATE TABLE otg2_udp_out (oml_sender_id INTEGER, oml_seq INTEGER, oml_ts_client REAL, oml_ts_server REAL, myFilterA_avg REAL, myFilterA_min REAL, myFilterA_max REAL);
CREATE TABLE otr2_udp_in (oml_sender_id INTEGER, oml_seq INTEGER, oml_ts_client REAL, oml_ts_server REAL, ts_avg REAL, ts_min REAL, ts_max REAL, flow_id_avg REAL, flow_id_min REAL, flow_id_max REAL, seq_no_avg REAL, seq_no_min REAL, seq_no_max REAL, pkt_length_avg REAL, pkt_length_min REAL, pkt_length_max REAL, src_host TEXT, src_port_avg REAL, src_port_min REAL, src_port_max REAL);

Note the schema for the table "otg2_udp_out"
- this is the Measurement Point for which we used an average filter on the packet length metric over a sampling window of 4 samples
- you see that apart from the classic OML fields, we only have 3 fields related to our 'myFilterA' filter:
  - 'myFilterA_avg' : the average applied on the packet length metric over a sampling window, as we reqested
  - 'myFilterA_min' : the minimum value of the metric over the sampling window
  - 'myFilterA_max' : the maximum value of the metric over the sampling window

Note the schema for the table "otr2_udp_in"
- this is the Measurement Point for which we are collecting all the metrics (= no filter) over a sampling window of 3 seconds
- you see that we have all the fields corresponding to all the metrics defined for the "udp_in" Measurement Point

You can also have a look at the entries from the "otg2_udp_out" table, i.e. the filtered measurements on the "udp_out" Measurement Point:

## Assuming you have sqlite3 installed, and a dump of your database in MyDatabase
## List all the filtered measurements taken from the "udp_out" MP, using the command:

sqlite3 -separator " " -init myDatabase db2 "select * from otg2_udp_out;" 

# which should return:

2 1 11.1277229934931 4.983788 256.0 256.0 256.0
2 2 15.1277409940958 8.983655 256.0 256.0 256.0
2 3 19.1277249902487 12.983579 256.0 256.0 256.0
2 4 23.1277529895306 16.983556 320.0 256.0 512.0
2 5 27.1277089715004 20.983446 512.0 512.0 512.0
2 6 31.127701997757 24.983355 512.0 512.0 512.0
2 7 35.1277059912682 28.983377 512.0 512.0 512.0

These entries follow the schema of the "otg2_udp_out" table mentioned above
- on the 5th column are the filtered average over the sampling windows (i.e. field "myFilterA_avg")
- we can notice on the 4th rows the value 320.0 for the average packet length over the sampling window
- this indicates that within the sampling window, the packet length changed, as expected since we doubled its value around that time (see the experiment description above)

7. What is Next?¶

Now that you have learned how to use collect measurements and use filters on them:

- either go back to refer to the Basic "Hello World" tutorial and example

- or continue reading the following basic OMF tutorials. Each one of them is introducing a new basic OMF feature, incrementally building on the simple "Hello World" example. You do not need to follow them in the order suggested below.