Add IPSec tests
[csit.git] / resources / tools / presentation / doc / pal_lld.rst
index 027d6b3..81c2547 100644 (file)
@@ -840,6 +840,35 @@ latency in a box chart):
         width: 700
         height: 1000
 
+The structure of the section "Plot" is as follows (example of a plot showing
+VPP HTTP server performance in a box chart with pre-defined data
+"plot-vpp-httlp-server-performance" set and  plot layout "plot-cps"):
+
+::
+
+    -
+      type: "plot"
+      title: "VPP HTTP Server Performance"
+      algorithm: "plot_http_server_performance_box"
+      output-file-type: ".html"
+      output-file: "{DIR[STATIC,VPP]}/http-server-performance-cps"
+      data:
+        "plot-vpp-httlp-server-performance"
+      # Keep this formatting, the filter is enclosed with " (quotation mark) and
+      # each tag is enclosed with ' (apostrophe).
+      filter: "'HTTP' and 'TCP_CPS'"
+      parameters:
+      - "result"
+      - "name"
+      traces:
+        hoverinfo: "x+y"
+        boxpoints: "outliers"
+        whiskerwidth: 0
+      layout:
+        title: "VPP HTTP Server Performance"
+        layout:
+          "plot-cps"
+
 
 Section: file
 '''''''''''''
@@ -1109,8 +1138,9 @@ For example, the element which specification includes:
     filter:
       - "'64B' and 'BASE' and 'NDRDISC' and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
 
-will be constructed using data from the job "csit-vpp-perf-1707-all", for all listed
-builds and the tests with the list of tags matching the filter conditions.
+will be constructed using data from the job "csit-vpp-perf-1707-all", for all
+listed builds and the tests with the list of tags matching the filter
+conditions.
 
 The output data structure for filtered test data is:
 
@@ -1189,6 +1219,83 @@ Subset of existing performance tests is covered by TSA graphs.
           "plot-throughput-speedup-analysis"
 
 
+Comparison of results from two sets of the same test executions
+'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+This algorithm enables comparison of results coming from two sets of the
+same test executions. It is used to quantify performance changes across
+all tests after test environment changes e.g. Operating System
+upgrades/patches, Hardware changes.
+
+It is assumed that each set of test executions includes multiple runs
+of the same tests, 10 or more, to verify test results repeatibility and
+to yield statistically meaningful results data.
+
+Comparison results are presented in a table with a specified number of
+the best and the worst relative changes between the two sets. Following table
+columns are defined:
+
+    - name of the test;
+    - throughput mean values of the reference set;
+    - throughput standard deviation  of the reference set;
+    - throughput mean values of the set to compare;
+    - throughput standard deviation  of the set to compare;
+    - relative change of the mean values.
+
+**The model**
+
+The model specifies:
+
+    - type: "table" - means this section defines a table.
+    - title: Title of the table.
+    - algorithm: Algorithm which is used to generate the table. The other
+      parameters in this section must provide all information needed by the used
+      algorithm.
+    - output-file-ext: Extension of the output file.
+    - output-file: File which the table will be written to.
+    - reference - the builds which are used as the reference for comparison.
+    - compare - the builds which are compared to the reference.
+    - data: Specify the sources, jobs and builds, providing data for generating
+      the table.
+    - filter: Filter based on tags applied on the input data, if "template" is
+      used, filtering is based on the template.
+    - parameters: Only these parameters will be put to the output data
+      structure.
+    - nr-of-tests-shown: Number of the best and the worst tests presented in the
+      table. Use 0 (zero) to present all tests.
+
+*Example:*
+
+::
+
+    -
+      type: "table"
+      title: "Performance comparison"
+      algorithm: "table_performance_comparison"
+      output-file-ext: ".csv"
+      output-file: "{DIR[DTR,PERF,VPP,IMPRV]}/vpp_performance_comparison"
+      reference:
+        title: "csit-vpp-perf-1801-all - 1"
+        data:
+          csit-vpp-perf-1801-all:
+          - 1
+          - 2
+      compare:
+        title: "csit-vpp-perf-1801-all - 2"
+        data:
+          csit-vpp-perf-1801-all:
+          - 1
+          - 2
+      data:
+        "vpp-perf-comparison"
+      filter: "all"
+      parameters:
+      - "name"
+      - "parent"
+      - "throughput"
+      nr-of-tests-shown: 20
+
+
 Advanced data analytics
 ```````````````````````
 
@@ -1216,7 +1323,8 @@ Tables
  - tables are generated by algorithms implemented in PAL, the model includes the
    algorithm and all necessary information.
  - output format: csv
- - generated tables are stored in specified directories and linked to .rst files.
+ - generated tables are stored in specified directories and linked to .rst
+   files.
 
 
 Plots
@@ -1232,8 +1340,8 @@ Report generation
 -----------------
 
 Report is generated using Sphinx and Read_the_Docs template. PAL generates html
-and pdf formats. It is possible to define the content of the report by specifying
-the version (TODO: define the names and content of versions).
+and pdf formats. It is possible to define the content of the report by
+specifying the version (TODO: define the names and content of versions).
 
 
 The process
@@ -1251,13 +1359,121 @@ The process
 5. Generate the report.
 6. Store the report (Nexus).
 
-The process is model driven. The elements’ models (tables, plots, files and
-report itself) are defined in the specification file. Script reads the elements’
-models from specification file and generates the elements.
+The process is model driven. The elements' models (tables, plots, files
+and report itself) are defined in the specification file. Script reads
+the elements' models from specification file and generates the elements.
+
+It is easy to add elements to be generated in the report. If a new type
+of an element is required, only a new algorithm needs to be implemented
+and integrated.
+
+
+Continuous Performance Measurements and Trending
+------------------------------------------------
+
+Performance analysis and trending execution sequence:
+`````````````````````````````````````````````````````
+
+CSIT PA runs performance analysis, change detection and trending using specified
+trend analysis metrics over the rolling window of last <N> sets of historical
+measurement data. PA is defined as follows:
+
+    #. PA job triggers:
+
+        #. By PT job at its completion.
+        #. Manually from Jenkins UI.
+
+    #. Download and parse archived historical data and the new data:
+
+        #. New data from latest PT job is evaluated against the rolling window
+           of <N> sets of historical data.
+        #. Download RF output.xml files and compressed archived data.
+        #. Parse out the data filtering test cases listed in PA specification
+           (part of CSIT PAL specification file).
+
+    #. Calculate trend metrics for the rolling window of <N> sets of historical data:
+
+        #. Calculate quartiles Q1, Q2, Q3.
+        #. Trim outliers using IQR.
+        #. Calculate TMA and TMSD.
+        #. Calculate normal trending range per test case based on TMA and TMSD.
+
+    #. Evaluate new test data against trend metrics:
 
