docs/cpta/methodology/perpatch_performance_tests.rst

   1 Per-patch performance tests
   2 ---------------------------
   3
   4 Updated for CSIT git commit id: 72b45cfe662107c8e1bb549df71ba51352a898ee.
   5
   6 A methodology similar to trending analysis is used for comparing performance
   7 before a DUT code change is merged. This can act as a verify job to disallow
   8 changes which would decrease performance without a good reason.
   9
  10 Existing jobs
  11 `````````````
  12
  13 VPP is the only project currently using such jobs.
  14 They are not started automatically, must be triggered on demand.
  15 They allow full tag expressions, but some tags are enforced (such as MRR).
  16
  17 There are jobs available for multiple types of testbeds,
  18 based on various processors.
  19 Their Gerrit triggers words are of the form "perftest-{node_arch}"
  20 where the node_arch combinations currently supported are:
  21 2n-clx, 2n-dnv, 2n-skx, 2n-tx2, 2n-zn2, 3n-dnv, 3n-skx, 3n-tsh.
  22
  23 Test selection
  24 --------------
  25
  26 ..
  27     TODO: Majority of this section is also useful for CSIT verify jobs. Move it somewhere.
  28
  29 Gerrit trigger line without any additional arguments selects
  30 a small set of test cases to run.
  31 If additional arguments are added to the Gerrit trigger, they are treated
  32 as Robot tag expressions to select tests to run.
  33 While very flexible, this method of test selection also allows the user
  34 to accidentally select too high number of tests, blocking the testbed for days.
  35
  36 What follows is a list of explanations and recommendations
  37 to help users to select the minimal set of tests cases.
  38
  39 Verify cycles
  40 _____________
  41
  42 When Gerrit schedules multiple jobs to run for the same patch set,
  43 it waits until all runs are complete.
  44 While it is waiting, it is possible to trigger more jobs
  45 (adding runs to the set Gerrit is waiting for), but it is not possible
  46 to trigger more runs for the same job, until Gerrit is done waiting.
  47 After Gerrit is done waiting, it becames possible to trigger
  48 the same job again.
  49
  50 Example. User triggers one set of tests on 2n-skx and immediately
  51 also triggers other set of tests on 3n-skx. Then the user notices
  52 2n-skx run end early because of a typo in tag expression.
  53 When the user tries to re-trigger 2n-skx (with fixed tag expression),
  54 that comment gets ignored by Jenkins.
  55 Only when 3n-skx job finishes, the user can trigger 2n-skx.
  56
  57 One comment many jobs
  58 _____________________
  59
  60 In the past, the CSIT code which parses for perftest trigger comments
  61 was buggy, which lead to bad behavior (as in selection all performance test,
  62 because "perftest" is also a robot tag) when user included multiple
  63 perftest trigger words in the same comment.
  64
  65 The worst bugs were fixed since then, but it is still recommended
  66 to use just one trigger word per Gerrit comment, just to be safe.
  67
  68 Multiple test cases in run
  69 __________________________
  70
  71 While Robot supports OR operator, it does not support parentheses,
  72 so the OR operator is not very useful. It is recommended
  73 to use space instead of OR operator.
  74
  75 Example template:
  76 perftest-2n-skx {tag_expression_1} {tag_expression_2}
  77
  78 See below for more concrete examples.
  79
  80 Suite tags
  81 __________
  82
  83 Traditionally, CSIT maintains broad Robot tags that can be used to select tests,
  84 for details on existing tags, see
  85 `CSIT Tags <https://github.com/FDio/csit/blob/master/docs/tag_documentation.rst>`_.
  86
  87 But it is not recommended to use them for test selection,
  88 as it is not that easy to determine how many test cases are selected.
  89
  90 The recommended way is to look into CSIT repository first,
  91 and locate a specific suite the user is interested in,
  92 and use its suite tag. For example, "ethip4-ip4base" is a suite tag
  93 selecting just one suite in CSIT git repository,
  94 avoiding all scale, container, and other simialr variants.
  95
  96 Note that CSIT uses "autogen" code generator,
  97 so the robot running in Jenkins has access to more suites
  98 than visible just by looking into CSIT git repository,
  99 so suite tag is not enough to select even the intended suite,
 100 and user still probably wants to narrow down
 101 to a single test case within a suite.
 102
 103 Fully specified tag expressions
 104 _______________________________
 105
 106 Here is one template to select a single test case:
 107 {test_type}AND{nic_model}AND{nic_driver}AND{cores}AND{frame_size}AND{suite_tag}
 108 where the variables are all lower case (so AND operator stands out).
 109
 110 Currently only one test type is supported by the performance comparison jobs:
 111 "mrr".
 112 The nic_driver options depend on nic_model. For Intel cards "drv_avf" (AVF plugin)
 113 and "drv_vfio_pci" (DPDK plugin) are popular, for Mellanox "drv_rdma_core".
 114 Currently, the performance using "drv_af_xdp" is not reliable enough, so do not use it
 115 unless you are specifically testing for AF_XDP.
 116
 117 The most popular nic_model is "nic_intel-xxv710", but that is not available
 118 on all testbed types.
 119 It is safe to use "1c" for cores (unless you are suspection multi-core performance
 120 is affected differently) and "64b" for frame size ("78b" for ip6
 121 and more for dot1q and other encapsulated traffic;
 122 "1518b" is popular for ipsec and other payload-bound tests).
 123
 124 As there are more test cases than CSIT can periodically test,
 125 it is possible to encounter an old test case that currently fails.
 126 To avoid that, you can look at "job spec" files we use for periodic testing,
 127 for example `this one <https://github.com/FDio/csit/blob/master/docs/job_specs/report_iterative/2n-skx/vpp-mrr-00.md>`_.
 128
 129 ..
 130     TODO: Explain why "periodic" job spec link lands at report_iterative.
 131
 132 Shortening triggers
 133 ___________________
 134
 135 Advanced users may use the following tricks to avoid writing long trigger comments.
 136
 137 Robot supports glob matching, which can be used to select multiple suite tags at once.
 138
 139 Not specifying one of 6 parts of the recommended expression pattern
 140 will select all available options. For example not specifying nic_driver
 141 for nic_intel-xxv710 will select all 3 applicable drivers.
 142 You can use NOT operator to reject some options (e.g. NOTdrv_af_xdp),
 143 but beware, with NOT the order matters:
 144 tag1ANDtag2NOTtag3 is not the same as tag1NOTtag3ANDtag2,
 145 the latter is evaluated as tag1AND(NOT(tag3ANDtag2)).
 146
 147 Beware when not specifying nic_model. As a precaution,
 148 CSIT code will insert the defailt NIC model for the tetsbed used.
 149 Example: Specifying drv_rdma_core without specifying nic_model
 150 will fail, as the default nic_model is nic_intel-xxv710
 151 which does not support RDMA core driver.
 152
 153 Complete example
 154 ________________
 155
 156 A user wants to test a VPP change which may affect load balance whith bonding.
 157 Searching tag documentation for "bonding" finds LBOND tag and its variants.
 158 Searching CSIT git repository (directory tests/) finds 8 suite files,
 159 all suited only for 3-node testbeds.
 160 All suites are using vhost, but differ by the forwarding app inside VM
 161 (DPDK or VPP), by the forwarding mode of VPP acting as host level vswitch
 162 (MAC learning or cross connect), and by the number of DUT1-DUT2 links
 163 available (1 or 2).
 164
 165 As not all NICs and testbeds offer enogh ports for 2 parallel DUT-DUT links,
 166 the user looks at `testbed specifications <https://github.com/FDio/csit/tree/master/topologies/available>`_
 167 and finds that only x710 NIC on 3n-skx testbed matches the requirements.
 168 Quick look into the suites confirm the smallest frame size is 64 bytes
 169 (despite DOT1Q robot tag, as the encapsulation does not happen on TG-DUT links).
 170 It is ok to use just 1 physical core, as 3n-skx has hyperthreading enabled,
 171 so VPP vswitch will use 2 worker threads.
 172
 173 The user decides the vswitch forwarding mode is not important
 174 (so choses cross connect as that has less CPU overhead),
 175 but wants to test both NIC drivers (not AF_XDP), both apps in VM,
 176 and both 1 and 2 parallel links.
 177
 178 After shortening, this is the trigger comment fianlly used:
 179 perftest-3n-skx mrrANDnic_intel-x710AND1cAND64bAND?lbvpplacp-dot1q-l2xcbase-eth-2vhostvr1024-1vm*NOTdrv_af_xdp
 180
 181 Basic operation
 182 ```````````````
 183
 184 The job builds VPP .deb packages for both the patch under test
 185 (called "current") and its parent patch (called "parent").
 186
 187 For each test (from a set defined by tag expression),
 188 both builds are subjected to several trial measurements (BMRR).
 189 Measured samples are grouped to "parent" sequence,
 190 followed by "current" sequence. The same Minimal Description Length
 191 algorithm as in trending is used to decide whether it is one big group,
 192 or two smaller gropus. If it is one group, a "normal" result
 193 is declared for the test. If it is two groups, and current average
 194 is less then parent average, the test is declared a regression.
 195 If it is two groups and current average is larger or equal,
 196 the test is declared a progression.
 197
 198 The whole job fails (giving -1) if some trial measurement failed,
 199 or if any test was declared a regression.
 200
 201 Temporary specifics
 202 ```````````````````
 203
 204 The Minimal Description Length analysis is performed by
 205 CSIT code equivalent to jumpavg-0.1.3 library available on PyPI.
 206
 207 In hopes of strengthening of signal (code performance) compared to noise
 208 (all other factors influencing the measured values), several workarounds
 209 are applied.
 210
 211 In contrast to trending, trial duration is set to 10 seconds,
 212 and only 5 samples are measured for each build.
 213 Both parameters are set in ci-management.
 214
 215 This decreases sensitivity to regressions, but also decreases
 216 probability of false positives.
 217
 218 Console output
 219 ``````````````
 220
 221 The following information as visible towards the end of Jenkins console output,
 222 repeated for each analyzed test.
 223
 224 The original 5 values are visible in order they were measured.
 225 The 5 values after processing are also visible in output,
 226 this time sorted by value (so people can see minimum and maximum).
 227
 228 The next output is difference of averages. It is the current average
 229 minus the parent average, expressed as percentage of the parent average.
 230
 231 The next three outputs contain the jumpavg representation
 232 of the two groups and a combined group.
 233 Here, "bits" is the description length; for "current" sequence
 234 it includes effect from "parent" average value
 235 (jumpavg-0.1.3 penalizes sequences with too close averages).
 236
 237 Next, a sentence describing which grouping description is shorter,
 238 and by how much bits.
 239 Finally, the test result classification is visible.
 240
 241 The algorithm does not track test case names,
 242 so test cases are indexed (from 0).