OML-instrumented Applications

This project holds the set of applications which have been instrumented with OML. Whenever it is relevant, they also provide an up-to-date application definition for use with OMF (using the oml:app namespace).

These applications have some OML Measurement Points defined within their source code, which allows systematic collection and storage of measurement samples using the OML client library and the OML collection server. We currently provide the following applications:
  • collectd-write-oml2: writer plugin for collectd;
  • gpslogger-oml2: measure GPS data from gpds;
  • iperf-oml2: Iperf with OML2 measurement recording;
  • nmetrics-oml2: node metrics using libsigar;
  • otg2-oml2: the otg2/otr2 programs for generating background traffic;
  • ping-oml2: a simple OML4R wrapper around the system ping tool;
  • ripwavemon-oml2: use OML to monitor the Navini Ripwave WiMAX (kinda) modem;
  • trace-oml2: wrapper around libtrace with OML2 measurement recording;
  • wattsup-oml2: OML-instrumented monitor for WattsUp? power meters
  • wpamon-oml2: simple interface to wpa_supplicant allowing to report 802.11 connections,

These names are also the names of the distribution packages, for those which separate components (e.g., Debian).

The current version of the bundle is 2.10.0, released on 2013-06-05.

We also have some work-in-progress applications being instrumented. They usually are based on upstream sources, and are therefore handled in separate repositories, so we can maintain the OML instrumenation only.

Descriptions

Some of the applications are described here. Others, like iperf-oml2, have their own dedicated page. Smaller applications are ommited. All of them, though, implement a --help command line argument.

Collectd writer (collectd-write-oml2)

This plugin for Collectd reports all statistics that the daemon collects via OML, thereby allowing to monitor within the OML realm everything for which a collectd plugin has been written. It can be enabled by adding the following snippet to collectd's configuration file (usually /etc/collectd/collectd.conf).

<Plugin write_oml>
        # OML ID, e.g. hostname
        #NodeID         "hostname" 
        # OML domain
        #Domain         "collectd" 
        # print OML measurements to STDOUT
        #CollectURI     "file:-" 
        # send OML measurements to an OML server running on localhost port 3000
        CollectURI      "tcp:localhost:3003" 
</Plugin>

After installing the collectd-write-oml2 package, collectd has been pulled in as a dependency and is running already. To enable data collection with OML, the collectd plugin must be enabled and configured as described above and collectd must be restarted.

GPS Logger (gpslogger-oml2)

The GPS logger application makes use of the gpsd library and data structures. In addition to capturing latitude and longitude, it reads elevation, the fix type (none, 2D or 3D) and the timestamp sent from the satellite and reports these values back to an OML server. The current application definition is available an source:/gpslogger/gpslogger.rb.in. An example on how to use it in an OMF experiment can be found here.

With the -v flag, it also reports fixes on stdout as CSV. This can be handy for a quick test with gpsd's gpsfake:

