simulators/workload_generator/README.md

   1 # ======================================================================
   2 #         Copyright (c) 2019 Nokia
   3 #         Copyright (c) 2018-2019 AT&T Intellectual Property.
   4
   5 #    Licensed under the Apache License, Version 2.0 (the "License");
   6 #    you may not use this file except in compliance with the License.
   7 #    You may obtain a copy of the License at
   8
   9 #        http://www.apache.org/licenses/LICENSE-2.0
  10
  11 #    Unless required by applicable law or agreed to in writing, software
  12 #    distributed under the License is distributed on an "AS IS" BASIS,
  13 #    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
  14 #    implied. See the License for the specific language governing
  15 #    permissions andlimitations under the License.
  16 # ======================================================================
  17
  18 RIC workload_generator is a tool to test the performanc of xAPPs in RIC. It works by generating PDU messages at a specified rate, receiving the reply messages and caculating performance counters including but not limited to latency and throughput. RIC workload_generator currently consists of two applications: ric_generator and ric_receiver.
  19
  20 ric_generator sends PDU messages to the xAPP. ric_receiver receives messages and computes performance counters.
  21
  22 workload_generator test setup
  23 ============================================
  24
  25                      -------------           -----------
  26                     |     RIC     |  t1     |           |<-- -      t1: sending time
  27                     |  generator  |---->----|           |---> |     t2: receiving time
  28                     |             |         |           |   | |     latency = t2 - t1
  29                     |             |         |    xAPP   |   v ^
  30                     |             |         |           |   | |
  31                     |     RIC     |----<----|           |<--  |
  32                     |   receiver  |  t2     |           |----->
  33                     |             |         |           |
  34                      -------------           -----------
  35
  36
  37 workload_generator directory structure
  38 ==============================================
  39 ric_receiver: receiver executable
  40 ric_generator: generator executable
  41 run.sh: script to run workload_generator
  42 back2back_test.sh: script to run workload_generator in back2back test mode (i.e generator is connected directly to receiver)
  43 Makefile: Makefile to build the source
  44 src: source code
  45 report: detailed report generated after each run
  46 PDU: example PDU files (.per)
  47 seed.rt: RMR routing table
  48 test.srt: RMR routing table for back to back testing
  49
  50 Build workload_generator using
  51 =================================
  52 1. Install RMR
  53
  54 2. after checking out workload_generator in directory (for example at /opt/workload_generator, and this readme will use this directory afterwards) do following
  55 1) cd /opt/workload_generator
  56 2) make
  57
  58 Configuration
  59 ===============================
  60 1. Configure seed.rt on the workload generator machine.
  61
  62 workload_generator can run on baremetal servers, VMs and containers.
  63
  64 workload_generator is built upon RMR. It reads the seed.rt file to figure out the destination of messages based on message types. Currently workload_generator only supports two message types numbered as 0 and 1, so in seed.rt you need to specify the destination IP address of the xAPP. For instance if your xAPP's ip address and port number are IP1:PORT1, the seed.rt would look like
  65 "
  66 newrt|start
  67      rte|0|IP1:PORT1
  68      rte|1|IP1:PORT1
  69 newrt|end
  70 "
  71
  72
  73 2. Configure RMR routing information on the xAPP machine.
  74
  75 RIC xAPP which is built upon RMR can work with workload_generator. It requires that xAPP should know how to send the message back to the receiver. That means the routing table, either statical like seed.rt or dynamic using rt service (please refer to RMR Manual if you need to know more about rt service) should include a route entry for reply message. For example, if the reply message has a type number 3 and the address of the workload_generator is IP2:PORT2. The routing table on xAPP machine (say it is named as xAPP_seed.rt) may look like
  76
  77 "
  78 newrt|start
  79      rte|3|IP2:PORT2
  80 newrt|end
  81 "
  82
  83 3. Setup PDU files
  84
  85 You can put up to 2 PDU files in the PDU directory. By default, the workload generator reads pdu1.per and pdu2.per in this directory.
  86
  87 Execution
  88 =========================
  89
  90 1. run back to back test
  91 /opt/workload_generator/back2back_test.sh
  92
  93 2. run xAPP test
  94 /opt/workload_generator/run.sh [rate]
  95
  96 workload_generator stops automatically, after sending 1000 messages.
  97 A report will be generated as /opt/workload_generator/report/xAPP_counters.csv
  98
  99 Uninstall workload_generator
 100 =========================
 101 cd /opt/workload_generator
 102 make clean