diff options
Diffstat (limited to 'doc/trex_control_plane_peek.asciidoc')
| -rwxr-xr-x | doc/trex_control_plane_peek.asciidoc | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/doc/trex_control_plane_peek.asciidoc b/doc/trex_control_plane_peek.asciidoc new file mode 100755 index 00000000..ce923d0b --- /dev/null +++ b/doc/trex_control_plane_peek.asciidoc @@ -0,0 +1,227 @@ +TRex Stateful Python API Tutorial +================================= +: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
\ No newline at end of file |