04 Platform Interaction - Smart-Edge-Lab/SeQaM GitHub Wiki

The SeQaM Platform offers multiple methods for users to interact with its functionalities. These methods enable the execution of commands and the management of experiments.

1. Console Interaction

The primary method of interacting with SeQaM is through the console, accessible via the web interface. Users can connect to the platform by accessing the console on port :8000 where the central components are deployed.

2. Experiment Configuration

An experiment is a set of commands triggered at a certain point in time. Experiments are defined within the ExperimentConfig.json file, which describes a series of commands as part of the experiment. Once configured, the experiment can be executed through the experiment dispatcher as a console command.

start_module module:experiment_dispatcher

For more detailed information on configuring experiments, please read more on Configuration files here.

3. Events on Demand at Runtime

Additionally, users can utilize the on-demand events feature for interacting with the platform. If you need to create SeQaM events based on some custom events your algorithm generates (eg. triggering a CPU load when an application has just migrated to a new server), you will need to send an on-demand POST request to the command translator module with the command you would like to execute.

curl -X POST http://Central_IP_Address:8001/translate \
     -H "Content-Type: text/plain" \
     --data "cpu_load src_device_type:ue src_device_name:ue003 cores:0 load:90 time:60s"

In this way, you can implement your logic to determine what command to execute in SeQaM and when.

Commands

A command represents an action to perform in any of the SeQaM components (central, distributed, network). The commands can be triggered from the console or automatically invoked by the experiment dispatcher module.

Structure and Syntax

The general syntax of a command is

action arg1-name:arg1-value arg2-name:arg2-value ... argN-name:argN-value

where any or all argN-value can be optionally quoted with single or double quotes; these optional quotes become mandatory if a value contains a whitespace.

List of Commands

1. CPU load

Generates CPU load in a desired device like user equipment or server.

Action: cpu_load

cpu_load time:duration load:load-value src_device_type:src_device_type src_device_name:src_device_name 
cores:number-of-cores comment:"any optional human-readable comment" mode:stress-mode random_seed:random-seed 
load_min:load-min load_max:load-max load_step:load-step time_step:time-step

Argument	Description
time:	Duration of the stress test. Must be suffixed with a time unit (s for seconds, m for minutes, h for hours).
load:	Stress level percentage as integer. Range [0-100]
src_device_type:	Type of the device to be stressed. Options include: ue, server
src_device_name:	Name of the device to be stressed. Defined in ScenarioConfig.json
cores:	Number of CPU cores to be used in the stress test. If the value is 0, all cores will be utilized.

Optional Arguments

Argument	Description
comment:	A description or comment about the experiment action.
mode:	Stress mode type. Options include: stat (static, default), rand (random), inc (increasing), or dec (decreasing).
random_seed:	Integer used in rand mode to reproduce the same random load in subsequent experiments.
load_min:	Integer representing the minimum load value (defaults to 0). Used in inc and rand modes. dec mode will reduce load until this value is reached.
load_max:	Integer representing the maximum load value (defaults to 100). Used in dec and rand modes. inc mode will increase load until this value is reached.
load_step:	Integer (defaults to 1) representing the step value added in inc mode or subtracted in dec mode per iteration.
time_step:	Integer (defaults to 1) representing the duration of each iteration. Uses the same time unit as the time argument

📝 Note:

• The comment argument can help attach descriptive text to the experiment action.
• Ensure that the duration argument is suffixed with the appropriate time unit (s, m, h).
• Make sure the total time of the command matches the time-step x amount of steps when using dec or inc modes

Example

cpu_load src_device_type:ue src_device_name:ue001 cores:5 load:20 time:60s

2. Network load

Generates defined ammount of traffic in a specific link in your network scenario. This method uses a client and a server that must be attached to both sides of the link you want to stress with network traffic.

network_load time:duration load:load-value src_device_type:src_device_type src_device_name:src_device_name 
dst_device_type:dst_device_type dst_device_name:dst_device_name comment:"any optional human-readable comment" 
mode:stress-mode random_seed:random-seed load_min:load-min load_max:load-max load_step:load-step time_step:time-step

Action: network_load

Argument	Description
time:	Duration of the network load test. Must be suffixed with a time unit (s for seconds, m for minutes, h for hours).
load:	Stress level as integer. Range [0-100]
src_device_type:	Type of the sender source device. Options include: router
src_device_name:	Name of the sender source device. Defined in ScenarioConfig.json
dst_device_type:	Type of the receiver (destination) device. Options include: ue, server
dst_device_name:	Name of the receiver (destination) device. Defined in ScenarioConfig.json

Optional Arguments

Argument	Description
comment:	A description or comment about the action.
mode:	String to specify the stress mode. Options include: stat (static, default), rand (random), inc (increasing), or dec (decreasing).
random_seed:	Integer used in rand mode to reproduce the same random load in subsequent experiments.
load_min:	Integer representing the minimum load value (defaults to 0). Used in inc and rand modes. dec mode will reduce load until this value is reached.
load_max:	Integer representing the maximum load value (defaults to 100). Used in dec and rand modes. inc mode will increase load until this value is reached.
load_step:	Integer (defaults to 1) representing the step value added in inc mode or subtracted in dec mode per iteration.
time_step:	Integer (defaults to 1) representing the duration of each iteration. Uses the same time unit as the time argument
interface:	Name of the interface in the source device.

