trex_client Module documentation

CTRexClient class

class trex_client.CTRexClient(trex_host, max_history_size=100, filtered_latency_amount=0.001, trex_daemon_port=8090, master_daemon_port=8091, trex_zmq_port=4500, verbose=False, debug_image=False, trex_args='', timeout=30)[source]

This class defines the client side of the RESTfull interaction with TRex

Instantiate a TRex client object, and connecting it to listening daemon-server

Parameters
trex_hoststr

a string of the TRex ip address or hostname.

max_history_sizeint

a number to set the maximum history size of a single TRex run. Each sampling adds a new item to history.

default value : 100

filtered_latency_amountfloat

Ignore high latency for this ammount of packets. (by default take value of 99.9% measurements)

default value : 0.001

trex_daemon_portint

the port number on which the trex-daemon server can be reached

default value: 8090

master_daemon_portint

the port number on which the master-daemon server can be reached

default value: 8091

trex_zmq_portint

the port number on which trex’s zmq module will interact with daemon server

default value: 4500

verbosebool

sets a verbose output on supported class method.

default value : False

trex_argsstring

additional arguments passed to TRex. For example, “-w 3 –no-watchdog”

timeoutint

timeout in seconds to wait for socket response default value: 30

Raises

socket errors, in case server could not be reached.

cancel_reservation(user=None)[source]

Cancels a current reservation of TRex to a certain user.

When TRex is reserved, no other user can start new TRex runs.

Parameters
userstr

a username of the desired owner of TRex

default: current logged user

Returns

  • True if reservation canceled successfully,

  • False if there was no reservation at all.

Raises

  • trex_exceptions.TRexRequestDenied, in case TRex is reserved for another user than the one trying to cancel the reservation.

  • ProtocolError, in case of error in JSON-RPC protocol.

check_master_connectivity()[source]

Check Master daemon for connectivity. Return True upon success

check_server_connectivity()[source]

Checks TRex daemon server for connectivity.

force_kill(confirm=True)[source]

Force killing of running TRex process (if exists) on the server.

Tip

This method is a safety method and overrides any running or reserved resources, and as such isn’t designed to be used on a regular basis. Always consider using trex_client.CTRexClient.stop_trex() instead.

In the end of this method, TRex will return to IDLE state with no reservation.

Parameters
confirmbool

Prompt a user confirmation before continue terminating TRex session

Returns

  • True on successful termination

  • False otherwise.

Raises

  • ProtocolError, in case of error in JSON-RPC protocol.

get_file(filepath)[source]

Gets content of file as bytes string from /tmp/trex_files or TRex server directory.

Parameters
filepathstr

a path to a file at server. it can be either relative to TRex server or absolute path starting with /tmp/trex_files

Returns

Content of the file

Raises

  • trex_exceptions.TRexRequestDenied, in case TRex is reserved for another user than the one trying to cancel the reservation.

  • ProtocolError, in case of error in JSON-RPC protocol.

get_files_list(path)[source]

Gets a list of dirs and files either from /tmp/trex_files or path relative to TRex server.

Parameters
pathstr

a path to directory to read.

Returns

Tuple: list of dirs and list of files in given path

Raises

  • trex_exceptions.TRexRequestDenied, in case TRex is reserved for another user than the one trying to cancel the reservation.

  • ProtocolError, in case of error in JSON-RPC protocol.

get_result_obj(copy_obj=True)[source]

Returns the result object of the trex_client’s instance.

By default, returns a copy of the objects (so that changes to the original object are masked).

Parameters
copy_objbool

False means that a reference to the original (possibly changing) object are passed

defaul value : True

Returns

the latest result object (see CTRexResult for further details) with sampled data.

get_running_info()[source]

Performs single poll of TRex running data and process it into the result object (named result_obj).

Tip

This method will throw an exception if TRex isn’t running. Always consider using trex_client.CTRexClient.is_running() which handles a single poll operation in safer manner.

Parameters

None

Returns

dictionary containing the most updated data dump from TRex.

Raises

  • trex_exceptions.TRexIncompleteRunError, in case one of failed TRex run (unexpected termination).

  • TypeError, in case JSON stream decoding error.

  • ProtocolError, in case of error in JSON-RPC protocol.

get_running_status()[source]

Fetches the current TRex status.

If available, a verbose data will accompany the state itself.

Parameters

None

Returns

dictionary with ‘state’ and ‘verbose’ keys.

Raises

ProtocolError, in case of error in JSON-RPC protocol.

get_trex_cmds()[source]

Gets list of running TRex pids and command lines. Can be used to verify if any TRex is running.

Returns