$ gpsfake  /PATH/TO/GPSD/SOURCES/test/daemon/*.log &
$ gpslogger-oml2 --oml-id gps --oml-domain gps --oml-collect localhost -v

Iperf (iperf-oml2)

Details on this application can be found on its own wiki page.

System Metrics (nmetrics-oml2)

Nmetrics is a simple command line program to capture some system statistics (CPU load, memory usage, network load, process information). It makes use of the Hyperic SIGAR library, which we also provide as a package in our Debian/Ubuntu repositories.

The current application definition is available an source:/nmetrics/nmetrics.rb.in. An example experiment using it monitoring only CPU, memory and network for 20s with OMF 5.4 could look as follows. Note the reliance on the oml:app:nmetrics application definition shipped with the binary.

 1defPrototype("system_monitor") do |p| 
 2
 3  p.name = "System Monitor" 
 4  p.description = "A monitor that reports stats on the system's resource usage" 
 5
 6  p.defProperty('monitor_cpu', 'Monitor the CPU usage', true)
 7  p.defProperty('monitor_memory', 'Monitor the Memory usage', true)
 8  p.defProperty('monitor_interface', 'Monitor the interface usage', 'eth1')
 9
10  p.addApplication("oml:app:nmetrics") do |a|
11    a.bindProperty('cpu', 'monitor_cpu')
12    a.bindProperty('memory', 'monitor_memory')
13    a.bindProperty('interface', 'monitor_interface')
14    a.measure('cpu', :samples => 1)
15    a.measure('memory', :samples => 1)
16    a.measure('net_if', :samples => 1)
17  end
18end
19
20defProperty('theSender','nodeB','ID of sender node')
21defProperty('theReceiver', 'nodeE', "ID of receiver node")
22
23defGroup('Sender',property.theSender) do |node|
24    node.addPrototype 'system_monitor'
25end
26
27defGroup('Receiver',property.theReceiver) do |node|
28    node.addPrototype 'system_monitor'
29end
30
31onEvent(:ALL_UP_AND_INSTALLED) do |event|
32    info "starting" 
33    wait 5
34    allGroups.startApplications
35    info "All applications started..." 
36    wait 20
37    allGroups.stopApplications
38    info "All applications stopped." 
39    Experiment.done
40end

Packet tracer (trace-oml2)

Trace is a packet-capture tool based on libtrace. This application can report information about captured packets int terms of their Radiotap, IPv4/IPv6 and TCP/UDP encasulations, amongst others.

The current application definition is available an source:/trace/trace.rb.in. It can be used as follows.

 1defPrototype("test:proto:listener") { |p|
 2 p.name = "Listener" 
 3 p.description = "A node which listen for packets through a given interface" 
 4 # List properties of prototype
 5 p.defProperty('omlServer', 'Contact details for the oml collection server', "tcp:#{OmlApp.getServerAddr}:#{OmlApp.getServerPort}")
 6 p.defProperty('id', 'ID for this oml client', "#{Experiment.ID}")
 7 p.defProperty('expId', 'ID for this experiment', "#{Experiment.ID}")
 8 p.defProperty('radiotap', 'Radiotap metadata enable')
 9
10 p.defProperty('interface', 'Listen on this given interface')
11
12 p.addApplication("oml:app:trace") {|otl|
13   otl.bindProperty('oml-server', 'omlServer')
14   otl.bindProperty('oml-id', 'id')
15   otl.bindProperty('oml-exp-id', 'expId')
16   otl.bindProperty('interface', 'interface')
17   otl.bindProperty('radiotap', 'radiotap')
18}
19}
20
21defGroup('listener', [[1,1],[1,2]]) {|node|
22 node.prototype("listener", {
23             'radiotap' => true,
24             'interface' => "pcapint:ath0" 
25 })
26}
27
28onEvent(:ALL_UP_AND_INSTALLED) do |event|
29 wait 30
30 allGroups.exec('ifconfig ath0 down')
31 allGroups.exec('echo \'803\' > /proc/sys/net/ath0/dev_type')
32 allGroups.exec('ifconfig ath0 up')
33 wait 1
34 allGroups.startApplications
35 wait 20
36 Experiment.done
37end

OTG2/OTR2, traffic generator and sink (otg2-oml2)

The OTG application is a traffic generator. OTR is the receiving side. Their current definition is available an source:/otg2/otg2.rb.in and source:/otg2/otr2.rb.in. They can be used with OMF as follows shown in the basic OMF tutorial.

In a pinch, they can also be started from the command line as follows

$ otr2-oml2 --oml-id otr2 --oml-domain otg --oml-collect localhost &
$ otg2-oml2 --oml-id otg --oml-domain otg --oml-collect localhost -g cbr --udp:dst_host localhost

Help can be obtained on either the main applications or their components (udp, cbr, ...) with

$ otg2-oml2 --help[=udp|cbr|...]

WattsUp? power meter monitor (wattsup-oml2)

The Linux utility from WattsUp? has been instrumented with OML, and can be used as follows, assuming the meter is connected via USB to the reporting computer as /dev/ttyUSB0, and that the current user has read/write permissions to that device (otherwise, sudo can be useful).

$ wattsup-oml2 --oml-id a --oml-domain b --oml-collect localhost ttyUSB0

The current application definition is available an source:/wattsup/wattsup.rb.in.

The instrumentation history for this application is also a good example of how to instrument existing applications (particularly 89a14785, 5b5d32b2, e8d9228b for the application description and 9593b811 for the C part of thife instrumentation).

WPA monitor (wpamon-oml2)

WpaMon is a simple interface to wpa_supplicant allowing to report 802.11 connections, disconnections and neigbours via OML. The current application definition is available an source:/wpamon/wpamon.rb.in.

OML-instrumented applications available by third-parties

These applications are not part of the bundle, but are listed here for completeness.

Fraida Fund from NYU Poly maintains a set of additional applications :

Installing the Applications

Distribution Packages

As for OML, we maintain packages for major distributions, they can be installed in the same way. Each application is available as a separate package for Debian/Ubuntu, under the names listed above. There also is an oml2-apps-omfdef package for easy integration with OMF.

Getting the Code and Contributing

You can download the latest tarball from the Files page, or check out the source directly from our git repository:

git clone git://git.mytestbed.net/oml-apps.git

Alternatively, you can also browse the git repository on the OML Applications repository page
You can also contribute patches or new instrumentation!

Discussion Mailing List

If you want to discuss any problem or improvements, please add tickets in the issue tracker (if they don't already exist), or send a message to the oml-user mailing list.