• Analysing Results from the "Hello World" experiment
  • Where are the measurements ?
  • How to access your measurements ?
    • Option 1 - Using the 'Result' Service provided by an Aggregate Manager
    • Option 2 - Using SQLite3 directly
    • Option 3 - Exporting the SQL database to a Text file
  • Understanding your "Hello World" measurements
  • Where to go from here ?
  • Next...

Analysing Results from the "Hello World" experiment¶

The collected measurements can be accessed and analyzed at the end of the experiment.

As mentioned previously the simple traffic generator and sink applications that we used in the 'Hello World' experiment have some default measurement points enabled. Thus some measurements were made and collected by the OML framework while you were running the 'Hello World' experiment.

Note: For more detailed information on how measurements are collected and stored, please refer to the Collecting Measurements section of this guide. This section will also show you how to set specific measurement points within your application to collect the required experiment data via the OML framework.

Where are the measurements ?¶

For each experiment, the OML framework stores the corresponding measurements in a different SQLite database. This database is contained in a file which has the same name as your experiment ID, with the added "sq3" extension.

In the "Hello Word" example on the previous page, the ID for the executed "Hello World" experiment was: npc_2009_01_28_16_07_04. Thus the measurement database will be in a file with the name npc_2009_01_28_16_07_04.sq3. By default this file is located on the '/var/lib/oml2/' directory of machine that executes the OML Collection Server.

• If you are using one of the NICTA testbeds, the OML Collection Server is running on your testbed console. Thus, the file with your measurement database will be at '/var/lib/oml2/npc_2009_01_28_16_07_04.sq3'.

• If you are using one of the Winlab testbeds, the OML Collection Server is running on the server named 'idb1'. Thus, the file with your measurement database will be at '/var/lib/oml2/npc_2009_01_28_16_07_04.sq3' on the machine named 'idb1'.

How to access your measurements ?¶

Option 1 - Using the 'Result' Service provided by an Aggregate Manager¶

This is the default and recommended method to access your measurements.

Every basic OMF installation should have one or more Aggregate Manager(s) running, which provides a range of services to manage the testbed resources (click here for more information about AMs). One of these services is called result, and as its name implies, it provides an easy HTTP-based API to access experiment results.

To get a list of the available functions of the result services, you can use your web-browser or the following command lines on the console machine running your Experiment Controller.

• Using a web-browser, assuming your AM result service runs on the machine foo at port 5022, then point your browser to the following URL: http://foo:5022/result/

• Using command line on the console machine running your Experiment Controller:

# The "-O -" option of wget will print the received response on standard output

wget "http://foo:5022/result/" -O -

# For example on the testbeds at NICTA:

wget "http://localhost:5022/result/" -O -

# For example on the testbed SandBox 2 at Winlab:

wget "http://oml:5022/result/" -O -

You will then be presented with a XML-formatted list of functions (and their syntax) provided by the result service.

These functions are:

• dumpDatabase: Dump the complete database holding the measurement results for a given experiment

# Usage examples from the command line.
# The following command will dump the result database of the experiment 
# with the ID 'bar_12345' into the file 'myMeasures.sq3'

wget "http://foo:5022/result/dumpDatabase?expID=bar_12345" -O myMeasures.sq3

# Another example:

wget -O res.txt "http://oml:5022/result/dumpDatabase?expID=sb2_2009_05_18_02_00_10" 

• getSchema: Get the Schema of a given experiment measurement database

# Usage examples from the command line.
wget "http://foo:5022/result/getSchema?expID=bar_12345" -O mySchema.txt

• listTables: Get the list of tables in given experiment measurement database

# Usage examples from the command line.
wget "http://foo:5022/result/listTables?expID=bar_12345" -O mySchema.txt

• queryDatabase: Run a specific SQL-formatted query against the database

# Usage examples from the command line.
# Note the 2 mandatory parameters 'expID' and 'query'

wget "http://foo:5022/result/queryDatabase?expID=bar_12345&query=Your SQL Query Here" -O mySchema.txt

# Another example:

wget -O myResult.txt "http://oml:5022/result/queryDatabase?expID=sb2_2009_05_18_02_00_10&query=Select * from otg2_udp_out limit 3" 

# The resulting 'myResult.txt' file will then contain something similar to:

<DATABASE ExperimentID='sb2_2009_05_18_02_00_10'>
  <QUERY>Select * from otg2_udp_out limit 3</QUERY>
  <RESULT>
    <FIELDS>oml_sender_id oml_seq oml_ts dst_port dst_host pkt_length seq_no flow_id ts</FIELDS>
    <ROW>2 1 107.702077999711 3000 192.168.0.2 256 1 1 0.701887999661267</ROW>
    <ROW>2 2 107.951928999275 3000 192.168.0.2 256 2 1 0.951848999597132</ROW>
    <ROW>2 3 108.201885998249 3000 192.168.0.2 256 3 1 1.20184499956667</ROW>
  </RESULT>
</DATABASE>

As you can see the result service provided by the AM manager provides all the basic functions to access your experiment measurements.

Also note that all the replies from the result service are XML-formatted.

Option 2 - Using SQLite3 directly¶