List of tuples (pid, command) of running TRexes

get_trex_config()[source]

Get Trex config file (/etc/trex_cfg.yaml).

Returns

String representation of TRex config file

Raises
get_trex_daemon_log()[source]

Get Trex daemon log.

Returns

String representation of TRex daemon log

Raises
get_trex_files_path()[source]

Fetches the local path in which files are stored when pushed to TRex server from client.

Parameters

None

Returns

string representation of the desired path

Note

The returned path represents a path on the TRex server local machine

Raises

ProtocolError, in case of error in JSON-RPC protocol.

get_trex_log()[source]

Get TRex CLI output log

Returns

String representation of TRex log

Raises
get_trex_path()[source]

Returns TRex path on server

get_trex_version()[source]

Get TRex version details.

Returns

Trex details (Version, User, Date, Uuid, Git SHA) as ordered dictionary

Raises

  • trex_exceptions.TRexRequestDenied, in case TRex version could not be determined.

  • ProtocolError, in case of error in JSON-RPC protocol.

  • KeyError is case one of the keys is missing in response

is_idle()[source]

Poll for TRex running status, check if TRex is in Idle state.

Parameters

None

Returns

  • True if TRex is idle.

  • False if TRex is starting or running.

Raises

  • trex_exceptions.TRexIncompleteRunError, in case one of failed TRex run (unexpected termination).

  • TypeError, in case JSON stream decoding error.

  • ProtocolError, in case of error in JSON-RPC protocol.

is_query_relevance()[source]

Checks if time between any two consecutive server queries (asking for live running data) passed.

Note

The allowed minimum time between each two consecutive samples is 0.5 seconds.

Parameters

None

Returns

  • True if more than 0.5 seconds has been past from last server query.

  • False otherwise.

is_reserved()[source]

Checks if TRex is currently reserved to any user or not.

Parameters

None

Returns

  • True if TRex is reserved.

  • False otherwise.

Raises

ProtocolError, in case of error in JSON-RPC protocol.

is_running(dump_out=False)[source]

Poll for TRex running status.

If TRex is running, a history item will be added into result_obj and processed.

Tip

This method is especially useful for iterating until TRex run is finished.

Parameters
dump_outdict

if passed, the pointer object is cleared and the latest dump stored in it.

Returns

  • True if TRex is running.

  • False if TRex is not running.

Raises

  • trex_exceptions.TRexIncompleteRunError, in case one of failed TRex run (unexpected termination).

  • TypeError, in case JSON stream decoding error.

  • ProtocolError, in case of error in JSON-RPC protocol.

is_trex_daemon_running()[source]

Check if TRex server daemon is running. Returns True/False

kill_all_trexes(timeout=15)[source]

Kills running TRex processes (if exists) on the server, not only owned by current daemon. Raises exception upon error killing.

Returns

  • True if processes killed/not running

  • False otherwise.

master_add(x, y)[source]

Sanity check for Master daemon

prompt_verbose_data()[source]

This method prompts any verbose data available, only if verbose option has been turned on.

push_files(filepaths)[source]

Pushes a file (or a list of files) to store locally on server.

Parameters
filepathsstr or list

a path to a file to be pushed to server. if a list of paths is passed, all of those will be pushed to server

Returns

  • True if file(s) copied successfully.

  • False otherwise.

Raises

  • IOError, in case specified file wasn’t found or could not be accessed.

  • ProtocolError, in case of error in JSON-RPC protocol.

reserve_trex(user=None)[source]

Reserves the usage of TRex to a certain user.

When TRex is reserved, it can’t be reserved.

Parameters
userstr

a username of the desired owner of TRex

default: current logged user

Returns

True if reservation made successfully

Raises
restart_trex_daemon(tries=1)[source]

Restart TRex server daemon. Useful after update. Will not fail if daemon is initially stopped.

sample_until_condition(condition_func, time_between_samples=1)[source]

Automatically sets ongoing sampling of TRex data, with sampling rate described by time_between_samples.

On each fetched dump, the condition_func is applied on the result objects, and if returns True, the sampling will stop.

Parameters
condition_funcfunction

function that operates on result_obj and checks if a condition has been met

Note

condition_finc is applied on CTRexResult object. Make sure to design a relevant method.

time_between_samplesint

determines the time between each sample of the server

default value : 1

Returns

the first result object (see CTRexResult for further details) of the TRex run on which the condition has been met.

Raises

  • UserWarning, in case the condition_func method condition hasn’t been met

  • trex_exceptions.TRexIncompleteRunError, in case one of failed TRex run (unexpected termination).

  • TypeError, in case JSON stream decoding error.

  • ProtocolError, in case of error in JSON-RPC protocol.

  • Exception, in case the condition_func suffered from any kind of exception