-It is easy to add elements to be generated, if a new kind of element is
-required, only a new algorithm is implemented and integrated.
+        #. If within the range of (TMA +/- 3*TMSD) => Result = Pass,
+           Reason = Normal.
+        #. If below the range => Result = Fail, Reason = Regression.
+        #. If above the range => Result = Pass, Reason = Progression.
 
+    #. Generate and publish results
+
+        #. Relay evaluation result to job result.
+        #. Generate a new set of trend analysis summary graphs and drill-down
+           graphs.
+
+            #. Summary graphs to include measured values with Normal,
+               Progression and Regression markers. MM shown in the background if
+               possible.
+            #. Drill-down graphs to include MM, TMA and TMSD.
+
+        #. Publish trend analysis graphs in html format on
+           https://docs.fd.io/csit/master/trending/.
+
+
+Parameters to specify:
+``````````````````````
+
+- job to be monitored - the Jenkins job which results are used as input data for
+  this test;
+- builds used for trending plot(s) - specified by a list of build numbers or by
+  a range of builds defined by the first and the last buld number;
+- list plots to generate:
+
+  - plot title;
+  - output file name;
+  - data for plots;
+  - tests to be displayed in the plot defined by a filter;
+  - list of parameters to extract from the data;
+  - periods (daily = 1, weekly = 5, monthly = 30);
+  - plot layout
+
+*Example:*
+
+::
+
+    -
+      type: "cpta"
+      title: "Continuous Performance Trending and Analysis"
+      algorithm: "cpta"
+      output-file-type: ".html"
+      output-file: "{DIR[STATIC,VPP]}/cpta"
+      data: "plot-performance-trending"
+      plots:
+        - title: "VPP 1T1C L2 64B Packet Throughput - {period} Trending"
+          output-file-name: "l2-1t1c-x520"
+          data: "plot-performance-trending"
+          filter: "'NIC_Intel-X520-DA2' and 'MRR' and '64B' and ('BASE' or 'SCALE') and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST' and not 'MEMIF'"
+          parameters:
+          - "result"
+    #      - "name"
+          periods:
+          - 1
+          - 5
+          - 30
+          layout: "plot-cpta"
+
+        - title: "VPP 2T2C L2 64B Packet Throughput - {period} Trending"
+          output-file-name: "l2-2t2c-x520"
+          data: "plot-performance-trending"
+          filter: "'NIC_Intel-X520-DA2' and 'MRR' and '64B' and ('BASE' or 'SCALE') and '2T2C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST' and not 'MEMIF'"
+          parameters:
+          - "result"
+    #      - "name"
+          periods:
+          - 1
+          - 5
+          - 30
+          layout: "plot-cpta"
 
 API
 ---
@@ -1396,12 +1612,12 @@ PAL functional diagram
 How to add an element
 `````````````````````
 
-Element can be added by adding its model to the specification file. If the
-element will be generated by an existing algorithm, only its parameters must be
-set.
+Element can be added by adding it's model to the specification file. If
+the element is to be generated by an existing algorithm, only it's
+parameters must be set.
 
-If a brand new type of element will be added, also the algorithm must be
-implemented.
-The algorithms are implemented in the files which names start with "generator".
-The name of the function implementing the algorithm and the name of algorithm in
-the specification file had to be the same.
+If a brand new type of element needs to be added, also the algorithm
+must be implemented. Element generation algorithms are implemented in
+the files with names starting with "generator" prefix. The name of the
+function implementing the algorithm and the name of algorithm in the
+specification file have to be the same.