Changes between Initial Version and Version 1 of OMF/OMF60/0User/1Tutorials/Tutorial0


Ignore:
Timestamp:
Apr 6, 2019, 12:50:06 PM (20 months ago)
Author:
seskar
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • OMF/OMF60/0User/1Tutorials/Tutorial0

    v1 v1  
     1=== "Hello World" Tutorial ===
     2
     3[[TOC(heading=OMF Documentation, OMF/*, reverse, depth=1)]]
     4
     5[[TOC(heading=OMF 6 Documentation, OMF/OMF60/*, depth=2)]]
     6
     7This simple tutorial presents all the basic steps to develop, run, and access the result of an experiment with [wiki:/OMF/OMF60 OMF 6]. Subsequent tutorials will build on this one to introduce further OMF features.
     8
     9If you are a new OMF user (i.e. an experimenter), you may want to read the OMF sytem overview or the experimenter overview pages
     10
     11===== Objectives =====
     12
     13After reading this tutorial you should be able to:
     14
     15develop a simple networking experiment using OEDL, the OMF Experiment Description Language
     16orchestrate that experiment using one OMF-enabled resources (PC type)
     17access the measurements collected during that experiment run
     18
     19===== Files =====
     20
     21The experiment description (aka script) is: tutorial00.rb
     22
     23===== Experiment Scenario =====
     24
     25This 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).
     26
     27This '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.
     28
     29==== Prerequisites ====
     30
     31===== !Accessing/Provisioning Resources =====
     32
     33This 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.
     34
     35You 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.
     36
     37Alternatively 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
     38
     39====== Accessing a Resource at NICTA/ORBIT ======
     40
     41Are you using a testbed at NICTA? Please refer to the OMF at NICTA Getting Started page
     42Are you using a testbed at ORBIT? Please refer to the OMF at ORBIT Getting Started page
     43Provisioning a Resource at NICTA/ORBIT ======
     44
     45The 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.
     46
     47In 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)
     48
     49====== Installing the 'ping-oml2' application on your resource ======
     50
     51When 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'
     52
     53If you are using a PC-type resource from another OMF enabled testbed:
     54
     55you will need to install this 'ping-oml2' application by following the instructions on the OML Application pages
     56for example on an resource running Ubuntu Linux, you would issue the following commands:
     57{{{
     58sudo apt-add-repository "deb http://download.opensuse.org/repositories/home:/cdwertmann:/oml/xUbuntu_12.10/ ./"
     59sudo apt-add-repository "deb http://download.opensuse.rg/repositories/home:/cdwertmann:/oml/xUbuntu_12.10/ ./"
     60curl http://download.opensuse.org/repositories/home:/cdwertmann:/oml/xUbuntu_12.10/Release.key | sudo apt-key add -
     61sudo apt-get update
     62sudo apt-get install ping-oml2
     63}}}
     64for any other platforms, please refer to the OML Application pages.
     65
     66Note: 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
     67
     68====== Installing the Experiment Controller ======
     69The 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:
     70
     71use a pre-installed EC on the consoles of any NICTA or ORBIT testbeds
     72or install your own EC on your machine, by following the instructions for users on our OMF 6 Installation Guide
     73This tutorial assumes the latter, i.e. you have installed an EC on your machine and will use it to orchestrate your experiment
     74
     75==== Developing the “Hello World” Experiment ====
     76To 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).
     77
     78The 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.
     79
     80{{{
     81# A. Define an OMF Application Definition for the ping-oml2 application
     82# The OMF entities are using this definition to know where to find the
     83# application, what are its configurable parameters, and what are the
     84# OML2 measurement points that it provides.
     85# This ping-oml2 application will be known by OMF entities as 'ping_oml2'
     86#
     87defApplication('ping_oml2') do |app|
     88  app.description = 'Simple Definition for the ping-oml2 application'
     89  # Define the path to the binary executable for this application
     90  app.binary_path = '/usr/bin/ping-oml2'
     91  # Define the configurable parameters for this application
     92  # For example if target is set to foo.com and count is set to 2, then the
     93  # application will be started with the command line:
     94  # /usr/bin/ping-oml2 -a foo.com -c 2
     95  app.defProperty('target', 'Address to ping', '-a', {:type => :string})
     96  app.defProperty('count', 'Number of times to ping', '-c', {:type => :integer})
     97  # Define the OML2 measurement point that this application provides.
     98  # Here we have only one measurement point (MP) named 'ping'. Each measurement
     99  # sample from this MP will be composed of a 4-tuples (addr,ttl,rtt,rtt_unit)
     100  app.defMeasurement('ping') do |m|
     101    m.defMetric('dest_addr',:string)
     102    m.defMetric('ttl',:uint32)
     103    m.defMetric('rtt',:double)
     104    m.defMetric('rtt_unit',:string)
     105  end
     106end
     107
     108# B. Define a group of resources which will run the ping-oml2 application
     109# Here we define only one group (Sender), which has only one resource in it
     110# (omf.nicta.node8)
     111#
     112defGroup('Sender', 'omf.nicta.node8') do |g|
     113  # Associate the application ping_oml2 defined above to each resources
     114  # in this group
     115  g.addApplication("ping_oml2") do |app|
     116    # Configure the parameters for the ping_oml2 application
     117    app.setProperty('target', 'www.nicta.com.au')
     118    app.setProperty('count', 3)
     119    # Request the ping_oml2 application to collect measurement samples
     120    # from the 'ping' measuremnt point (as defined above), and send them
     121    # to an OML2 collection point
     122    app.measure('ping', :samples => 1)
     123  end
     124end
     125
     126# C. Define the sequence of tasks to perform when the event
     127# "all resources are up and all applications are install" is being triggered
     128#
     129onEvent(:ALL_UP_AND_INSTALLED) do |event|
     130  # Print some information message
     131  info "This is my first OMF experiment"
     132  # Start all the Applications associated to all the Groups
     133  allGroups.startApplications
     134  # Wait for 5 sec
     135  wait 5
     136  # Stop all the Applications associated to all the Groups
     137  allGroups.stopApplications
     138  # Tell the Experiment Controller to terminate the experiment now
     139  Experiment.done
     140end
     141}}}
     142
     143===== Application Definition =====
     144OMF 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:
     145{{{
     146defApplication('ping_oml2') do |app|
     147  app.description = 'Simple Definition for the ping-oml2 application'
     148  ...
     149end
     150}}}
     151first we provided the path for the application itself (i.e. app.binary_path = '/usr/bin/ping-oml2')
     152{{{
     153app.binary_path = '/usr/bin/ping-oml2'
     154}}}
     155then 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.
     156{{{
     157# /usr/bin/ping-oml2 -a foo.com -c 2
     158app.defProperty('target', 'Address to ping', '-a', {:type => :string})
     159app.defProperty('count', 'Number of times to ping', '-c', {:type => :integer})
     160}}}
     161finally 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
     162{{{
     163# sample from this MP will be composed of a 4-tuples (addr,ttl,rtt,rtt_unit)
     164app.defMeasurement('ping') do |m|
     165  m.defMetric('dest_addr',:string)
     166  m.defMetric('ttl',:uint32)
     167  m.defMetric('rtt',:double)
     168  m.defMetric('rtt_unit',:string)
     169end
     170}}}
     171It 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.
     172
     173===== Group/Resource Definition =====
     174Within 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'.
     175
     176IMPORTANT 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.
     177{{{
     178defGroup('Sender', 'omf.nicta.node8') do |g|
     179  ...
     180end
     181}}}
     182When 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
     183
     184* configure the 'target' parameter to the value 'www.nicta.com.au'
     185* configure the 'count' parameter to the vlaue 2
     186* request the application to collect every measurement samples that the 'ping' measurement point will produce
     187
     188{{{
     189g.addApplication("ping_oml2") do |app|
     190  app.setProperty('target', 'www.nicta.com.au')
     191  app.setProperty('count', 3)
     192  app.measure('ping', :samples => 1)
     193end
     194}}}
     195
     196===== Event Definition =====
     197
     198An experiment in OMF is fully event driven. This means that to perform an experiment, you as the experimenter have to define:
     199
     200* sets of events that may be triggered during the course of the experiment execution
     201* sets of consecutive tasks to perform when each of these events are triggered
     202
     203For example, your experiment might involve 2 events:
     204
     205* 'when my PC node is ready' and
     206* 'when my application has finished running'. You would then a
     207You would then associate the following tasks to each of these events:
     208
     209* 'configure my application on my PC node and start it'
     210* 'do some cleanup, send me an email, and switch off my PC node'
     211
     212For 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:
     213
     214* :ALL_UP - triggered when all resources in all the defined groups have contacted the EC and ready to participate in the experiment
     215* :ALL_INTERFACE_UP - triggered when all the network interfaces, which were configured within this experiment are in their 'up' active state
     216* :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
     217
     218For 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:
     219
     220{{{
     221onEvent(:ALL_UP_AND_INSTALLED) do |event|
     222  ...
     223end
     224}}}
     225
     226The set of consecutive tasks that we define are:
     227
     228* print some information message (using the 'info' command)
     229* start all the applications associated with all the groups (using the 'startApplications' command on the 'allGroups' accessor)
     230* wait for 5 seconds
     231* stop all the applications associated with all the groups
     232
     233{{{
     234info "This is my first OMF experiment"
     235allGroups.startApplications
     236wait 5
     237allGroups.stopApplications
     238}}}
     239
     240As 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:
     241{{{
     242  Experiment.done
     243}}}
     244
     245If you would like more information on defining your own custom events, please read our User-Defined Event Tutorial
     246
     247==== Running the “Hello World” Experiment ====
     248===== How do you run it? =====
     249Assuming 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:
     250
     251* save its description in a file on your computer, thus either
     252 * cut-and-paste the above ED listing into a new file named 'tutorial00.rb'
     253 * download the ED directly: tutorial00.rb
     254* open a terminal and navigate to the folder/directory where you saved that file
     255* start the EC software and tell it to execute the experiment described in your ED file, using the command line:
     256{{{
     257omf_ec -u xmpp://usr:pwd@my_xmpp.com exec --oml_uri tcp:srv:port tutorial00.rb
     258}}}
     259 * replace xmpp://usr:pwd@srv with the credentials for your user on the xmpp pubsub server that is used to communicate with the resources
     260 * replace tcp:srv:port with the hostname/IP and port of the OML2 server which will collect the experiment's measurement
     261
     262* 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:
     263
     264{{{
     265omf_ec -u xmpp://foo:bar@my_xmpp.com exec --oml_uri tcp:my_oml.com:3003 tutorial00.rb
     266}}}
     267
     268If you would like to know more about the other options of the OMF EC software please run the commands:
     269
     270{{{
     271    omf_ec help
     272    omf_ec help exec
     273}}}
     274
     275===== What will happen next? =====
     276
     277When running the EC with the above command, you should see an output similar to this:
     278{{{
     279  INFO  XMPP::Communicator: Connecting to 'norbit.npc.nicta.com.au' ...
     280  INFO  Object: Connected
     281  INFO  Object: Start experiment: 2013-03-14T03:48:48Z
     282  INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a
     283  INFO  OmfEc: Subscribed to omf.nicta.node8
     284  INFO  OmfEc: Config omf.nicta.node8 to join Sender
     285  INFO  OmfEc: Newly discovered resource >> omf.nicta.node8
     286  INFO  OmfEc: Event triggered: 'ALL_UP'
     287  INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a_application
     288  INFO  OmfEc: Resource xmpp://bd9c68d5-1469-41a0-9a33-4bdba501f7b0@norbit.npc.nicta.com.au created
     289  INFO  OmfEc: Newly discovered resource >> bd9c68d5-1469-41a0-9a33-4bdba501f7b0
     290  INFO  OmfEc: Event triggered: 'ALL_UP_AND_INSTALLED'
     291  INFO  Object: This is my first OMF experiment
     292  INFO  Object: Request from Experiment Script: Wait for 10s....
     293  WARN  Object: Calling 'wait' or 'sleep' will block entire EC event loop. Please try 'after' or 'every'
     294  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
     295  INFO  OmfEc: APP_EVENT STDERR from app ping_oml2_cxt_0 - msg: INFO ping-oml2 2.9.0-dirty
     296  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
     297  INFO  OmfEc: Exit in up to 15 seconds...
     298  INFO  OmfEc: APP_EVENT STDERR from app ping_oml2_cxt_0 - msg: INFO Collection URI is tcp:norbit.npc.nicta.com.au:3003
     299  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
     300  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
     301  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
     302  INFO  OmfEc: APP_EVENT DONE.OK from app ping_oml2_cxt_0 - msg: status: pid 2065 exit 0
     303  INFO  OmfEc: Release applications and network interfaces
     304  INFO  OmfEc: Subscribed to bd9c68d5-1469-41a0-9a33-4bdba501f7b0
     305  INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a
     306  INFO  XMPP::Communicator: Disconnecting ...
     307}}}
     308
     309The 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'
     310
     311===== What does that screen output mean? =====
     312Here is a brief explanation of the output messages displayed by the EC above:
     313
     314* First the EC provides us with some information about the parameters of this experiment (ID, xmpp server used, resource used,...):
     315{{{
     316INFO  XMPP::Communicator: Connecting to 'norbit.npc.nicta.com.au' ...
     317INFO  Object: Connected
     318INFO  Object: Start experiment: 2013-03-14T03:48:48Z
     319...
     320INFO  OmfEc: Subscribed to omf.nicta.node8
     321INFO  OmfEc: Config omf.nicta.node8 to join Sender
     322}}}
     323* It also provides us some feedback about its communication with the xmpp server and other OMF entities:
     324{{{
     325...
     326INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a
     327INFO  OmfEc: Subscribed to omf.nicta.node8
     328...
     329INFO  OmfEc: Newly discovered resource >> omf.nicta.node8
     330...
     331INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a_application
     332...
     333INFO  OmfEc: Newly discovered resource >> bd9c68d5-1469-41a0-9a33-4bdba501f7b0
     334...
     335INFO  OmfEc: Subscribed to bd9c68d5-1469-41a0-9a33-4bdba501f7b0
     336INFO  OmfEc: Subscribed to 856de74b-6cf7-4de7-aaad-6c842eea209a
     337INFO  XMPP::Communicator: Disconnecting ...
     338Then it also informs us when a defined event has been triggered:
     339
     340...
     341INFO  OmfEc: Event triggered: 'ALL_UP'
     342...
     343INFO  OmfEc: Event triggered: 'ALL_UP_AND_INSTALLED'
     344...
     345}}}
     346* 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:
     347{{{
     348...
     349INFO  OmfEc: Event triggered: 'ALL_UP_AND_INSTALLED'
     350INFO  Object: This is my first OMF experiment
     351INFO  Object: Request from Experiment Script: Wait for 10s....
     352WARN  Object: Calling 'wait' or 'sleep' will block entire ...
     353INFO  OmfEc: APP_EVENT STARTED from app ping_oml2_cxt_0 - ...
     354INFO  OmfEc: APP_EVENT STDERR from app ping_oml2_cxt_0 - msg: INFO ping-oml2 2.9.0-dirty
     355INFO  OmfEc: APP_EVENT STDERR from app ping_oml2_cxt_0 - msg: INFO OML4R Client V2.9.0.1 [Protocol V3] Copyright 2009-2012, NICTA
     356INFO  OmfEc: Exit in up to 15 seconds...
     357INFO  OmfEc: APP_EVENT STDERR from app ping_oml2_cxt_0 - msg: INFO Collection URI is tcp:norbit.npc.nicta.com.au:3003
     358INFO  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
     359INFO  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
     360INFO  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
     361INFO  OmfEc: APP_EVENT DONE.OK from app ping_oml2_cxt_0 - msg: status: pid 2065 exit 0
     362...
     363}}}
     364
     365==== Accessing the Results from the Experiment ====
     366During 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).
     367
     368===== How do you access the measurements? =====
     369This 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.
     370
     371For a detailed description of OML2 server's configuration modes, please refer to the OML2 Documentation
     372
     373Here is a short example on how you would access your data if you used the NICTA testbed:
     374
     375* 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/'
     376* first you need to get access to a console on that host, assuming you have an account 'foo' with the password 'bar':
     377{{{
     378ssh foo@my_oml.com  # the enter the password 'bar'
     379}}}
     380* 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):
     381{{{
     382sqlite3 /var/lib/oml2/2013-03-14T03:48:48Z.sq3
     383}}}
     384
     385For more information on SQLite3, please refer to its documentation website
     386
     387===== How do I display my measurements in some nice graphs? =====
     388We 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