sample_until_finish(time_between_samples=1)[source]

Automatically samples TRex data with sampling rate described by time_between_samples until TRex run finishes.

Parameters
time_between_samplesint

determines the time between each sample of the server

default value : 1

Returns

the latest result object (see CTRexResult for further details) with sampled data.

Raises

  • UserWarning, in case the condition_func method condition hasn’t been met

  • trex_exceptions.TRexIncompleteRunError, in case one of failed TRex run (unexpected termination).

  • TypeError, in case JSON stream decoding error.

  • ProtocolError, in case of error in JSON-RPC protocol.

sample_x_seconds(sample_time, time_between_samples=1)[source]

Automatically sets ongoing sampling of TRex data for sample_time seconds, with sampling rate described by time_between_samples. Does not stop the TRex afterwards!

Tip

Useful for changing the device (Router, ASA etc.) configuration after given time.

Parameters
sample_timeint

sample the TRex this number of seconds

time_between_samplesint

determines the time between each sample of the server

default value : 1

Returns

the first result object (see CTRexResult for further details) of the TRex run after given sample_time.

Raises

  • UserWarning, in case the TRex run ended before sample_time duration

  • trex_exceptions.TRexIncompleteRunError, in case one of failed TRex run (unexpected termination).

  • TypeError, in case JSON stream decoding error.

  • ProtocolError, in case of error in JSON-RPC protocol.

start_stateless(block_to_success=True, timeout=40, user=None, **trex_cmd_options)[source]

Request to start a TRex run on server in stateless mode.

Parameters
block_to_successbool

determine if this method blocks until TRex changes state from ‘Starting’ to either ‘Idle’ or ‘Running’

default value : True

timeoutint

maximum time (in seconds) to wait in blocking state until TRex changes state from ‘Starting’ to either ‘Idle’ or ‘Running’

default value: 40

userstr

the identity of the the run issuer.

trex_cmd_optionskey, val

sets desired TRex options using key=val syntax, separated by comma. for keys with no value, state key=True

Returns

True on success

Raises
start_trex(f, d, block_to_success=True, timeout=40, user=None, trex_development=False, **trex_cmd_options)[source]

Request to start a TRex run on server in stateful mode.

Parameters
fstr

a path (on server) for the injected traffic data (.yaml file)

dint

the desired duration of the test. must be at least 30 seconds long.

block_to_successbool

determine if this method blocks until TRex changes state from ‘Starting’ to either ‘Idle’ or ‘Running’

default value : True

timeoutint

maximum time (in seconds) to wait in blocking state until TRex changes state from ‘Starting’ to either ‘Idle’ or ‘Running’

default value: 40

userstr

the identity of the the run issuer.

trex_cmd_optionskey, val

sets desired TRex options using key=val syntax, separated by comma. for keys with no value, state key=True

Returns

True on success

Raises
start_trex_daemon()[source]

Start TRex server daemon.

Returns

  • True if success.

  • False if TRex server daemon already running.

stop_trex()[source]

Request to stop a TRex run on server.

The request is only valid if the stop initiator is the same client as the TRex run initiator.

Parameters

None

Returns

  • True on successful termination

  • False if request issued but TRex wasn’t running.

Raises
stop_trex_daemon()[source]

Stop TRex server daemon.

Returns

  • True if success.

  • False if TRex server daemon already running.

wait_until_kickoff_finish(timeout=40)[source]

Block the client application until TRex changes state from ‘Starting’ to either ‘Idle’ or ‘Running’

The request is only valid if the stop initiator is the same client as the TRex run initiator.

Parameters
timeoutint

maximum time (in seconds) to wait in blocking state until TRex changes state from ‘Starting’ to either ‘Idle’ or ‘Running’

Returns

  • True on successful termination

  • False if request issued but TRex wasn’t running.

Raises

Note

Exceptions are throws only when start_trex did not block in the first place, i.e. block_to_success parameter was set to False

CTRexResult class

class trex_client.CTRexResult(max_history_size, filtered_latency_amount=0.001)[source]

A class containing all results received from TRex.

Ontop to containing the results, this class offers easier data access and extended results processing options

Instatiate a TRex result object

Parameters
max_history_sizeint

A number to set the maximum history size of a single TRex run. Each sampling adds a new item to history.

filtered_latency_amountfloat

Ignore high latency for this ammount of packets. (by default take into account 99.9%)

clear_results()[source]

Clears all results and sets the history’s validity to False

Parameters

None

Returns

None

get_avg_latency()[source]

