Playing, Stopping, and Listing Scenarios

Scenario functionality in the Eggplant Network device provides the ability to play time-based emulations. These are created by putting together one or more standard emulations or scenarios with transitions using the Scenario editor in the Emulator GUI. Familiarize yourself with scenarios in the GUI before using these API commands. At this time, the API concerns itself solely with playing (running) timed scenarios. Creating or editing timed Scenarios is done in the Scenario editor GUI.

Get a List of Scenarios

Gets a list of all the available scenarios, their types (point-to-point or multi-hop), durations, and end mode (what happens at the end of the scenario: Stop the emulation, Stay in the last configuration, Go back to the beginning).

Syntax:

--listScenario

Output:

--scenarios "{number of scenarios};{name of scenario};{emulation type};{duration};{end mode};...."

In this output, number of scenarios is the number of defined scenarios that are valid.

Each valid scenario is then listed and comes with 4 fields:

Name of Scenario: Scenario name

Emulation type: ptp or multihop

Duration: The total duration of the scenario in seconds

End mode: The scenario’s behavior when reaching its end (1 - Stop Emulation, 2 - Stays On with the parameters from the last element of the scenario, 3 – Repeat)

Examples:

C:\Users\Lara>python necli.py --host 192.168.202.135 --user admin --password admin --listScenario

--scenarios "3;Dual_Link_1;ptp;60;1;Dual_Link_2;ptp;60;1;Single_Link_1;ptp;100;1;"

Play (Run) a Scenario

This allows you to run a scenario by name specifying the point pair on which it should run and the playback speed (the default is 1x – normal speed).

Syntax:

--playScenario {Scenario Name} --portPair {Port Pair} [--speed {Speed} (one of 1|2|4|0.5|0.25)]

Scenario Name is the scenario to play.

Port Pair is the port pair on which to start an scenario.

Speed is the speed at which to run the scenario. Valid values are 1, 2, 4, 0.5, 0.25, which plays the scenario faster (2, 4), at normal speed (1) or slower (0.5, 0.25). The speed value is a divisor for how long 1 second of scenario actually takes to run. If speed is not specified, the default is 1, or normal speed.

Output:

--ok (if successful) or

--error "{reason}" (if there was a problem – the reason specifies the issue)

Examples:

C:\Users\Lara>python necli.py --host 192.168.202.135 --user admin --password admin --playScenario Dual_Link_1 --portpair 0

--ok

The scenario now plays (in the background).

Note: If the scenario name contains a space, place it in quotation marks: --playScenario "My Scenario"

Pause a Playing (Running) Scenario

This pauses the scenario running on a port pair. The timer freezes, but the emulation remains in its current state (i.e., the emulation keeps running).

Syntax:

--pauseScenario --portPair {portPair}

{portPair} is either 0 for the first port pair (ports 0 & 1) or 1 for the second port pair (ports 2 & 3).

Output:

--ok

--error "{reason}"

Examples:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --pauseScenario --portpair 0

--ok

Resume a Paused Scenario

This resumes a previously paused scenario running on a port pair. It resumes the timer from where it paused, and the scenario continues to run from that point

Syntax:

--resumeScenario --portPair {portPair}

{portPair} is either 0 for the first port pair (ports 0 & 1) or 1 for the second port pair (ports 2 & 3)

Output:

--ok

--error "{reason}"

Examples:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --resumeScenario --portpair 0

--ok

Stop a Playing (Running) Scenario

This stops the scenario running on a port pair. The timer stops and the emulation stops.

Syntax:

--stopScenario --portPair {portPair}

{portPair} is either 0 for the first port pair (ports 0 & 1) or 1 for the second port pair (ports 2 & 3)

Output:

--ok

--error "{reason}"

Examples:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --stopScenario --portpair 0

--ok

Set Scenario Speed

This has two functions:

To set the default playback speed for a port pair.

To change the speed at which a currently running scenario plays back. This value persists for the next time a scenario is started on the port pair.

Syntax:

--setSpeed {Speed} (one of 1|2|4|0.5|0.25) --portPair {portPair}

{Speed} is one of 1|2|4|0.5|0.25. This plays the scenario faster (2, 4), at normal speed (1) or slower (0.5, 0.25). The speed value is a divisor for how long 1 second of scenario actually takes to run.

