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

Timestamp:

Apr 6, 2019, 12:50:06 PM (5 years ago)

Author:

seskar

Comment:

--

OMF/OMF60/0User/1Tutorials/Tutorial0

@@ +1 @@
+=== "Hello World" Tutorial ===
+
+[[TOC(heading=OMF Documentation, OMF/*, reverse, depth=1)]]
+
+[[TOC(heading=OMF 6 Documentation, OMF/OMF60/*, depth=2)]]
+
+This 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.
+
+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