OML FAQ

Demystifying the addMeasurement method

addMeasurement in Application definition : Application definition is created by the application developer. The application developer chooses what measurements(metrics) will be generated by the application, how they will be grouped and what name to give to the measurement group. An experimenter has no control over this. This is the "WHAT" of measurement collection since the application writer decides what measurements (metrics) will be generated by the application.

In the example for OTG application definition found here:

a.addMeasurement("senderport", nil, [
     ['pkt_seqno', 'long'],
     ['pkt_size', 'long'],
     ['gen_timestamp', Float],
     ['tx_timestamp', 'long']
 ])

There is a measurement group called "senderport" which is defined by the application developer. This group has 4 metrics that are being measured, namely: pkt_seqno, pkt_size, gen_timestamp and tx_timestamp. Again these metrics and their datatypes are decided by the application developer.

addMeasurement in Prototype definition : As an experimenter you read what metrics are available to you in a particular application. The application definition has the comprehensive list of measurement groups and the metrics listed within each group. The experimenter controls which metrics to use in the experiment and how to process them or filter them, via a prototype. He or she can use one of the predefined prototypes or create their own. Think of the prototypes as the "Avatars" that you define to control the "HOW" of measurement collection i.e. HOW often the measurements will be aggregated and which of them you are interested in and how you want to filter them.

So if you look at a sample prototype like sender.rb which uses the otg application here:

 otg = p.addApplication(:otg, "test:app:otg")

Here you add the application otg to your prototype.

otg.addMeasurement('senderport',  Filter::TIME, 
  {Filter::SAMPLE_SIZE => 1},
  [  
    ['pkt_seqno'],
    ['pkt_size', Filter::SUM],
    ['gen_timestamp'],
    ['tx_timestamp']
  ]

Here you are specifying that your prototype will use the the "senderport" measurement group and that you want TIME based aggregation every one second and want to apply SUM filter to the pkt_size metric. You can only specify a measurement group or metric that is part of the application definition that you are using. You can't make up your own.
Example application and prototype definitions as well as experiment scripts can be found here :

How do I configure OML measurement collection via nodehandler?

OML supports TIME or SAMPLE based measurement collection. Depending on the method used, either every X seconds or every Y samples, one can apply data filters to the measurements. There are two default filters included with the oml client: 'sum' and 'mean'. OML has the ability to apply user-defined filters to the collected data. (Details on how to do that will be posted soon). The collection and filtering of application generated data is defined in the prototypes used in your experiment. Let's look at 2 example prototype definitions to see how this works :

Example I:

1. otg.addMeasurement('senderport',  Filter::TIME,
2.   {Filter::SAMPLE_SIZE => 1},
3.   [
4.    ['pkt_seqno'],
5.    ['pkt_size', Filter::SUM]
6.  ]
7. )

The "Filter" you see here is a nodehandler reference to the OML measurement collection and filtering mechanism. This definition is processed by the nodehandler and based on that it creates an xml file which acts as input to the oml client at runtime.

• On line 1, we are defining a Time-based filtering scheme on the data being generated by the application. (in this case otg)
• Line 2 sets the trigger for this collection in seconds. So 0.5 would indicate 0.5 seconds and so on. In the above example the oml client will collect measurements coming from the application and will process them every 1 seconds.
• On line 5 we instruct the oml client through nodehandler to apply the SUM filter on the "pkt_size" data.

To summarize, every one second the oml-client would send the following filtered values to the collection server :

• The first seq_no collected in this time period (since no summarizing filter was applied only the first value is sent)
• The sum of all pkt_size metrics collected during this timer period.

Example II :

1. otg.addMeasurement('senderport',  Filter::SAMPLE,
2.   {Filter::SAMPLE_SIZE => 20},
3.   [
4.    ['pkt_seqno'],
5.    ['pkt_size', Filter::MEAN]
6.  ]
7. )

In example II, the trigger for applying the filtering is 20 samples collected from the application. So every 20 samples later a summary will be sent to collection server with pkt_seqno and mean of the 20 pkt_sizes collected.

Take a look at some example prototype definitions here :