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