This sections includes:

1. A "how to use" of Scenario Builder & Scenario Observer in order to generate your scenarios and launch them from the CLI.
2. A "how to use" the helpers: a way to simplify your scenarios
3. A "how to use" the reference scenarios: a way to include pre-defined scenarios and launch them.

For a detailed description of the helpers and the reference scenarios, we encourage to go to the scenario/helpers section

The scenario_observer.py script is particular as it is meant to be used from the command line directly. Instead it serves as a building block to create, save/modify, and run scenarios built using the scenario_builder API. It can also easily generate JSON files instead.

Follow the steps listed here to generate/launch the scenario below:

1. In order to use the API, import the Scenario class from scenario_builder and the ScenarioObserver from the auditorium-scripts.
2. Create a function that builds your scenario (build_delay_scenario()): a fping and a hping launched at the same time, that will be stopped after 20 seconds. The IP destination address should be given as an argument.
3. In the main function, you should create your ScenarioObserver, add your arguments (the names of your entities and the argument of your scenario).
4. Pass your arguments to the scenario and use the launch_and_wait() function.

delay_scenario.py

#Import the Scenario class from scenario_builder and the ScenarioObserver from the auditorium-scripts.
from scenario_builder import Scenario
from auditorium_scripts.scenario_observer import ScenarioObserver
 
#Your scenario
def build_delay_scenario(client, server, scenario_name):
    scenario = Scenario(scenario_name, 'Comparison of 2 types of RTT measurements')
    scenario.add_argument('ip_dst', 'Target of the pings and server ip adress')
 
    hping = scenario.add_function('start_job_instance')
    hping.configure('hping', client, offset=0, destination_ip='$ip_dst')
    fping = scenario.add_function('start_job_instance')
    fping.configure('fping', client, offset=0, destination_ip='$ip_dst')
    stop = scenario.add_function('stop_job_instance', wait_launched=[hping, fping], wait_delay=20)
    stop.configure(hping, fping)
    return scenario
 
def main(scenario_name='Delay metrology scenario'):
    observer = ScenarioObserver()
    observer.add_scenario_argument(
            '--client', '--client-entity', default='Client',
            help='name of the entity for the client of the RTT tests')
    observer.add_scenario_argument(
            '--server', '--server-entity', default='Server',
            help='name of the entity for the server of the owamp RTT test')
    observer.add_run_argument(
            'ip_dst', help='server ip address and target of the pings')
    args = observer.parse(default_scenario_name=scenario_name)
 
    built_delay_scenario = build_delay_scenario(args.client, args.server, scenario_name)
    observer.launch_and_wait(built_delay_scenario)
 
if __name__ == '__main__':
    main()

To generate the scenario JSON file in the current directory:

$ python3 delay_scenario.py --client your_client --server your_server build --local .

To launch the scenario on the controller, run it, and wait for its completion. See that the arguments after the “run” action are arguments given directly (via the .add_run_argument() of the Observer) to your scenario if it has mandatory arguments (in this case, the ip_dst).

$ python3 delay_scenario.py -o -p your_project --your_client client --server your_server run 192.168.19.3

All the arguments options can be detailed via the help( python3 delay_scenario.py -h ).

OpenBACH — Run a scenario and postprocess stats
 
optional arguments:
  -h, --help            show this help message and exit
  -o, --override        have the provided scenario builder (if any) replace
                        the current scenario (default: False)
 
backend:
  --controller CONTROLLER
                        address at which the contoller is listening (default:
                        172.20.34.41)
  --login LOGIN, --username LOGIN
                        username used to authenticate as (default: openbach)
  --password PASSWORD   password used to authenticate as (default: None)
 
scenario arguments:
  -n NAME, --name NAME, --scenario-name NAME
                        name of the scenario to launch (default: None)
  -p NAME, --project NAME, --project-name NAME
                        name of the project the scenario is associated with
                        (default: None)
  --client CLIENT, --client-entity CLIENT
                        name of the entity for the client of the RTT tests
                        (default: Client)
  --server SERVER, --server-entity SERVER
                        name of the entity for the server of the owamp RTT
                        test (default: Server)
  --sequential          whether or not the test should run one after the other
                        (default: False)
 
actions:
  action
    run                 run the selected scenario on the controller after
                        optionally sending it (default action)
    build               write the JSON of the selected scenario into the given
                        directory

If you chose the “run” action and ask for the help ( python3 delay_scenario.py -o -p your_project –client your_client –server your_server run -h ), you will be able to check the scenario arguments (in our case, the server IP destination)

optional arguments:
  -h, --help            show this help message and exit
 
scenario arguments:
  ip_dst                server ip address and target of the pings

