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/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 testy
 128 ^^^^^
 129 In the testy sections, where y denotes the index of the test, the test that will
 130 be executed on the machines that were specified in the TestMx sections, will be
 131 described. Using Xtesting, we will typically only use 1 test.
 132 Parameter test is defining which test needs to be run. This is a hardcoded
 133 string and can only be one of the following ['flowsizetest', 'TST009test',
 134 'fixed_rate', 'increment_till_fail', 'corestats', 'portstats', 'impairtest',
 135 'irqtest', 'warmuptest']. In this project, we will use the TST009test testing.
 136 For examples of the other tests, please check out the other test files in
 137 rapid_location_.
 138
 139 The pass_threshold parameter defines the success criterium for the test. When
 140 this test uses multiple combinations of packet size and flows, all combinations
 141 must be meeting the same threshold. If one of the combinations fails, the test
 142 will be reported as failed.
 143 The threshold is expressed in Mpps.
 144
 145 The imixs parameter defines the pakcet sizes that will be used. Each element in
 146 the imixs list will result in a separate test. Each element is on its turn a
 147 list of packet sizes which will be used during one test execution. If you only
 148 want to test 1 imix size, define imixs with only one element. For each element in
 149 the imixs list, the generator will iterate over the packet lengths and send them
 150 out in the order as specified in the list. An example of an imix list is [128,
 151 256, 64, 64, 128]. In this case, 40% of the packets will have a size of 64
 152 bytes, 40% will have a packet size of 128 and 20% will have a packet size of
 153 256. When using this with Xtesting, we will typically only use 1 imix. When
 154 needing results for more sizes, one should create a specific test file per size
 155 and launch the different tests using Xtesting.
 156
 157 The flows parameter is a list of flow sizes. For each flow size, a test will be
 158 run with the specified amount of flows. The flow size needs to be a power of 2,
 159 max 2^30. If not a power of 2, we will use the lowest power of 2 that is larger
 160 than the requested number of flows. e.g. 9 will result in 16 flows.
 161 Same remark as for the imixs parameter: we will only use one element in the
 162 flows list. When more flows need to be tested, create a different test file and
 163 launch it using Xtesting.
 164
 165 The drop_rate_threshold parameter specifies the maximum ratio of packets than
 166 can be dropped while still considering
 167 the test run as succesful. Note that a value of 0 means an absolute zero packet
 168 loss: even if we lose 1 packet during a certain step in a test run, it will be
 169 marked as failed.
 170
 171 The lat_avg_threshold, lat_perc_threshold, lat_max_threshold parameters
 172 are thresholds to define
 173 the maximal acceptable round trip latency to mark the test step as successful.
 174 You can set this threshold for the average, the percentile and the maximum
 175 latency. Which percentile is being used is defined in the TestParameters section.
 176 All these thresholds are expressed in micro-seconds. You can also put the value
 177 to inf, which means the threshold will never be reached and hence the threshold
 178 value is not being used to define if the run is successful or not.
 179
 180 The MAXr, MAXz, MAXFramesPerSecondAllIngress and StepSize parameters are defined in
 181 NFV-TST009_ and are used to control the binary search algorithm.
 182
 183 The ramp_step variable controls the ramping of the generated traffic. When
 184 not specified, the requested traffic for each step in the testing will be
 185 applied immediately. If specified, the generator will slowly go to the requested
 186 speed by increasing the traffic each second with the value specified in this
 187 parameter till it reaches the requested speed. This parameter is expressed in
 188 100Mb/s.
 189
 190 .. code-block:: console
 191
 192      pass_threshold=0.001
 193      imixs=[[128, 256, 64, 64, 128]]
 194      flows=[64]
 195      drop_rate_threshold = 0
 196      lat_avg_threshold = inf
 197      lat_perc_threshold = inf
 198      lat_max_threshold = inf
 199      MAXr = 3
 200      MAXz = 5000
 201      MAXFramesPerSecondAllIngress = 12000000
 202      StepSize = 10000
 203      #ramp_step = 1
 204
 205 Modifying the test
 206 ------------------
 207 In case you want to modify the parameters as specified in
 208 TST009_Throughput_64B_64F.test_, it is best to create your own test file. Your
 209 test file will need to be uploaded to the test container. Hence you will have to
 210 rebuild your container, and add an extra copy command to the Dockerfile so that
 211 your new test file will be avaialble in the container.
 212 Then you will need to modify the testcases.yaml file. One of the args that you
 213 can specify is the test_file. Put your newly created test file as the new value
 214 for this argument.
 215 Now build and publish your test container as specified in steps 5 & 6 of the
 216 installation procedure.
 217
 218 Note that other arguments than test_file can be specified in testcases.yaml. For
 219 a list of arugments, please check out the test_params dictionary in the
 220 rapid_defaults.py that you can find in rapid_location_.
 221 It is adviced not to change these parameters unless you have an in-depth
 222 knowledge of the code.
 223 The only 2 arguments that van be changed are the test_file which was already
 224 discussed and the runtime argument. This argument defines how long each test run
 225 will take and is expressed in seconds.