= !OnTime Control User Manual =
'''Prasad Calyam, Kunpeng Zhu'''[[BR]]
'''Jan 18, 2011'''

''Software License:'' [http://www.geni.net/wp-content/uploads/2009/02/geniprojlic.pdf ''GENI Project License (GPL)'']

== 1. Overview ==
!OnTime Control is a command-line interface client for users to login, manage slice information and control Node/Root Beacons within their slices in an ''automated manner''[[BR]]

NOTE: Typically, users need to install !OnTime Control software on their desktops along with other experiment workflow tools such as GUSH; !OnTime Control provides a way to control the measurement service in an automated manner versus using the !OnTimeMeasure web-portal to control the measurement service in an ''interactive manner''. 

Features implemented include:
 * Manage measurement tasks
 * Start/Stop measurement service
 * Check measurement service status
 * Query measurement results
 * Query measurement archive

== 2. Requirements ==

A. ProtoGENI/PlanetLab slice with !OnTimeMeasure software installed and running.

B. Python 2.5.X or 2.6.X (NOTE: Current version is not compatible with Python 2.7 or 3.0)

'''Note''': [http://www.activestate.com/activepython/downloads ActivePython] is recommended for Windows users.

== 3. Installation and Configuration ==

Download the tarball from http://ontime.oar.net/download/OnTimeControl_latest.php, extract the files to any folder.

Copy the config_example.yaml as config.yaml and edit it with any text editor.

Follow instructions within the file to configure the !OnTime Control software. It is strongly suggested to use the "direct" connection mode. The "portal" mode should only be used when the !OnTime Control cannot connect to the Root Beacon directly.

== 4. Usage ==

=== 4.1 Check measurement service status ===

Run command "service_status.py" to verify whether the !OnTime Control has been installed successfully, and to verify if all the components of the measurement service are functioning correctly.

Example:

[[Image(service_status.PNG)]]

=== 4.2 Manage measurement tasks ===

"task_manage.py" manages the measurement tasks, which are configured in a YAML file. An example "measurement.yaml" is included in the package with contents:

{{{
# Measurement task settings
# Hint: A space is required after ':'

##################################################
# Supported patters:
# - Periodic
# - RandomPoisson
# - RandomExponential
# - RandomGaussian
# - StratifiedRandom
# - Adaptive
##################################################
pattern: Periodic

##################################################
# Measurement links
# Please use node names as source and destination
# Supported metrics:
# - RoundtripDelay
# - Throughput
# - Loss
# - Jitter
# - RouteChanges
##################################################
links:
- source: WASH
  destination: SALT
  metric: [Throughput, RoundtripDelay, Jitter, RouteChanges]

- source: SALT
  destination: WASH
  metric: [Jitter, RoundtripDelay, Throughput, RouteChanges]
}}}

Create your own measurement configuration file by following the example and comments in the file. Then run the "task_manage.py" with parameter "-c <measurement_config_file.yaml>".

An example:

[[Image(task_manage.PNG)]]

=== 4.3  Measurement service control ===

"service_control.py" controls the measurement service. Supported parameters are "start", "stop", "restart".

[[Image(service_control.PNG)]]

=== 4.4 Query measurement results ===

"query.py" queries the measurement results. Parameters for the query are:

  {{{
-f from time "YYYY-MM-DD HH:MM:SS" in UTC
-t to time "YYYY-MM-DD HH:MM:SS" in UTC
-s source node name
-d destination node name
-m metric {RountTripDelay|Throughput|Loss|Jitter}
-r result type {RawFiles|TimeSeries|TimeSeriesPlusAnomalies|TimeSeriesPlusForecasts}
}}}

Measurement results are automatically downloaded into the local folder.

An example query:
{{{
python query.py -f "2010-09-15 11:00:00" -t "2010-09-30 12:00:00" -s node1 -d node2 -m RoundTripDelay -r TimeSeries
}}}

[[Image(query.PNG)]]

=== 5. Query measurement archive ===

"request_measurement_archive.py" queries the measurement archive in the Root Beacon and automatically downloads the archive into a local folder.

[[Image(dump_measurement_db.PNG)]]