Fetches the average latency measured on each of the interfaces from the start of TRex run

Parameters

None

Returns

dictionary containing the average latency, where the key is the measurement interface (c indicates client), and the value is the measurement value.

The all key represents the average of all interfaces’ average

get_avg_steady_state_value(tree_path_to_key)[source]

Gets average value after warmup period. For example: <result object>.get_avg_steady_state_value(‘trex-global.data.m_tx_bps’) Usually more accurate than latest history value.

Parameters
tree_path_to_keystr

defines a path to desired data.

Returns

average value at steady state

Raises

KeyError in case steady state period was not reached or tree_path_to_key was not found in result.

get_avg_window_latency()[source]

Fetches the average latency measured on each of the interfaces from all the sampled currently stored in window.

Parameters

None

Returns

dictionary containing the average latency, where the key is the measurement interface (c indicates client), and the value is the measurement value.

The all key represents the average of all interfaces’ average

get_current_tx_rate()[source]

Fetches the current TX rate in various units representation

Parameters

None

Returns

dictionary containing the current TX rate, where the key is the measurement units, and the value is the measurement value.

get_drop_rate()[source]

Fetches the most recent drop rate in pkts/sec units.

Parameters

None

Returns

current drop rate (as float)

get_expected_tx_rate()[source]

Fetches the expected TX rate in various units representation

Parameters

None

Returns

dictionary containing the expected TX rate, where the key is the measurement units, and the value is the measurement value.

get_is_latency_exists()[source]

return True if latency information exists

Parameters

None

Returns

True or False

get_jitter_latency()[source]

Fetches the jitter latency measured on each of the interfaces from the start of TRex run

Parameters

None

Returns

dictionary containing the average latency, where the key is the measurement interface (c indicates client), and the value is the measurement value.

The all key represents the average of all interfaces’ average

get_last_value(tree_path_to_key, regex=None)[source]

A dynamic getter from the latest sampled data item stored in the result object.

Parameters
tree_path_to_keystr

defines a path to desired data.

Tip

Use ‘.’ to enter one level deeper in dictionary hierarchy.
Use ‘[i]’ to access the i’th indexed object of an array.
regexregex

apply a regex to filter results out from a multiple results set.

Filter applies only on keys of dictionary type.

dafault value : None

Returns

  • a list of values relevant to the specified path

  • None if no results were fetched or the history isn’t valid.

get_latest_dump()[source]

A getter to the latest sampled data item stored in the result object.

Parameters

None

Returns

  • a dictionary of the latest data item

  • an empty dictionary if history is empty.

get_max_latency()[source]

Fetches the maximum latency measured on each of the interfaces

Parameters

None

Returns

dictionary containing the maximum latency, where the key is the measurement interface (c indicates client), and the value is the measurement value.

get_min_latency()[source]

Fetches the minimum latency measured on each of the interfaces

Parameters

None

Returns

dictionary containing the maximum latency, where the key is the measurement interface (c indicates client), and the value is the measurement value.

get_ports_count()[source]

Returns number of ports based on TRex result

Returns

  • number of ports in TRex result

  • -1 if history is empty.

get_total_drops()[source]

Fetches the total number of drops identified from the moment TRex run began.

Parameters

None

Returns

total drops count (as int)

get_value_list(tree_path_to_key, regex=None, filter_none=True)[source]

A dynamic getter from all sampled data items stored in the result object.

Parameters
tree_path_to_keystr

defines a path to desired data.

Tip

Use ‘.’ to enter one level deeper in dictionary hierarchy.
Use ‘[i]’ to access the i’th indexed object of an array.
regexregex

apply a regex to filter results out from a multiple results set.

Filter applies only on keys of dictionary type.

dafault value : None

filter_nonebool

specify if None results should be filtered out or not.

dafault value : True

Returns

  • a list of values relevant to the specified path. Each item on the list refers to a single server sample.

  • None if no results were fetched or the history isn’t valid.

is_done_warmup()[source]

Checks if TRex latest results TX-rate indicates that TRex has reached its expected TX-rate.

Parameters

None

Returns

  • True if expected TX-rate has been reached.

  • False otherwise.

is_valid_hist()[source]

Checks if result obejct contains valid data.

Parameters

None

Returns

  • True if history is valid.

  • False otherwise.

set_valid_hist(valid_stat=True)[source]

Sets result obejct validity status.

Parameters
valid_statbool

defines the validity status

dafault value : True

Returns

None

update_result_data(latest_dump)[source]

Integrates a latest_dump dictionary into the CTRexResult object.

Parameters
latest_dumpdict

a dictionary with the items desired to be integrated into the object history and stats

Returns

None