"Hello World" Tutorial

This simple tutorial presents all the basic steps to develop, run, and access the result of an experiment with OMF 6. Subsequent tutorials will build on this one to introduce further OMF features.

If you are a new OMF user (i.e. an experimenter), you may want to read the OMF sytem overview or the experimenter overview pages

Objectives

After reading this tutorial you should be able to:

develop a simple networking experiment using OEDL, the OMF Experiment Description Language orchestrate that experiment using one OMF-enabled resources (PC type) access the measurements collected during that experiment run

Files

The experiment description (aka script) is: tutorial00.rb

Experiment Scenario

This simple experiment involves a single resource of type PC, which has a active network interface. In this experiment, we will instruct that resource to start an instance of the 'ping-oml2' application to probe another host on the network attached to that interface (e.g. another host on the Internet, the LAN, or the resource's itself).

This 'ping-oml2' application is a wrapper around the traditional ping application. It captures the ping outputs and sends them as measurement streams to an OML2 collection point (an OML2 server in this case), which then stores them in a database available to the experimenter.

Prerequisites

Accessing/Provisioning Resources

This tutorial assumes that you are using OMF-enabled resources, which are provided by one of the OMF supported testbeds ([href://www.orbit-lab.org ORBIT] WINET, NITOS etc. testbeds). This section briefly describes the steps to reserve and provision resources on these testbeds.

You can complete this tutorial with OMF-enabled resources, which are provided by other testbeds. In such a case, please refer to these testbeds' specific documentation for instructions on how to reserve/provision their resources.

Alternatively you may also decide to install OMF on your own testbed, if so then please follow the instructions for testbed operators on our OMF 6 Installation Guide

Accessing a Resource at NICTA/ORBIT

Are you using a testbed at NICTA? Please refer to the OMF at NICTA Getting Started page Are you using a testbed at ORBIT? Please refer to the OMF at ORBIT Getting Started page Provisioning a Resource at NICTA/ORBIT ======

The current version of OMF 6 does not yet have a complete process in place to provision a PC-type resource in ORBIT. Such feature will be added in the next release. Provision in the context of PC-type resources in ORBIT means having a specific user disk image loaded on the resource.

In the meantime, please use the method described on the OMF 5.4 imaging page for instruction on how to provision/image resources. Using these instructions, make sure that you load on your resource a disk image that contains OMF 6 (normally the latest baseline.ndz image will do)

Installing the 'ping-oml2' application on your resource

When using PC-type resources on the NICTA or ORBIT testbeds, the applications 'ping-oml2' should already be pre-installed in the default disk image for your resource (usually this would be the 'baseline.ndz' image). Thus you can directly move to the next section about 'Installing the Experiment Controller'

If you are using a PC-type resource from another OMF enabled testbed:

you will need to install this 'ping-oml2' application by following the instructions on the OML Application pages for example on an resource running Ubuntu Linux, you would issue the following commands:

sudo apt-add-repository "deb http://download.opensuse.org/repositories/home:/cdwertmann:/oml/xUbuntu_12.10/ ./"
sudo apt-add-repository "deb http://download.opensuse.rg/repositories/home:/cdwertmann:/oml/xUbuntu_12.10/ ./"
curl http://download.opensuse.org/repositories/home:/cdwertmann:/oml/xUbuntu_12.10/Release.key | sudo apt-key add -
sudo apt-get update
sudo apt-get install ping-oml2

for any other platforms, please refer to the OML Application pages.

Note: OMF has a feature that allows you to install applications as part of your experiment orchestration. This feature is not presented in this simple tutorial, but it is described in details in this other tutorial

Installing the Experiment Controller

The OMF Experiment Controller (EC) is the software that will interpret your Experiment Description (ED) and interact with the resources to execute it accordingly. You can either:

use a pre-installed EC on the consoles of any NICTA or ORBIT testbeds or install your own EC on your machine, by following the instructions for users on our OMF 6 Installation Guide This tutorial assumes the latter, i.e. you have installed an EC on your machine and will use it to orchestrate your experiment

Developing the “Hello World” Experiment

To run an experiment with OMF, you first need to describe it into an Experiment Description (ED). An ED is a file/script that is supplied as an input to the Experiment Controller (EC). It contains a detailed description of the resources involved in an experiment and the sets of actions to perform in order to realize that experiment. An ED is written using the OMF Experiment Description Language (OEDL).

The ED describing this simple “Hello World” experiment is tutorial00.rb. It is composed of 3 distinct parts, described in the following listing and subsections below.

# A. Define an OMF Application Definition for the ping-oml2 application
# The OMF entities are using this definition to know where to find the
# application, what are its configurable parameters, and what are the
# OML2 measurement points that it provides.
# This ping-oml2 application will be known by OMF entities as 'ping_oml2'
#
defApplication('ping_oml2') do |app|
  app.description = 'Simple Definition for the ping-oml2 application'
  # Define the path to the binary executable for this application
  app.binary_path = '/usr/bin/ping-oml2'
  # Define the configurable parameters for this application
  # For example if target is set to foo.com and count is set to 2, then the
  # application will be started with the command line:
  # /usr/bin/ping-oml2 -a foo.com -c 2
  app.defProperty('target', 'Address to ping', '-a', {:type => :string})
  app.defProperty('count', 'Number of times to ping', '-c', {:type => :integer})
  # Define the OML2 measurement point that this application provides.
  # Here we have only one measurement point (MP) named 'ping'. Each measurement
  # sample from this MP will be composed of a 4-tuples (addr,ttl,rtt,rtt_unit)
  app.defMeasurement('ping') do |m|
    m.defMetric('dest_addr',:string)
    m.defMetric('ttl',:uint32)
    m.defMetric('rtt',:double)
    m.defMetric('rtt_unit',:string)
  end
end

# B. Define a group of resources which will run the ping-oml2 application
# Here we define only one group (Sender), which has only one resource in it
# (omf.nicta.node8)
#
defGroup('Sender', 'omf.nicta.node8') do |g|
  # Associate the application ping_oml2 defined above to each resources
  # in this group
  g.addApplication("ping_oml2") do |app|
    # Configure the parameters for the ping_oml2 application
    app.setProperty('target', 'www.nicta.com.au')
    app.setProperty('count', 3)
    # Request the ping_oml2 application to collect measurement samples
    # from the 'ping' measuremnt point (as defined above), and send them
    # to an OML2 collection point
    app.measure('ping', :samples => 1)
  end
end

# C. Define the sequence of tasks to perform when the event
# "all resources are up and all applications are install" is being triggered
#
onEvent(:ALL_UP_AND_INSTALLED) do |event|
  # Print some information message
  info "This is my first OMF experiment"
  # Start all the Applications associated to all the Groups
  allGroups.startApplications
  # Wait for 5 sec
  wait 5
  # Stop all the Applications associated to all the Groups
  allGroups.stopApplications
  # Tell the Experiment Controller to terminate the experiment now
  Experiment.done
end

Application Definition

OMF entities need to learn about the applications that will be used in the experiment, such as where their binary executable resides, what configurable parameters they have, or what measurements they can collect. All this information is provided in the block of instructions defined between the 'do' and 'end' markers following the 'defApplication' commands:

defApplication('ping_oml2') do |app|
  app.description = 'Simple Definition for the ping-oml2 application'
  ...
end

first we provided the path for the application itself (i.e. app.binary_path = '/usr/bin/ping-oml2')

app.binary_path = '/usr/bin/ping-oml2'

then we define all the configurable command line parameters of the application, that we would like to configure within OMF. This is done using the 'defProperty' command for each parameter. In this example, we are only interested in interacting with 2 parameters of the application, namely the ones referred to as '-a' and '-c' on the command, which correspond to the target host to ping and the number of pings to send, respectively.

# /usr/bin/ping-oml2 -a foo.com -c 2
app.defProperty('target', 'Address to ping', '-a', {:type => :string})
app.defProperty('count', 'Number of times to ping', '-c', {:type => :integer})

finally we define all the OML2 measurement points (MP) that this application has (if any). In this example we have only one MP named 'ping'. If that MP is activated (i.e. we want it to collect measurement), it will provide a serie of 4-tuple samples

# sample from this MP will be composed of a 4-tuples (addr,ttl,rtt,rtt_unit)
app.defMeasurement('ping') do |m|
  m.defMetric('dest_addr',:string)
  m.defMetric('ttl',:uint32)
  m.defMetric('rtt',:double)
  m.defMetric('rtt_unit',:string)
end

It is important to note that this Application Definition is only informative for OMF, i.e. it is only a description of what the real application has to offer. Indeed, the application itself must already implements the parameters and measurement points that you define in this App definition.

Group/Resource Definition

Within an OMF experiment, resources may be grouped together within named Groups. A named Group can be itself viewed as a resource holding other resources. A given resource can belong to many groups at the same time, and a group itself may be part of another group. In this example, we define a single group named 'Sender', which contains a single resource 'omf.nicta.node8'.

IMPORTANT When running this experiment using your own resource and testbed please change 'omf.nicta.node8' in the ED to the actual name of your own resource.

defGroup('Sender', 'omf.nicta.node8') do |g|
  ...
end

When we define a group, we can associate configuration settings and applications to all members of that group. In this example, we only associate a one application to the single member of the 'Sender' group. This is done using the 'addApplication' command. Furthermore, when associating an application to a group, we can provide a given configuration for that application in the specific context of that group. This is achieved inside the block of instructions following the 'addApplication' command. In this example, we

• configure the 'target' parameter to the value 'www.nicta.com.au'
• configure the 'count' parameter to the vlaue 2
• request the application to collect every measurement samples that the 'ping' measurement point will produce

g.addApplication("ping_oml2") do |app|
  app.setProperty('target', 'www.nicta.com.au')
  app.setProperty('count', 3)
  app.measure('ping', :samples => 1)
end

Event Definition

An experiment in OMF is fully event driven. This means that to perform an experiment, you as the experimenter have to define:

• sets of events that may be triggered during the course of the experiment execution
• sets of consecutive tasks to perform when each of these events are triggered

For example, your experiment might involve 2 events:

• 'when my PC node is ready' and
• 'when my application has finished running'. You would then a

You would then associate the following tasks to each of these events:

• 'configure my application on my PC node and start it'
• 'do some cleanup, send me an email, and switch off my PC node'

For your convenience, the OMF EC already defines by default a set of common events that are useful to many experiments. For example, these default defined events are:

• :ALL_UP - triggered when all resources in all the defined groups have contacted the EC and ready to participate in the experiment
• :ALL_INTERFACE_UP - triggered when all the network interfaces, which were configured within this experiment are in their 'up' active state
• :ALL_UP_AND_INSTALLED - triggered when all the resources are 'ALL_UP' and all the applications associated to them are installed and ready to be started

For these default EC-defined event, there is no need for you to redefine them in your ED. The only thing that you have to do is define the set of tasks you would like to perform when one of these events triggers. In this tutorial we define a set of tasks to perform when the :ALL_UP_AND_INSTALLED event is triggered, using the 'onEvent' command:

onEvent(:ALL_UP_AND_INSTALLED) do |event|
  ...
end

The set of consecutive tasks that we define are:

• print some information message (using the 'info' command)
• start all the applications associated with all the groups (using the 'startApplications' command on the 'allGroups' accessor)
• wait for 5 seconds
• stop all the applications associated with all the groups

info "This is my first OMF experiment"
allGroups.startApplications
wait 5
allGroups.stopApplications

As OMF experiment are fully event driven, you have to explicitly tell the OMF EC when to terminate the experiment! Otherwise, it will keep waiting for more events to happen, and of course if nothing else change in your experiment after that, you may never see the EC software stopping. To explicitly tell the EC to terminate the experiment, we use the following command which can be placed in any event-tasks definition as you design your experiment:

  Experiment.done

If you would like more information on defining your own custom events, please read our User-Defined Event Tutorial

Running the “Hello World” Experiment

How do you run it?

Assuming that you have checked all the prerequisite points in the above section 2, and that you have the EC software installed on your own computer, then to run your experiment you have to:

• save its description in a file on your computer, thus either
  • cut-and-paste the above ED listing into a new file named 'tutorial00.rb'
  • download the ED directly: tutorial00.rb
• open a terminal and navigate to the folder/directory where you saved that file
• start the EC software and tell it to execute the experiment described in your ED file, using the command line:

  omf_ec -u xmpp://usr:pwd@my_xmpp.com exec --oml_uri tcp:srv:port tutorial00.rb
  

  • replace xmpp://usr:pwd@srv with the credentials for your user on the xmpp pubsub server that is used to communicate with the resources
  • replace tcp:srv:port with the hostname/IP and port of the OML2 server which will collect the experiment's measurement

• So only for example, if you are using the username 'foo' and the password 'bar' to connect to the xmpp pubsub server 'my_xmpp.com' and if you furthermore want to use the OML2 server with hostname 'my_oml.com at port 3003 to collect the measurement of your experiment, then you would use the command:

omf_ec -u xmpp://foo:bar@my_xmpp.com exec --oml_uri tcp:my_oml.com:3003 tutorial00.rb

If you would like to know more about the other options of the OMF EC software please run the commands:

    omf_ec help
    omf_ec help exec

What will happen next?

When running the EC with the above command, you should see an output similar to this:

  INFO  XMPP::Communicator: Connecting to 'norbit.npc.nicta.com.au' ...
  INFO  Object: Connected
  INFO  Object: Start experiment: 2013-03-14T03:48:48Z
  INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a
  INFO  OmfEc: Subscribed to omf.nicta.node8
  INFO  OmfEc: Config omf.nicta.node8 to join Sender
  INFO  OmfEc: Newly discovered resource >> omf.nicta.node8
  INFO  OmfEc: Event triggered: 'ALL_UP'
  INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a_application
  INFO  OmfEc: Resource xmpp://bd9c68d5-1469-41a0-9a33-4bdba501f7b0@norbit.npc.nicta.com.au created
  INFO  OmfEc: Newly discovered resource >> bd9c68d5-1469-41a0-9a33-4bdba501f7b0
  INFO  OmfEc: Event triggered: 'ALL_UP_AND_INSTALLED'
  INFO  Object: This is my first OMF experiment
  INFO  Object: Request from Experiment Script: Wait for 10s....
  WARN  Object: Calling 'wait' or 'sleep' will block entire EC event loop. Please try 'after' or 'every'
  INFO  OmfEc: APP_EVENT STARTED from app ping_oml2_cxt_0 - msg: env -i /usr/bin/ping-oml2 -a www.nicta.com.au -c 3 --oml-config /tmp/bd9c68d5.xml
  INFO  OmfEc: APP_EVENT STDERR from app ping_oml2_cxt_0 - msg: INFO ping-oml2 2.9.0-dirty
  INFO  OmfEc: APP_EVENT STDERR from app ping_oml2_cxt_0 - msg: INFO OML4R Client V2.9.0.1 [Protocol V3] Copyright 2009-2012, NICTA
  INFO  OmfEc: Exit in up to 15 seconds...
  INFO  OmfEc: APP_EVENT STDERR from app ping_oml2_cxt_0 - msg: INFO Collection URI is tcp:norbit.npc.nicta.com.au:3003
  INFO  OmfEc: APP_EVENT STDOUT from app ping_oml2_cxt_0 - msg: 64 bytes from 221.199.217.18: icmp_req=1 ttl=62 time=0.000 ms
  INFO  OmfEc: APP_EVENT STDOUT from app ping_oml2_cxt_0 - msg: 64 bytes from 221.199.217.18: icmp_req=1 ttl=62 time=0.000 ms
  INFO  OmfEc: APP_EVENT STDOUT from app ping_oml2_cxt_0 - msg: 64 bytes from 221.199.217.18: icmp_req=1 ttl=62 time=0.000 ms
  INFO  OmfEc: APP_EVENT DONE.OK from app ping_oml2_cxt_0 - msg: status: pid 2065 exit 0
  INFO  OmfEc: Release applications and network interfaces
  INFO  OmfEc: Subscribed to bd9c68d5-1469-41a0-9a33-4bdba501f7b0
  INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a
  INFO  XMPP::Communicator: Disconnecting ...

The above screen output was optained when running the EC on the NICTA testbed, with the experiment described in tutorial00.rb and using the resource named 'omf.nicta.node8'

What does that screen output mean?

Here is a brief explanation of the output messages displayed by the EC above:

• First the EC provides us with some information about the parameters of this experiment (ID, xmpp server used, resource used,...):

  INFO  XMPP::Communicator: Connecting to 'norbit.npc.nicta.com.au' ...
  INFO  Object: Connected
  INFO  Object: Start experiment: 2013-03-14T03:48:48Z
  ...
  INFO  OmfEc: Subscribed to omf.nicta.node8
  INFO  OmfEc: Config omf.nicta.node8 to join Sender
  

• It also provides us some feedback about its communication with the xmpp server and other OMF entities:

  ...
  INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a
  INFO  OmfEc: Subscribed to omf.nicta.node8
  ...
  INFO  OmfEc: Newly discovered resource >> omf.nicta.node8
  ...
  INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a_application
  ...
  INFO  OmfEc: Newly discovered resource >> bd9c68d5-1469-41a0-9a33-4bdba501f7b0
  ...
  INFO  OmfEc: Subscribed to bd9c68d5-1469-41a0-9a33-4bdba501f7b0
  INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a
  INFO  XMPP::Communicator: Disconnecting ...
  Then it also informs us when a defined event has been triggered:
  
  ...
  INFO  OmfEc: Event triggered: 'ALL_UP'
  ...
  INFO  OmfEc: Event triggered: 'ALL_UP_AND_INSTALLED'
  ...
  

• Finally, when an event is triggered (such as ALL_UP_AND_INSTALLED), it informs us about the tasks executed for that event, and their results/outputs:

  ...
  INFO  OmfEc: Event triggered: 'ALL_UP_AND_INSTALLED'
  INFO  Object: This is my first OMF experiment
  INFO  Object: Request from Experiment Script: Wait for 10s....
  WARN  Object: Calling 'wait' or 'sleep' will block entire ...
  INFO  OmfEc: APP_EVENT STARTED from app ping_oml2_cxt_0 - ...
  INFO  OmfEc: APP_EVENT STDERR from app ping_oml2_cxt_0 - msg: INFO ping-oml2 2.9.0-dirty
  INFO  OmfEc: APP_EVENT STDERR from app ping_oml2_cxt_0 - msg: INFO OML4R Client V2.9.0.1 [Protocol V3] Copyright 2009-2012, NICTA
  INFO  OmfEc: Exit in up to 15 seconds...
  INFO  OmfEc: APP_EVENT STDERR from app ping_oml2_cxt_0 - msg: INFO Collection URI is tcp:norbit.npc.nicta.com.au:3003
  INFO  OmfEc: APP_EVENT STDOUT from app ping_oml2_cxt_0 - msg: 64 bytes from 221.199.217.18: icmp_req=1 ttl=62 time=0.000 ms
  INFO  OmfEc: APP_EVENT STDOUT from app ping_oml2_cxt_0 - msg: 64 bytes from 221.199.217.18: icmp_req=1 ttl=62 time=0.000 ms
  INFO  OmfEc: APP_EVENT STDOUT from app ping_oml2_cxt_0 - msg: 64 bytes from 221.199.217.18: icmp_req=1 ttl=62 time=0.000 ms
  INFO  OmfEc: APP_EVENT DONE.OK from app ping_oml2_cxt_0 - msg: status: pid 2065 exit 0
  ...
  

Accessing the Results from the Experiment

During the execution of the above experiment script, the ping-oml2 application has collected some measurement, as we requested it to do, and sent them to the OML2 server that we selected (the --oml-uri option of the EC command line).

How do you access the measurements?

This depends on how the OML2 server which received your measurment is set up. Indeed the collection point for your measurement (OML2 server) can be configured to use either a SQLite3 or a PostgreSQL, moreover additional tools could have been put in place by your testbed operators to faciliate the access to the resulting database.

For a detailed description of OML2 server's configuration modes, please refer to the OML2 Documentation

Here is a short example on how you would access your data if you used the NICTA testbed:

• assuming that the OML2 server was running on the host 'my_oml.com' and was configured to use SQLite3 and store the databases in '/var/lib/oml2/'
• first you need to get access to a console on that host, assuming you have an account 'foo' with the password 'bar':

  ssh foo@my_oml.com  # the enter the password 'bar'
  

• then you use the sqlite3 command to access your experiment database, which is in the file your_experiment_id.sq3. Thus assuming the experiment ID above (2013-03-14T03:48:48Z):

  sqlite3 /var/lib/oml2/2013-03-14T03:48:48Z.sq3
  

For more information on SQLite3, please refer to its documentation website

How do I display my measurements in some nice graphs?

We have a separate tool named omf_web which allows you to build some custom visualisation of the data collected within your experiment and display them within your Internet browser. For more information on how to use that tool, please refer to the omf_web documentation