This page aims to be a manual to help developing in OpenBACH API.
For a detailed description of the helpers and the reference scenarios, we encourage you to read the introduction to OpenBACH-extra and OpenBACH API.
In order to keep a clean API, and ease first-time users understanding, here is some conventions proposed for developing reference scenarios.
If you want to have your scenarios included in OpenBACH, please follow them.
Following some of the principles in the Zen of Python, here are a few simple rules to keep in mind:
"""Module Docstring. Describe the steps an phylosophy of your scenario. """ imports # Constants SCENARIO_DESCRIPTION = """Description of what the scenario accomplishes - step by step - walkthrough - if need be """ SCENARIO_NAME = 'default_name_for_scenario' # Other constants # Custom types needed as parameters # utility functions def _utility_function(…): … # "main" scenario functions def scenario_component(…, scenario_name=SCENARIO_NAME): … return scenario def alternate_scenario_component(…, scenario_name=SCENARIO_NAME): … return scenario # exposed "whole" scenario def build(…, post_processing_entity=None, scenario_name=SCENARIO_NAME): scenario = … if post_processing_entity is not None: … return scenario
The layout used should be the usual Python layout made of, in this order, module docstring, imports, constant declarations, classes (mostly namedtuples and custom argument types), and functions.
SCENARIO_NAME
and SCENARIO_DESCRIPTION
at the top;scenario_name=SCENARIO_NAME
parameter at the end;scenario_builder.Scenario
), it must be wrapped in its own function: this ease reusability and parameters discovery through the function signature.Scenario.add_constant
instead of Scenario.add_argument
. The latter making it harder to know, for an unsuspecting user, what values are expected when using the scenario as a sub-scenario.build
function should be considered the “official” finished scenario of the file: it uses other functions to create a complete scenario and optionally add post-processing capabilities. Usage may look like import scenario_module_file; scenario_module_file.build(…)
.build
function is encouraged to define a scenario_name=SCENARIO_NAME
parameter that will be forwarded to other scenario functions called. Beware, though, that naming two scenario with the same name will have the latter one override the former one in the OpenBach database.build
function is encouraged to use scenarios constructed by the other functions and add behaviour (such as post-processing) to those scenarios directly; restrict the use of sub-scenario to the minimum (to ease scheduling, for instance).
File names and default scenario names (the SCENARIO_NAME
constant) share the following four options:
Protocol_Layer
_type_of action
: e.g. network_configuration_link
Protocol_Layer
_traffic type
: e.g. service_video_dash
Protocol_Layer
_main statistic evaluated
: e.g. network_delay
(if you want to highlight a measurement or performance evaluations (e.g. delay, jitter, rate, etc.)Protocol_Layer
_traffic type
_main statistic evaluated
Protocol_Layer is one of: service, transport, network, access or physical.
Naming:
client_entity
, server_entity
;client_ip
, server_port
;Order of arguments:
build
function);There are three ways to help the user to create and launch scenarios:
Some useful information on helpers and scenarios:
How to combine them?
This manual contains guides on how to develop and use the helpers, the reference scenarios, and the executors as you work toward expanding OpenBACH capabilities.
Examples of scripts using the scenario builder are available in the section Reference Scenarios and its subsections.