docs/testing/user/userguide/04-running_the_test.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International
   2 .. License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. (c) OPNFV, Intel Corporation and others.
   5
   6 ================
   7 Running the test
   8 ================
   9 .. _NFV-TST009: https://docbox.etsi.org/ISG/NFV/open/Publications_pdf/Specs-Reports/NFV-TST%20009v3.2.1%20-%20GS%20-%20NFVI_Benchmarks.pdf
  10 .. _TST009_Throughput_64B_64F.test: https://github.com/opnfv/samplevnf/blob/master/VNFs/DPPD-PROX/helper-scripts/rapid/tests/TST009_Throughput_64B_64F.test
  11 .. _rapid_location: https://github.com/opnfv/samplevnf/blob/master/VNFs/DPPD-PROX/helper-scripts/rapid/
  12
  13 Overview
  14 --------
  15 A default test will be run automatically when you launch the testing. The
  16 details and definition of that test are defined in file
  17 TST009_Throughput_64B_64F.test_.
  18
  19 We will discuss the sections of such a test file and how this can be changed to
  20 accomodate the testing you want to execute. This will be done by creating your
  21 own test file and making sure it becomes part of your testcases.yaml, as will
  22 be shown below.
  23
  24 As the name of the default test file suggests, the test will find the
  25 throughput, latency and packet loss according to NFV-TST009_, for packets that
  26 are 64 bytes long and for 64 different flows.
  27
  28 Test File Description
  29 ---------------------
  30 The test file has multiple sections. The first section is a generic section
  31 called TestParameters. Then there are 1 or more sections desribing the test
  32 machines we will be using in the test. The sections are named TestMx, where x
  33 is a number (starting with 1). The tests to be executed are described in a
  34 section called testy, where y is the number of the test to be executed,
  35 starting with 1. In this automated testing driven by Xtesting, we will
  36 typically only run 1 test.
  37
  38 TestParameters
  39 ^^^^^^^^^^^^^^
  40 In this section, the name of the test is specified. This is only used in the
  41 reporting and has no influence on the actual testing.
  42
  43 .. code-block:: console
  44
  45      name = Rapid_ETSINFV_TST009
  46
  47 The number of test that will be executed by this run and that will be described
  48 in the [testy] sections, is defined by the number_of_tests parameter. In the
  49 Xtesting framework that we are using here, this will typically be set to 1.
  50
  51 .. code-block:: console
  52
  53      number_of_tests = 1
  54
  55 The total number of machines to be used in this testing will be defined by the
  56 parameter total_number_of_test_machines. The function that these machines have
  57 in this test will be described in the [TestMx] section. Typically, this number
  58 will be set to 2, but many more machines can particiapte in a test.
  59
  60 .. code-block:: console
  61
  62      total_number_of_test_machines = 2
  63
  64 lat_percentile is a variable that is setting which percentile to use during the
  65 course of this test. This will be used to report the percentile round trip
  66 latency and is a better measurement for the high latencies during this test than
  67 the maximum latency which will also be reported. Note that we also report the
  68 total round trip latency histogram.
  69
  70 .. code-block:: console
  71
  72      lat_percentile = 99
  73
  74
  75 TestMx
  76 ^^^^^^
  77 In the TestMx sections, where x denotes the index of the machine, the function
  78 of the machine in the testing, will be described. The machine can be defined as
  79 a generator, or as a packet reflector (swap function). The machines can be any
  80 machine that is created upfront (See step 3 of the installation steps). Other
  81 functions can also be executed by the test machines and examples of test files
  82 can be found in rapid_location_.
  83
  84 The first parameter is the name of the machine and is only used for referencing
  85 the machine. This will be the name of the PROX instance and will be shown in
  86 case you run the PROX UI. In this automated testing, this will be not be
  87 visible.
  88
  89 The config_file parameter defines which PROX config file is used by the PROX
  90 program and what PROX will be
  91 doing. For a generator, this will typically be gen.cfg. Multiple cfg files
  92 exist in the rapid_location_.
  93
  94 The dest_vm parameter is used by a generator to find out to
  95 which VM he needs to send the packets. In the example below, the packets will be
  96 sent to TestM2.
  97
  98 The gencores parameter defines a list of cores to be used for the generator tasks.
  99 Note that if you specify more than 1 core, the interface will need to support as
 100 many tx queues as there are generator cores.
 101
 102 The latcores parameter specifies a
 103 list of cores to be used by the latency measurement tasks. You need as many rx
 104 queues on the interface as specified in the latcores parameter.
 105
 106 The default value for the
 107 bucket_size_exp parameter is 12. It is also its minimum value. In case most of
 108 the latency measurements in the histogram are falling in the last bucket, this
 109 number needs to be increased. Every time you increase this number by 1, the
 110 bucket size for the latency histogram is multiplied by 2. There are 128 buckets
 111 in the histogram.
 112
 113 cores is a parameter that will be used by non-generator configurations that
 114 don't need a disctinction between generator and latency cores (e.g. swap.cfg).
 115
 116 Changing these parameters requires in depth knowledge of the PROX tool and is
 117 not something to start with.
 118
 119 .. code-block:: console
 120
 121      name = Generator
 122      config_file = gen.cfg
 123      dest_vm = 2
 124      gencores = [1]
 125      latcores = [3]
 126      #bucket_size_exp = 12
 127
 128 testy
 129 ^^^^^
 130 In the testy sections, where y denotes the index of the test, the test that will
 131 be executed on the machines that were specified in the TestMx sections, will be
 132 described. Using Xtesting, we will typically only use 1 test.
 133 Parameter test is defining which test needs to be run. This is a hardcoded
 134 string and can only be one of the following ['flowsizetest', 'TST009test',
 135 'fixed_rate', 'increment_till_fail', 'corestats', 'portstats', 'impairtest',
 136 'irqtest', 'warmuptest']. In this project, we will use the TST009test testing.
 137 For examples of the other tests, please check out the other test files in
 138 rapid_location_.
 139
 140 The pass_threshold parameter defines the success criterium for the test. When
 141 this test uses multiple combinations of packet size and flows, all combinations
 142 must be meeting the same threshold. If one of the combinations fails, the test
 143 will be reported as failed.
 144 The threshold is expressed in Mpps.
 145
 146 The imixs parameter defines the pakcet sizes that will be used. Each element in
 147 the imixs list will result in a separate test. Each element is on its turn a
 148 list of packet sizes which will be used during one test execution. If you only
 149 want to test 1 imix size, define imixs with only one element. For each element in
 150 the imixs list, the generator will iterate over the packet lengths and send them
 151 out in the order as specified in the list. An example of an imix list is [128,
 152 256, 64, 64, 128]. In this case, 40% of the packets will have a size of 64
 153 bytes, 40% will have a packet size of 128 and 20% will have a packet size of
 154 256. When using this with Xtesting, we will typically only use 1 imix. When
 155 needing results for more sizes, one should create a specific test file per size
 156 and launch the different tests using Xtesting.
 157
 158 The flows parameter is a list of flow sizes. For each flow size, a test will be
 159 run with the specified amount of flows. The flow size needs to be a power of 2,
 160 max 2^30. If not a power of 2, we will use the lowest power of 2 that is larger
 161 than the requested number of flows. e.g. 9 will result in 16 flows.
 162 Same remark as for the imixs parameter: we will only use one element in the
 163 flows list. When more flows need to be tested, create a different test file and
 164 launch it using Xtesting.
 165
 166 The drop_rate_threshold parameter specifies the maximum ratio of packets than
 167 can be dropped while still considering
 168 the test run as succesful. Note that a value of 0 means an absolute zero packet
 169 loss: even if we lose 1 packet during a certain step in a test run, it will be
 170 marked as failed.
 171
 172 The lat_avg_threshold, lat_perc_threshold, lat_max_threshold parameters
 173 are thresholds to define
 174 the maximal acceptable round trip latency to mark the test step as successful.
 175 You can set this threshold for the average, the percentile and the maximum
 176 latency. Which percentile is being used is defined in the TestParameters section.
 177 All these thresholds are expressed in micro-seconds. You can also put the value
 178 to inf, which means the threshold will never be reached and hence the threshold
 179 value is not being used to define if the run is successful or not.
 180
 181 The MAXr, MAXz, MAXFramesPerSecondAllIngress and StepSize parameters are defined in
 182 NFV-TST009_ and are used to control the binary search algorithm.
 183
 184 The ramp_step variable controls the ramping of the generated traffic. When
 185 not specified, the requested traffic for each step in the testing will be
 186 applied immediately. If specified, the generator will slowly go to the requested
 187 speed by increasing the traffic each second with the value specified in this
 188 parameter till it reaches the requested speed. This parameter is expressed in
 189 100Mb/s.
 190
 191 .. code-block:: console
 192
 193      pass_threshold=0.001
 194      imixs=[[128, 256, 64, 64, 128]]
 195      flows=[64]
 196      drop_rate_threshold = 0
 197      lat_avg_threshold = inf
 198      lat_perc_threshold = inf
 199      lat_max_threshold = inf
 200      MAXr = 3
 201      MAXz = 5000
 202      MAXFramesPerSecondAllIngress = 12000000
 203      StepSize = 10000
 204      #ramp_step = 1
 205
 206 Modifying the test
 207 ------------------
 208 In case you want to modify the parameters as specified in
 209 TST009_Throughput_64B_64F.test_, it is best to create your own test file. Your
 210 test file will need to be uploaded to the test container. Hence you will have to
 211 rebuild your container, and add an extra copy command to the Dockerfile so that
 212 your new test file will be avaialble in the container.
 213 Then you will need to modify the testcases.yaml file. One of the args that you
 214 can specify is the test_file. Put your newly created test file as the new value
 215 for this argument.
 216 Now build and publish your test container as specified in steps 5 & 6 of the
 217 installation procedure.
 218
 219 Note that other arguments than test_file can be specified in testcases.yaml. For
 220 a list of arugments, please check out the test_params dictionary in the
 221 rapid_defaults.py that you can find in rapid_location_.
 222 It is adviced not to change these parameters unless you have an in-depth
 223 knowledge of the code.
 224 The only 2 arguments that van be changed are the test_file which was already
 225 discussed and the runtime argument. This argument defines how long each test run
 226 will take and is expressed in seconds.