{portPair} is either 0 for the first port pair (ports 0 & 1) or 1 for the second port pair (ports 2 & 3).

Output:

--ok

--error "{reason}"

Examples:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --setSpeed 0.25 --portPair 0

--ok

This example runs the scenario at one-quarter of normal speed (the scenario and each element in it take four times as long to complete). If the scenario is running in the GUI, the scenario progress bar moves at one-quarter of its normal rate.

Note: Issuing the –setSpeed CLI or API does not immediately change the value in the GUI drop-down speed menu (if the GUI is being used). However, if you play a scenario in the GUI, it accepts the speed change and the GUI drop-down menu changes at that moment.

Advance to Next Scenario Frame

This advances the scenario to the next scenario frame or element, which might be a transition or an emulation. If a transition is running when the command is received, the Emulator abandons the transition and sets the values for the next emulation element.

Syntax:

--nextScenFrame --portPair {portPair}

{portPair} is either 0 for the first port pair (ports 0 & 1) or 1 for the second port pair (ports 2 & 3)

Output:

--ok

--error "{reason}"

Examples:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --nextScenFrame --portPair 0

--ok

Note: If you are already in the last element of the scenario, the emulator displays an error message: "Cannot fast forward: already at the end of the scenario".

Go Back to Previous Scenario Frame

This returns the scenario to the start of the previous scenario frame or element, which might be a transition or an emulation. If a transition is running when the command is received, the Emulator abandons the transition and sets the values for the previous emulation element.

Syntax:

--prevScenFrame --portPair {portPair}

{portPair} is either 0 for the first port pair (ports 0 & 1) or 1 for the second port pair (ports 2 & 3)

Output:

--ok

--error "{reason}"

Examples:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --prevScenFrame --portPair 0

--ok

Note: If more than a few seconds of the element have passed, the Emulator doesn't return to the start of that element. To do this, use --prevScenFrame, immediately followed by --nextScenFrame.
Note: If you are in the first element of the scenario, the Emulator doesn’t return to the start of that element. Instead, the Emulator displays an error message: "Cannot rewind: already at the start of the scenario".

Get Scenario Running Information

This gets information on scenarios running by port pair. You can see if scenarios are running and, if running, the name of the scenario.

Syntax:

--getScenarioByPortPair [--portPair {portPair}]

Output:

With the optional portPair argument:

--status "1;{portPair};{running};{scenario name};"

{portPair} is either 0 for the first port pair (ports 0 & 1) or 1 for the second port pair (ports 2 & 3).

{running} is 0 if a scenario is running on that port pair.

{scenario name} is the name of the scenario if there is one running on that port pair.

Without the optional portPair argument:

--status "{Number of ports};0;{running for portpair 0};{name of scenario for portpair 0};…" (for each port pair)

Here there are two port pairs (4 ports), and no scenarios are running on any port pair:

Example:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --getScenarioByPortPair

--status "2;0;0;;1;0;;"

Here there are two port pairs (4 ports), and a scenario called Dual_Link_1 is running on port pair 0:

Example:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --getScenarioByPortPair

--status "2;0;1;Dual_Link_1;1;0;;"

In the next two examples, there are two port pairs (4 ports) and a scenario called Dual_Link_1 is running on port pair 0:

Example:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --getScenarioByPortPair --portpair 0

--status "1;0;1;Dual_Link_1;"

Example:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --getScenarioByPortPair --portpair 1

--status "1;1;0"

Get Running Scenario Details

Returns details on scenarios running by port pair. You can see the status of scenarios, when they were started, the element name, remaining time, speed they are running at, and error status.

Syntax:

--scenarioStatus [--portPair {portPair}]

{portPair} is either 0 for the first port pair (ports 0 & 1) or 1 for the second port pair (ports 2 & 3).

{scenario name} is the name of the current scenario if one is running on that port pair.

{status} is the current status of the scenario that's running. Possible values are STOP, PLAY, and PAUSE.

{at time} is the time from the start of the scenario, in seconds.

{started At} UTC time (in milliseconds) when the scenario started (Unix time in ms).

{element name} is the name of the emulation element currently in force. If it is a transition, the name is Gradual, Variable, or Outage.

{time left} is the time left in the current element, named above.

{speed} is the speed at which the scenario is running. It is one of 1|2|4|0.5|0.25. The speed value is a divisor for how long one second of scenario actually takes to run.