Example

This syntax generates traffic from a source to a destination. Both devices should have implemented the network component.

network_load src_device_type:ue002 src_device_name:ue dst_device_type:server dst_device_name:srv102 load:50 time:5s

The below syntax is still permitted but is to be deprecated. It sends data from the load client to the load server connected to the specified router.

network_load src_device_type:router src_device_name:router1 interface:eth2 load:5 time:5s

3. Memory load

Action: memory_load

memory_load time:duration load:load-value src_device_type:src_device_type src_device_name:src_device_name 
workers:number-of-workers comment:"any optional human-readable comment" mode:stress-mode random_seed:random-seed 
load_min:load-min load_max:load-max load_step:load-step time_step:time-step

Argument	Description
time:	Duration of the stress test. Must be suffixed with a time unit (s for seconds, m for minutes, h for hours).
load:	Memory load to apply in MegaBytes.
src_device_type:	Type of the device to be stressed. Options include: ue, server
src_device_name:	Name of the device to be stressed. Defined in ScenarioConfig.json
workers:	Number of worker porcess to be used in the stress test.

Optional Arguments

Argument	Description
comment:	A description or comment about the experiment action.
mode:	Stress mode type. Options include: stat (static, default), rand (random), inc (increasing), or dec (decreasing).
random_seed:	Integer used in rand mode to reproduce the same random load in subsequent experiments.
load_min:	Integer representing the minimum load value. Used in inc and rand modes. dec mode will reduce load until this value is reached.
load_max:	Integer representing the maximum load value. Used in dec and rand modes. inc mode will increase load until this value is reached.
load_step:	Integer (defaults to 1) representing the step value added in inc mode or subtracted in dec mode per iteration.
time_step:	Integer (defaults to 1) representing the duration of each iteration. Uses the same time unit as the time argument

⚠️ *Warning:

• Memory load, also will generate CPU load, due to the manner computers work.
• load argument in Memory load is in MB and not percentage

Example

memory_load src_device_type:ue src_device_name:ue001 workers:5 load:800 time:10s

4. Network bandwidth

Triggers a bandwidth change in one of the interfaces of a router. It requires admin permissions for real infrastructure. Therefore, it mainly works with tools for network emulation such as containerlab. However, you will have to manually implement some changes in the manageInterface.sh file of the source code to match the name of the container, representing the router, where you want to change the bandwidth.

network_bandwidth time:duration bandwidth:bandwidth-value src_device_type:src_device_type src_device_name:src_device_name dst_device_type:dst_device_type dst_device_name:dst_device_name comment:"any optional human-readable comment" 

Action: network_bandwidth

Argument	Description
time:	Duration of the network load test. Must be suffixed with a time unit (s for seconds, m for minutes, h for hours).
bandwidth:	Bandwith to change as integer. Range [0-100]
src_device_type:	Type of the sender (source) device. Options include: router
src_device_name:	Name of the sender (source) device. Defined in ScenarioConfig.json
interface:	Name of the interface in the source device.

Optional Arguments

Argument	Description
comment:	A description or comment about the action.
dst_device_type:	Type of the receiver (destination) device. Options include: router
dst_device_name:	Name of the receiver (destination) device. Defined in ScenarioConfig.json

Example

network_bandwidth src_device_type:router src_device_name:router1 interface:eth2 bandwidth:20 time:30s

5. Start module

This command launches the modules defined in the ModuleConfig.json file, initiating their respective operations.

start_module module:module_name

Action: start_module

Argument	Description
module:	provide a module name from the ModuleConfig.json file.

Example

start_module module:experiment_dispatcher

⚠️ Warning: Only the experiment_dispatcher module is supported for now. The experiment_dispatcher module triggers the execution of experiments defined in the ExperimentConfig.json file.

5. Stop module

This command exits the modules defined in the ModuleConfig.json file, terminating their respective operations.

stop_module module:module_name

Action: stop_module

Argument	Description
module:	provide a module name from the ModuleConfig.json file.

Example

stop_module module:experiment_dispatcher

5. SSH action

The action executes the given custom_command on the device specified by using an ssh daemon.

📝 Note:

• The host, port and username, that should be used to connect to the ssh daemon on the device, are resolved from the ScenarioConfig.json.
• The ssh private key should be saved among the Module Configuration Files.
• The ssh public key should be accessible using an arbitrary url on the API.

ssh src_device_type:src_device_type src_device_name:src_device_name custom_command

Action: ssh

Argument	Description
src_device_type:	Type of the sender (source) device. Options include: ue, server
src_device_name:	Name of the sender (source) device. Defined in ScenarioConfig.json
custom_command	Command to run.

Example

ssh src_device_type:ue src_device_name:ue001 "echo Hello World"