TRex Control Plane Design - Phase 1 peek
=========================================
:author: Dan Klein 
:email: <danklei@cisco.com> 
:revnumber: 1.0
:quotes.++:
:numbered:


include::trex_ga.asciidoc[]


=== TRex traffic generator

TRex traffic generator is a tool design the benchmark platforms with realistic traffic.
This is a work-in-progress product, which is under constant developement, new features are added and support for more router's fuctionality is achieved.

=== TRex Control

TRex control plane is under developement, and a phase 1 is planned to be published soon (Apr 2015). +
This document will shortly describe the planned control plane for TRex, which is planned to be more scalable and support automation more intuitively.

==== TRex Control Plane - High Level

TRex control plane is based on a JSON RPC transactions between clients and server. +
Each TRex machine will have a server running on it, closely interacting with TRex (clients do not approach TRex directly). +
As future feature, and as multiple T-Rexes might run on the same machine, single server shall serve all T-Rexes running a machine.

The client is a Python based application that created `TRexClient` instances. +
Using class methods, the client interacts with TRex server, and enable it to perform the following commands:

  1. Start TRex run (custom parameters supported).

  2. Stop  TRex run.

  3. Check what is the TRex status (possible states: `Idle, Starting, Running`).

  4. Poll (by customize sampling) the server and get live results from TRex **while still running**.

  5. Get custom TRex stats based on a window of saved history of latest 'N' polling results.


==== TRex Control Plane - Example crumbs

  

  - **Exmaple #1: Checking TRex status and Launching TRex**
    The following program checks TRex status, and later on launches it, querying its status along different time slots.

[source, python]
----
import time

trex = CTRexClient('trex-name')  
print "Before Running, TRex status is: ", trex.is_running()           # <1>
print "Before Running, TRex status is: ", trex.get_running_status()   # <2>

ret = trex.start_trex( c = 2, 										   # <3>	
        m = 0.1,
        d = 20,
        f = 'avl/sfr_delay_10_1g.yaml',
        nc = True,
        p = True,
        l = 1000)

print "After Starting, TRex status is: ", trex.is_running(), trex.get_running_status()

time.sleep(10)	# <4>

print "Is TRex running? ", trex.is_running(), trex.get_running_status() # <5>
----

<1> `is_running()` returns a boolean and checks if TRex is running or not.

<2> `get_running_status()` returns a Python dictionary with TRex state, along with a verbose field containing extra info, if available.

<3> TRex lanching. All types of inputs are supported. Some fields (such as 'f' and 'c' are mandatory).

<4> Going to sleep for few seconds, allowing TRex to start.

<5> Checking out with TRex status again, printing both a boolean return value and a full status.

This code will prompt the following output, assuming a server was launched on the TRex machine.

----
Connecting to TRex @ http://trex-dan:8090/ ...
Before Running, TRex status is:  False
Before Running, TRex status is:  {u'state': <TRexStatus.Idle: 1>, u'verbose': u'TRex is Idle'}
                                                      <1>                             <1>

After Starting, TRex status is:  False {u'state': <TRexStatus.Starting: 2>, u'verbose': u'TRex is starting'}
                                                      <1>                             <1>
Is TRex running?  True {u'state': <TRexStatus.Running: 3>, u'verbose': u'TRex is Running'}
                                                      <1>                             <1>
----

<1> When looking at TRex status, both an enum status (`Idle, Starting, Running`) and verbose output are available.


  * **Exmaple #2: Checking TRex status and Launching TRex with 'BAD PARAMETERS'**
    The following program checks TRex status, and later on launches it with wrong input ('mdf' is not legal option), hence TRex run will not start and a message will be available.

[source, python]
----
import time

trex = CTRexClient('trex-name')  
print "Before Running, TRex status is: ", trex.is_running()           # <1>
print "Before Running, TRex status is: ", trex.get_running_status()   # <2>

ret = trex.start_trex( c = 2, 										   # <3>	
#<4>     mdf = 0.1,
        d = 20,
        f = 'avl/sfr_delay_10_1g.yaml',
        nc = True,
        p = True,
        l = 1000)

print "After Starting, TRex status is: ", trex.is_running(), trex.get_running_status()

time.sleep(10)	# <5>

print "Is TRex running? ", trex.is_running(), trex.get_running_status() # <6>
----

<1> `is_running()` returns a boolean and checks if TRex is running or not.

<2> `get_running_status()` returns a Python dictionary with TRex state, along with a verbose field containing extra info, if available.

