Added the README file documenting the test suite

Change-Id: I2da2a79f3aa57f38872340155bd5fcc9e9443831
Signed-off-by: Jan Medved <jmedved@cisco.com>

diff --git a/test/tools/odl-mdsal-clustering-tests/clustering-performance-test/README b/test/tools/odl-mdsal-clustering-tests/clustering-performance-test/README
new file mode 100644 (file)
index 0000000..595e3b3
--- /dev/null
+++ b/test/tools/odl-mdsal-clustering-tests/clustering-performance-test/README
@@ -0,0 +1,177 @@
+OpenDaylight Performance Test Suite
+===================================
+
+The performance tests in this suite use ODL's RESTCONF API to add/delete
+flows into/from ODL's configuration data store. The test suite contains
+the following scripts:
+
+- inventory_crawler.py: 
+  Retrieves all nodes from either the confg or operational data store
+  and prints a flow summary to the console. Depending on the print level
+  specified in a command line option, the summary can shows the overall
+  number of flows in the network, the number of flows in each node, or 
+  detailed data for each flow
+
+- flow_config_blaster.py:
+  Adds and deletes ("blasts") flows into ODL's config space. Command line
+  options control the number of "blaster" threads, the number of blast cycles,
+  the number of flows blasted in each cycle by each thread, etc. 
+  flow_config_blaster.py provides the FlowConfigBlaster class that is reusable 
+  in other tests, such as in flow_add_delete_test.py
+
+- config_cleanup.py:
+  Cleans up the config data store by deleting the entire inventory.
+
+- flow_add_delete_test.py:
+  Adds/deletes ("blasts") flows into ODL's config space. Similar to the 
+  flow_config_blaster (in fact, flow_config_blaster is used in this test),
+  but has more advanced handling of the add/delete cycles. The test executes
+  in three steps:
+  1. The specified number of flows is added in the 'add cycle' (uses
+     flow_config_blaster to blast flows)
+  2. The network is polled for flow statistics statistics from the network 
+     (using the inventory_crawler) to make sure that all flows have been 
+     properly programmed into the network and stats can properly read them
+  3. The flows are deleted in the flow cycle (either in 'bulk' using the 
+     config_cleanup script or one by one using the flow_config_blaster) 
+
+
+
+The Inventory Crawler:
+======================
+To see the command line options, type:
+> ./inventory_cralwer --help
+
+usage: inventory_crawler.py [-h] [--odlhost ODLHOST] [--odlport ODLPORT]
+                            [--plevel PLEVEL]
+                            [--datastore {operational,config}] [--no-auth]
+                            [--auth] [--debug]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --odlhost ODLHOST     host where odl controller is running (default is
+                        127.0.0.1)
+  --odlport ODLPORT     port on which odl's RESTCONF is listening (default is
+                        8181)
+  --plevel PLEVEL       Print Level: 0 - Summary (stats only); 1 - Node names;
+                        2 - Node details;3 - Flow details
+  --datastore {operational,config}
+                        Which data store to crawl; default operational
+  --no-auth             Do not use authenticated access to REST (default)
+  --auth                Use authenticated access to REST (username: 'admin',
+                        password: 'admin').
+  --debug               List nodes that have not provided proper statistics
+                        data
+
+
+
+The Flow Config Blaster:
+========================
+To see the command line options, type:
+  > ./flow_config_blaster.py --help
+
+usage: flow_config_blaster.py [-h] [--host HOST] [--port PORT] [--flows FLOWS]
+                              [--cycles CYCLES] [--threads THREADS]
+                              [--nodes NODES] [--delay DELAY] [--delete]
+                              [--no-delete] [--no-auth] [--auth]
+                              [--startflow STARTFLOW]
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --host HOST           Host where odl controller is running (default is
+                        127.0.0.1)
+  --port PORT           Port on which odl's RESTCONF is listening (default is
+                        8181)
+  --flows FLOWS         Number of flow add/delete requests to send in each
+                        cycle; default 10
+  --cycles CYCLES       Number of flow add/delete cycles to send in each
+                        thread; default 1
+  --threads THREADS     Number of request worker threads, default=1. Each
+                        thread will add/delete nflows.
+  --nodes NODES         Number of nodes if mininet is not connected;
+                        default=16. If mininet is connected, flows will be
+                        evenly distributed (programmed) into connected nodes.
+  --delay DELAY         Time to wait between the add and delete cycles;
+                        default=0
+  --delete              Delete all added flows one by one, benchmark delete
+                        performance.
+  --no-delete           Do not perform the delete cycle.
+  --no-auth             Do not use authenticated access to REST (default)
+  --auth                Use authenticated access to REST (username: 'admin',
+                        password: 'admin').
+  --startflow STARTFLOW
+                        The starting Flow ID; default=0
+
+The 'startflow' command line parameter is used with multiple 
+flow_config_blasters blasting flows at the same ODL instance. With Python's
+GIL any given blastr can not use more than one CPU even when multiple blaster 
+threads are specified. Therefore, multiple blaster processes must be used to
+test ODL's preformance limits. The 'startflow' parameter gives each blaster 
+process its own flow id space so that each injects unique flows into ODL's
+config data store.
+
+ 
+
+The Config Cleanup
+==================
+To see the command line options, type:
+  > ./config_cleanup.py --help
+
+usage: config_cleanup.py [-h] [--odlhost ODLHOST] [--odlport ODLPORT]
+                         [--no-auth] [--auth]
+
+Cleans up the config space
+
+optional arguments:
+  -h, --help         show this help message and exit
+  --odlhost ODLHOST  host where odl controller is running (default is
+                     127.0.0.1)
+  --odlport ODLPORT  port on which odl's RESTCONF is listening (default is
+                     8181)
+  --no-auth          Do not use authenticated access to REST (default)
+  --auth             Use authenticated access to REST (username: 'admin',
+                     password: 'admin').
+
+
+
+The Flow Add/Delete Test
+========================
+To see the command line options, type:
+  >./flow_add_delete_test.py --help
+
+usage: flow_add_delete_test.py [-h] [--host HOST] [--port PORT]
+                               [--flows FLOWS] [--cycles CYCLES]
+                               [--threads THREADS] [--nodes NODES]
+                               [--delay DELAY] [--timeout TIMEOUT] [--delete]
+                               [--bulk-delete] [--auth]
+                               [--startflow STARTFLOW]
+
+Flow programming performance test: First adds and then deletes flows into the
+config tree, as specified by optional parameters.
+
+optional arguments:
+  -h, --help            show this help message and exit
+  --host HOST           Host where odl controller is running (default is
+                        127.0.0.1)
+  --port PORT           Port on which odl's RESTCONF is listening (default is
+                        8181)
+  --flows FLOWS         Number of flow add/delete requests to send in each
+                        cycle; default 10
+  --cycles CYCLES       Number of flow add/delete cycles to send in each
+                        thread; default 1
+  --threads THREADS     Number of request worker threads, default=1. Each
+                        thread will add/delete nflows.
+  --nodes NODES         Number of nodes if mininet is not connected;
+                        default=16. If mininet is connected, flows will be
+                        evenly distributed (programmed) into connected nodes.
+  --delay DELAY         Time to wait between the add and delete cycles;
+                        default=0
+  --timeout TIMEOUT     The maximum time to wait between the add and delete
+                        cycles; default=100
+  --delete              Delete all added flows one by one, benchmark delete
+                        performance.
+  --bulk-delete         Delete all flows in bulk; default=False
+  --auth                Use authenticated access to REST (username: 'admin',
+                        password: 'admin'); default=False
+  --startflow STARTFLOW
+                        The starting Flow ID; default=0