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_host : str

a string of the TRex ip address or hostname.

max_history_size : int

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_amount : float

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

default value : 0.001

trex_daemon_port : int

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

default value: 8090

master_daemon_port : int

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

default value: 8091

trex_zmq_port : int

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

default value: 4500

verbose : bool

sets a verbose output on supported class method.

default value : False

trex_args : string

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

timeout : int

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:
user : str

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:
confirm : bool

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:
filepath : str

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:
path : str

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_obj : bool

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_out : dict

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:
filepaths : str 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:
user : str

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_func : function

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_samples : int

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_samples : int

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_time : int

sample the TRex this number of seconds

time_between_samples : int

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_success : bool

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

default value : True

timeout : int

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

default value: 40

user : str

the identity of the the run issuer.

trex_cmd_options : key, 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:
f : str

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

d : int

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

block_to_success : bool

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

default value : True

timeout : int

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

default value: 40

user : str

the identity of the the run issuer.

trex_cmd_options : key, 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:
timeout : int

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_size : int

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

filtered_latency_amount : float

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_key : str

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_key : str

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.
regex : regex

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_key : str

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.
regex : regex

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

Filter applies only on keys of dictionary type.

dafault value : None

filter_none : bool

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_stat : bool

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_dump : dict

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

Returns:

None