Another way to access your data is by manipulating the database directly with SQLite3. This may require that you have some login rights/accounts on the machine running the OML Collection Server.

First, make a copy of your measurement database file into your home directory.

• If you are using a testbed at NICTA (more generally, if your Experiment Controller runs on the same machine as your OML Collection Server), use the following command:

cp /var/lib/oml2/npc_2009_01_28_16_07_04.sq3 ~

# More generally: 
# cp /var/lib/oml2/Your_Experiment_ID.sq3 /my/home/directory 

• If you are using a testbed at WINLAB (more generally if your EC and OML Collection Server run on a separate machines), use the following command. Important Note: depending on the testbed you are using, your user account may require some extra privileges to access the machine running the OML Collection Server.

scp idb1:/var/lib/oml2/npc_2009_01_28_16_07_04.sq3 ~

# More generally: 
# scp The_Server_Name_Or_Address:/var/lib/oml2/Your_Experiment_ID.sq3 /my/home/directory 

Assuming you have copied back your database file in your home directory as explained above, you can open your database with SQLite3 using the command:

sqlite3 npc_2009_01_28_16_07_04.sq3

SQLite version 3.5.9
Enter ".help" for instructions
sqlite>

Once inside the SQLite3 shell, you can use any SQL and SQLite queries to manipulate your database. Here are some command examples:

# To show a list of Tables:
.table

# To select the first 10 entries of the Table named 'otg2_udp_out'
select * from otg2_udp_out limit 10;

# etc...

More information on SQL and SQLite specific commands and queries are available here and here .

Option 3 - Exporting the SQL database to a Text file¶

Alternatively, if you already have your own preferred ways of viewing/slicing/processing your experiment data, you can directly export the SQL database into a plain text file.

The resulting plain text file should then plug nicely into your own processing tools (e.g. awk, ruby, python scripts, Matlab, Excel,etc...).

Assuming you have copied back your database file in your home directory as explained in 'Option 2' above, you can export it into a text file named 'data.txt' using the command:

echo '.dump' | sqlite3 npc_2009_01_28_16_07_04.sq3 > data.txt

Note: Using the above command, the resulting text file 'data.txt' will contain not only your raw data, but also all the commands that SQL needs to recreate your the database. If you intend to import that text file into another tool, you might have to strip some texts out.

Understanding your "Hello World" measurements¶

Let us assume that you used option 2 above to view your measurements directly using SQLite3.

- After opening the database, you can use the '.table' command to see the list of tables that it contains:

sqlite3 npc_2009_01_28_16_07_04.sq3

SQLite version 3.5.9
Enter ".help" for instructions
sqlite>
sqlite> .table
otg2_udp_out  otr2_udp_in 
sqlite>

Here we can see that the database contains 2 tables: 'otg2_udp_out' and 'otr2_udp_in'.

The first table contains an entry for each UDP packet generated and sent out by the traffic generator (named otg2), which was running on the 'source' node in the "Hello World" experiment.

Similarly, the second table contains an entry for each UDP packet received by the traffic receiver (named otr2), which was running on the 'sink' node in the "Hello World" experiment.

- You can now look at the description for the 'otr2_udp_in' table, using the '.schema' command:

sqlite> .schema otr2_udp_in
CREATE TABLE otr2_udp_in (oml_sender_id INTEGER, oml_seq INTEGER, oml_ts REAL, dst_port INTEGER, dst_host TEXT, pkt_length INTEGER, seq_no INTEGER, flow_id INTEGER, ts REAL);
sqlite>

Here is a an explanation of the fields there:

• oml_sender_id - OML info: the ID of the OML client that sent this measurement to the OML collection server
• oml_seq - OML info: the OML sequence number for this measurement
• oml_ts - OML info: the timestamp at which the OML collection server received this measurement
• dst_port - Packet/Application info: destination port from the packet in this measurement
• dst_host - Packet/Application info: destination host from the packet in this measurement
• pkt_length - Packet/Application info: length of the packet in this measurement
• seq_no - Packet/Application info: sequence number that was set inside the packet in this measurement
• flow_id - Packet/Application info: flow ID that was set inside the packet in this measurement
• ts - Packet/Application info: timestamp that was set inside the packet in this measurement

(In the case of 'otg2', the field 'ts' is the timestamp since the start of the application on the node)

Similarly, you can use the '.schema' command to see the description of the 'otg2_udp_out' table. The fields there are again very similar to the 'otr2_udp_in' table.

- Finally, you can dump the full content of the database on the screen and scroll through it, using the '.dump' command:

sqlite> .dump

This will display an output that looks like:

Where to go from here ?¶

• You can use your favorite processing/plotting tools (e.g. Gnuplot, Matlab, etc...), you can import tables (SQL or plain text) from the measurements and create graphs.

• In the near future, we plan to develop a set of default visualization tools and include them to our OMF portal for your convenience. These tools will parse your measurement data and plot some standard graphs (e.g. each collected metric against experiment running time) to give you an initial basic idea of your data.

• You can go on reading this guide and execute the more advanced tutorials.

• You can go and develop your own experiment to run on an OMF-enabled testbed.

Next...¶

• Next page: Beyond the Basics
• Jump to:
  - Advanced Tutorials
  - Collecting Measurements
  - FAQs

---