{error} indicates any error so far during the running scenario (1 - error, 0 - no error).

Output:

With the optional portPair argument, it returns details only for the port pair specified. Without the optional portPair argument, it returns the number of scenarios and details for each port pair:

--status "{number of portpairs};{portPair};{scenario name};{status};{at time};{started At};{element name};{time left};{speed};{error}…"

--error "Error message"

Example:

In the next two examples, there are two port pairs (4 ports) and a Scenario called Dual_Link_1 is running on port pair 0:

Example:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --scenarioStatus --portpair 0

--status "1;0;Dual_Link_1;PLAY;11;1490352881053;Test_twolink_1;9;1;0"

On port pair 0, a scenario called Dual_Link_1 is running. Its status is PLAY, it has been running for 11 seconds, the absolute start time of the scenario in UTC ms time is 1490352881053, the current element is Test_twolink_1 with 9 seconds left for that element, running at speed 1 (1x = Normal) and Error = 0 (no current error).

Example:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --scenarioStatus --portpair 1

--error "'"Scenario is not loaded or running on the port pair"\n'"

In the next example, a scenario called Dual_Link_1, running on port pair 0, is in the element Gradual, i.e., a gradual transition:

Example:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --scenarioStatus --portpair 0

--status "1;0;Dual_Link_1;PLAY;27;1490354519057;Gradual;12;1;0"

You can see the word Gradual in the element position, and there are 12 seconds of Gradual left to run.

Get Scenario Errors

This retrieves a list of errors from the currently running scenario.

Syntax:

--getScenarioErrors --portPair {portPair} [--reset]

--portPair {portPair} chooses the port pair – either 0 for the first port pair (ports 0 & 1) or 1 for the second port pair (ports 2 & 3).

--reset resets the list after returning any errors (optional).

{time} lists the second at which the error occurred relative to the scenario start.

{message} lists details of the error.

Output:

--errors "{time};{message};{time};{message}..."

Examples:

C:\Users\Lara>python necli.py --host 192.168.202.135 --user admin --password admin --getScenarioErrors –portPair 0

--errors (if no errors)

--error "Scenario is not loaded or running on the port pair" (if no scenario running)

Run Scenario Logging (advanced)

These commands are used for the automated testing of the CLI/API and should only be used under the guidance of your support representative. These commands produce very high amounts of output, which can affect the performance of the scenario server.

--setScenarioRunLogs

Syntax:

--setScenarioRunLogs [--portPair {portPair}] [--runLogDir {dir}]

This turns on the run log feature in the scenario server. If portPair argument is not given, then it switches on run time logging for all port pairs. If runLogDir is not given, the default directory for creating run time log files is /tmp.

The log filename is the same as the scenario name with a .log extension and port pair suffix. For example, if Testing.scen is loaded and run in port pair 0, the log file is Testing_0.log. If the log file is from previous run, it is renamed Testing_0.log.old.

The log file only contains entries during the lifetime of a running scenario.

Each entry is a single line, with newline terminated representing a single interval.

Each interval line is prefixed with Interval {secs}:

Only intervals with notable action are logged, such as: Start/End of the scenario; Start/End of a component; Pause/Resume the scenario; Speed change; Component skip; (TBD) micro intervals of transition.

--setScenarioRunLogs

Syntax:

--setScenarioRunLogs [--portPair {portPair}] --off

This turns off the run log feature.

--getScenarioRunLog

Syntax:

--getScenarioRunLog {scenario name} --portPair {portPair} [--interval {interval}]

This returns the log entries of the scenario previously run. If --interval is not given, it returns all log entries.

--interval accepts the following forms:

-{num} logs from interval 0 to interval num

+{num} logs from interval num+1 to the latest logs

{num1}-{num2} logs between the interval

{num1},{num2},{num3} is a list of specific logs at specific intervals

--playScenario with –logtrans

Syntax:

--playScenario {Scenario name} --portpair {portPair} --logtrans

This starts logging, which includes transition steps.

Example:

C:\Users\Lara> python necli.py --host 192.168.202.135 --user admin --password admin --playScenario Dual_Link_1 --portpair 0 --logtrans

--ok

 

This topic was last updated on June 21, 2019, at 02:49:49 PM.

Eggplant icon Eggplantsoftware.com | Documentation Home | User Forums | Support | Copyright © 2019 Eggplant