If you chose the “build” action and ask for the help ( python3 delay_scenario.py -o -p your_project –client your client –server your_server build -h ), you will see how to give a path to your json and an option to post the scenario on the controller.

positional arguments:
  PATH                  path to a directory to store generated JSON files
 
optional arguments:
  -h, --help            show this help message and exit
  --local, --no-controller
                        do not try to contact the controller to fetch or
                        update information; use the provided scenario builder
                        (if any) instead.

Alternatively, in order to simplify your scripts, you can use scenario helpers (pre-defined blocks of openbach functions) inside your scenarios. The helpers need to be imported as follows:

from scenario_builder.helpers.metrics import fping_measure_rtt, hping_measure_rtt

In that case, fping_measure_rtt and hping_measure_rtt allow to launch and stop the fping and hping jobs. Following previous example, we modify the script in order to use the helpers. Moreover, in this example hping and fping are launched sequentially (one after the other)

delay_scenario_with_helpers.py

from scenario_builder import Scenario
from auditorium_scripts.scenario_observer import ScenarioObserver
from scenario_builder.helpers.traffic_and_metrics import fping_measure_rtt, hping_measure_rtt
 
def build_scenario(client, scenario_name):
    scenario = Scenario(scenario_name, 'Comparison of 2 types of RTT measurements sequentially')
    scenario.add_argument('ip_dst', 'Target of the pings and server ip adress')
 
    wait = hping_measure_rtt(scenario, client, '$ip_dst', 60)
    fping_measure_rtt(scenario, client, '$ip_dst', 60, wait)
    return scenario
 
def main(scenario_name='Delay metrology scenario'):
    observer = ScenarioObserver()
    observer.add_scenario_argument(
            '--client', '--client-entity', default='Client',
            help='name of the entity for the client of the RTT tests')
    observer.add_scenario_argument(
            '--sequential', action='store_true',
            help='whether or not the test should run one after the other')
    observer.add_run_argument(
            'ip_dst', help='server ip address and target of the pings')
    args = observer.parse(default_scenario_name=scenario_name)
 
    build = build_scenario(args.client, scenario_name)
    observer.launch_and_wait(build)
 
 
if __name__ == '__main__':
    main()

Alternatively, you can also use/launch reference scenarios. The reference scenarios (in that case: network_delay ) need to be imported as follows:

from scenario_builder.scenarios import network_delay

The reference scenarios must have a launcher in the reference_scenarios. In this case, the script generate_network_delay will allow us to run it as follows (srv_ip is the same argument than ip_dst previously used):

python3 generate_network_delay.py your_project -o --clt_entity your_client --srv_ip 192.168.19.3 --entity_pp your_entity run

or generate the json as follows:

python3 generate_network_delay.py your_project -o --clt_entity your_client --srv_ip 192.168.19.3 --entity_pp your_entity build .

You can also import reference scenarios (or some parts) and add them as subscenarios. In the same example network_delay which:

• Launches the subscenarios network_delay_simultaneous_core or network_delay_sequential_core (allowing to compare the RTT measurement of fping, hping and owamp jobs).
• Launches two postprocessing helpers (launching postprocessing jobs) to compare the time-series and the CDF of the delay measurements.

As you can see in the import modules of the scenario, we are importing the helpers and the openbach functions StartJobInstance/StartScenarioInstance to launch our reference subscenario and the postprocessing jobs.

from scenario_builder import Scenario
from scenario_builder.helpers.network.owamp import owamp_measure_owd 
from scenario_builder.helpers.network.fping import fping_measure_rtt 
from scenario_builder.helpers.network.hping import hping_measure_rtt 
from scenario_builder.helpers.postprocessing.time_series import time_series_on_same_graph 
from scenario_builder.helpers.postprocessing.histogram import cdf_on_same_graph, pdf_on_same_graph 
from scenario_builder.openbach_functions import StartJobInstance, StartScenarioInstance

Below, you can see how to use subscenarios thanks to the :

• start_scenario_instance function (scenario.add_function('start_scenario_instance')) and
• the configuration of these subscenario functions available in the same script (in our case: network_delay_simultaneous_core and network_delay_sequential_core) with their arguments (start_scenario_core.configure(scenario_core, srv_ip=srv_ip, duration=duration)).

if simultaneous:
   scenario_core = network_delay_simultaneous_core(clt_entity)
else:
   scenario_core = network_delay_sequential_core(clt_entity)
 
start_scenario_core = scenario.add_function(
        'start_scenario_instance')
 
start_scenario_core.configure(
        scenario_core,
        srv_ip=srv_ip,
        duration=duration)