Oml
How to send and store your own data in an Emulab experiment
This page introduces how to send data to a central machine with OML(Orbit Measurement Library). OML is originally developed by Winlab at Rutgers University. It is composed of OML server and OML client. In an experiment, OML clients are instanced to send measurement data to a central OML server. OML server is responsible for receiving data from OML clients and store into a database(*.sq3). After that, you can use sqlite3 to access that file, located at /local/logs/ at the machine, where OML server runs. For each experiment, there is one dedicated OML server process, receiving data from multiple OML clients in that experiment.
To help users to send data distributed at experimental machines to a central machine, Emulab chooses OML to provide such a service. We have done some efforts to encapsulate some details, to facilitate users to use OML in Emulab. You can also find more information about OML at the end of this page.
To use OML clients at experimental nodes, an OML enabled image is required. We currently provide one for Ubuntu 10.4 named UBUNTU10-OML. Instructions for enabling OML on other images are provided at the end of this page.
The steps to use OML in Emulab are as following.
1. Define a machine to run OML server in your ns files.
You need to define a machine, to run OML server. You can do that in the following two ways. (Each way is OK.)
1.1 tb-set-use-oml
tb-set-use-omlIt will add a new node, called omlserver, where OML server process will run. All the data will be sent to this server. (We assume users will not name a node as omlserver.)
1.2 tb-set-oml-server <servernode>
set myomlserver [$ns node] tb-set-oml-server $myomlserverIn order to use this command, you need to define a Node by YOURSELF.
2. Define measurement points in your ns files.
tb-set-oml-mp <mp_name> (<metric_id> <metric_type>)+
It defines a new measurement point. A measurement point is a set of data, which has the same set of properties or metrics. The first parameter defines the name for this measurement point. The following pairs define pairs of <id,type> for metrics in this measurement point. You can define metrics as many as you want.
For example:
tb-set-oml-mp udp ip_src string ip_des string port_src int port_des int
Attention: Currently, It supports three types: string, double and int. These are types supported by OML. And we think these three types are enough to use in most situations.
3. Use the functions to send data to OML server.
3.1 After the experiment is swapped in, you will find two files generated for you: MP.c and MP.h, at /proj/pid/exp/eid at ops.emulab.net.
(e.g. /proj/utahstud/exp/omlexample)
3.2 Include MP.h in your source code and call initialize_oml() before you call other OML functions. The suggested place is to call this function immediately after main().
3.3 Call functions in your source codes where you want to send data.
For example:
#include "/proj/utahstud/exp/omlexample/MP.h" ... int main(int argc, char* argv[]){ initialize_oml(); ... char* ip_src = pkt->get_src_ip(); char* ip_des = pkt->get_des_ip(); int port_src = pkt->get_src_port(); int port_des = pkt->get_des_port(); oml_udp(ip_src,ip_des, port_src, port_des); ... }
4. Compile your source code against oml library at your experiment nodes.
For example:
gcc -Wall -o test test.c /proj/utahstud/exp/oml/MP.h /proj/utahstud/exp/oml/MP.c -loml2
Attention: make sure to specify *YOUR* experiment path. Other experiments may also contain these MP.* files.
5. That's all you need to do. You will find a database file, named as exp_id.sq3 at /local/logs/ at the machine, running OML server, which contains the data your application sends.
By default, the measurement data will be transferred through Emulab control network, not experimental network in your experiments. But if you want to transfer the measurement data through a new lan in your own experiment, you can do that by setting 0 to tb-set-oml-use-control.
tb-set-oml-use-control 0
As a result, it will create a new lan in your topology. You can also set 1 to this command. It will use control network to send the measurement data. The advantage of using control network is you will have more Ethernet interface left for your experiment. The new measurement lan will consume an Ethernet interface from each experimental node.
7. Complete examples
7.1 ns file
7.1.1 use tb-set-use-oml
set ns [new Simulator] source tb_compat.tcl tb-set-use-oml tb-set-oml-use-control 1 tb-set-oml-mp udp ip_src string ip_des string port_src int port_des int tb-set-oml-mp mp2 ttl int set node1 [$ns node] tb-set-node-os $node1 UBUNTU10-OML $ns run
7.1.2 use tb-set-oml-server
set ns [new Simulator] source tb_compat.tcl set node1 [$ns node] tb-set-node-os $node1 UBUNTU10-OML set omlserver [$ns node] tb-set-oml-server $omlserver tb-set-oml-use-control 0 tb-set-oml-mp udp ip_src string ip_des string port_src int port_des int tb-set-oml-mp mp2 ttl int $ns run
7.2 Sample applications
#include "/proj/utahstud/exp/oml/MP.h"
int main(int argc, char* argv[]){
initialize_oml();
oml_udp("10.0.1.4", "10.0.2.4");
oml_mp2(4);
return 0;
}
7.3 Sample Makefile
CC=gcc test: $(CC) -o test test.c /proj/utahstud/exp/oml/MP.h /proj/utahstud/exp/oml/MP.c -loml2
8. How to create an image with OML enabled
You can refer to the link at the end of this page for official and complete introduction. So here we list the important things to do.
8.1 Install OML-depended libraries. libxml2, libsqlite3, libpopt, libpcap, libtrace, libpthread and libsigar. Go to libtrace link to get the source code and install it.
8.2 Install OML from subversion. Because OML just provides Ubuntu package, you need to install from subversion in other operating systems.
External links:
http://omf.mytestbed.net/wiki/oml/Installing_from_Subversion