<3> TRex lanching. All types of inputs are supported. Some fields (such as 'f' and 'c' are mandatory).

<4> Wrong parameter ('mdf') injected.

<5> Going to sleep for few seconds, allowing TRex to start.

<6> Checking out with TRex status again, printing both a boolean return value and a full status.

This code will prompt the following output, assuming a server was launched on the TRex machine.
----
Connecting to TRex @ http://trex-dan:8090/ ...
Before Running, TRex status is:  False
Before Running, TRex status is:  {u'state': <TRexStatus.Idle: 1>, u'verbose': u'TRex is Idle'}
                                                      <1>                             <1>

After Starting, TRex status is:  False {u'state': <TRexStatus.Starting: 2>, u'verbose': u'TRex is starting'}
                                                      <1>                             <1>
Is TRex running?  False {u'state': <TRexStatus.Idle: 1>, u'verbose': u'TRex run failed due to wrong input parameters, or due to reachability issues.'}
                                                      <2>                             <2>
----

<1> When looking at TRex status, both an enum status (`Idle, Starting, Running`) and verbose output are available.
 
<2> After TRex lanuching failed, a message indicating the failure reason. However, TRex is back Idle, ready to handle another launching request.


  * **Exmaple #3: Launching TRex, monitor live data and stopping on demand**
    The following program will launch TRex, and while it runs poll the server (every 5 seconds) for running inforamtion, such as latency, drops, and other extractable parameters. +
    Then, after some criteria was met, TRex execution is terminated, enabeling others to use the resource instead of waiting for the entire execution to finish.
    
[source, python]
----
print "Before Running, TRex status is: ", trex.get_running_status()

    print "Starting TRex..."
    ret = trex.start_trex( c = 2, 
        mdf = 0.1,
        d = 100,
        f = 'avl/sfr_delay_10_1g.yaml',
        nc = True,
        p = True,
        l = 1000)

    print "After Starting, TRex status is: ", trex.is_running(), trex.get_running_status()
    print "sleeping 20 secs.."
    time.sleep(20)
    for i in range(5):
        print "Is TRex running? ", trex.is_running(), trex.get_running_status()	#<1>
    #<2> received_info = trex.get_running_info()	
    #<3> # Custom data processing is done here									
    #<4> time.sleep(5)

    print "Terminating TRex..."
    #<5> ret = trex.stop_trex() 															
    print "After stopping, TRex status is: ", trex.is_running(), trex.get_running_status() #<6>
----

<1> Running queries is still optional, although not mandatory in order to get stats.

<2> `get_running_info()` will return the latest data dump available from TRex. + 
    Some aditional data manipulation and queries are under developement, including manipulation over number of dumps, which is useful for avoiding "spikes" of singular behavior.

<3> Data processing. This is fully customizable for the relevant test initiated.

<4> The sampling rate is flexibale and can be configured depending on the desired output.

<5> TRex termination.

<6> Post-termination check for status.

	
This code will prompt the following output, assuming a server was launched on the TRex machine.
----
Connecting to TRex @ http://trex-dan:8090/ ...
Before Running, TRex status is:  False
Before Running, TRex status is:  {u'state': <TRexStatus.Idle: 1>, u'verbose': u'TRex is Idle'}
Starting TRex...
After Starting, TRex status is:  False {u'state': <TRexStatus.Starting: 2>, u'verbose': u'TRex is starting'}

<1> Is TRex running?  True {u'state': <TRexStatus.Running: 3>, u'verbose': u'TRex is Running'}

<1> Is TRex running?  True {u'state': <TRexStatus.Running: 3>, u'verbose': u'TRex is Running'}

<1> Is TRex running?  True {u'state': <TRexStatus.Running: 3>, u'verbose': u'TRex is Running'}

<1> Is TRex running?  True {u'state': <TRexStatus.Running: 3>, u'verbose': u'TRex is Running'}

<1> Is TRex running?  True {u'state': <TRexStatus.Running: 3>, u'verbose': u'TRex is Running'}

Before terminating, TRex status is:  True {u'state': <TRexStatus.Running: 3>, u'verbose': u'TRex is Running'}
Terminating TRex...
#<2> After stopping, TRex status is:  False {u'state': <TRexStatus.Idle: 1>, u'verbose': u'TRex finished (terminated).'}

----

<1> Polling TRex status while in a data polling loop.

<2> After termination, we can see that TRex is back idle, also the `verbose` field shows the stop reason