resources/tools/presentation/doc/pal_lld.rst

   1 Presentation and Analytics
   2 ==========================
   3
   4 Overview
   5 --------
   6
   7 The presentation and analytics layer (PAL) is the fourth layer of CSIT
   8 hierarchy. The model of presentation and analytics layer consists of four
   9 sub-layers, bottom up:
  10
  11  - sL1 - Data - input data to be processed:
  12
  13    - Static content - .rst text files, .svg static figures, and other files
  14      stored in the CSIT git repository.
  15    - Data to process - .xml files generated by Jenkins jobs executing tests,
  16      stored as robot results files (output.xml).
  17    - Specification - .yaml file with the models of report elements (tables,
  18      plots, layout, ...) generated by this tool. There is also the configuration
  19      of the tool and the specification of input data (jobs and builds).
  20
  21  - sL2 - Data processing
  22
  23    - The data are read from the specified input files (.xml) and stored as
  24      multi-indexed `pandas.Series <https://pandas.pydata.org/pandas-docs/stable/
  25      generated/pandas.Series.html>`_.
  26    - This layer provides also interface to input data and filtering of the input
  27      data.
  28
  29  - sL3 - Data presentation - This layer generates the elements specified in the
  30    specification file:
  31
  32    - Tables: .csv files linked to static .rst files.
  33    - Plots: .html files generated using plot.ly linked to static .rst files.
  34
  35  - sL4 - Report generation - Sphinx generates required formats and versions:
  36
  37    - formats: html, pdf
  38    - versions: minimal, full (TODO: define the names and scope of versions)
  39
  40 .. only:: latex
  41
  42     .. raw:: latex
  43
  44         \begin{figure}[H]
  45             \centering
  46                 \graphicspath{{../_tmp/src/csit_framework_documentation/}}
  47                 \includegraphics[width=0.90\textwidth]{pal_layers}
  48                 \label{fig:pal_layers}
  49         \end{figure}
  50
  51 .. only:: html
  52
  53     .. figure:: pal_layers.svg
  54         :alt: PAL Layers
  55         :align: center
  56
  57 Data
  58 ----
  59
  60 Report Specification
  61 ````````````````````
  62
  63 The report specification file defines which data is used and which outputs are
  64 generated. It is human readable and structured. It is easy to add / remove /
  65 change items. The specification includes:
  66
  67  - Specification of the environment.
  68  - Configuration of debug mode (optional).
  69  - Specification of input data (jobs, builds, files, ...).
  70  - Specification of the output.
  71  - What and how is generated:
  72    - What: plots, tables.
  73    - How: specification of all properties and parameters.
  74  - .yaml format.
  75
  76 Structure of the specification file
  77 '''''''''''''''''''''''''''''''''''
  78
  79 The specification file is organized as a list of dictionaries distinguished by
  80 the type:
  81
  82 ::
  83
  84     -
  85       type: "environment"
  86     -
  87       type: "configuration"
  88     -
  89       type: "debug"
  90     -
  91       type: "static"
  92     -
  93       type: "input"
  94     -
  95       type: "output"
  96     -
  97       type: "table"
  98     -
  99       type: "plot"
 100     -
 101       type: "file"
 102
 103 Each type represents a section. The sections "environment", "debug", "static",
 104 "input" and "output" are listed only once in the specification; "table", "file"
 105 and "plot" can be there multiple times.
 106
 107 Sections "debug", "table", "file" and "plot" are optional.
 108
 109 Table(s), files(s) and plot(s) are referred as "elements" in this text. It is
 110 possible to define and implement other elements if needed.
 111
 112
 113 Section: Environment
 114 ''''''''''''''''''''
 115
 116 This section has the following parts:
 117
 118  - type: "environment" - says that this is the section "environment".
 119  - configuration - configuration of the PAL.
 120  - paths - paths used by the PAL.
 121  - urls - urls pointing to the data sources.
 122  - make-dirs - a list of the directories to be created by the PAL while
 123    preparing the environment.
 124  - remove-dirs - a list of the directories to be removed while cleaning the
 125    environment.
 126  - build-dirs - a list of the directories where the results are stored.
 127
 128 The structure of the section "Environment" is as follows (example):
 129
 130 ::
 131
 132     -
 133       type: "environment"
 134       configuration:
 135         # Debug mode:
 136         # - Skip:
 137         #   - Download of input data files
 138         # - Do:
 139         #   - Read data from given zip / xml files
 140         #   - Set the configuration as it is done in normal mode
 141         # If the section "type: debug" is missing, CFG[DEBUG] is set to 0.
 142         CFG[DEBUG]: 0
 143
 144       paths:
 145         # Top level directories:
 146         ## Working directory
 147         DIR[WORKING]: "_tmp"
 148         ## Build directories
 149         DIR[BUILD,HTML]: "_build"
 150         DIR[BUILD,LATEX]: "_build_latex"
 151
 152         # Static .rst files
 153         DIR[RST]: "../../../docs/report"
 154
 155         # Working directories
 156         ## Input data files (.zip, .xml)
 157         DIR[WORKING,DATA]: "{DIR[WORKING]}/data"
 158         ## Static source files from git
 159         DIR[WORKING,SRC]: "{DIR[WORKING]}/src"
 160         DIR[WORKING,SRC,STATIC]: "{DIR[WORKING,SRC]}/_static"
 161
 162         # Static html content
 163         DIR[STATIC]: "{DIR[BUILD,HTML]}/_static"
 164         DIR[STATIC,VPP]: "{DIR[STATIC]}/vpp"
 165         DIR[STATIC,DPDK]: "{DIR[STATIC]}/dpdk"
 166         DIR[STATIC,ARCH]: "{DIR[STATIC]}/archive"
 167
 168         # Detailed test results
 169         DIR[DTR]: "{DIR[WORKING,SRC]}/detailed_test_results"
 170         DIR[DTR,PERF,DPDK]: "{DIR[DTR]}/dpdk_performance_results"
 171         DIR[DTR,PERF,VPP]: "{DIR[DTR]}/vpp_performance_results"
 172         DIR[DTR,FUNC,VPP]: "{DIR[DTR]}/vpp_functional_results"
 173         DIR[DTR,PERF,VPP,IMPRV]: "{DIR[WORKING,SRC]}/vpp_performance_tests/performance_improvements"
 174
 175         # Detailed test configurations
 176         DIR[DTC]: "{DIR[WORKING,SRC]}/test_configuration"
 177         DIR[DTC,PERF,VPP]: "{DIR[DTC]}/vpp_performance_configuration"
 178         DIR[DTC,FUNC,VPP]: "{DIR[DTC]}/vpp_functional_configuration"
 179
 180         # Detailed tests operational data
 181         DIR[DTO]: "{DIR[WORKING,SRC]}/test_operational_data"
 182         DIR[DTO,PERF,VPP]: "{DIR[DTO]}/vpp_performance_operational_data"
 183
 184         # .css patch file to fix tables generated by Sphinx
 185         DIR[CSS_PATCH_FILE]: "{DIR[STATIC]}/theme_overrides.css"
 186         DIR[CSS_PATCH_FILE2]: "{DIR[WORKING,SRC,STATIC]}/theme_overrides.css"
 187
 188       urls:
 189         URL[JENKINS,CSIT]: "https://jenkins.fd.io/view/csit/job"
 190         URL[S3_STORAGE,LOG]: "https://logs.nginx.service.consul/vex-yul-rot-jenkins-1"
 191         URL[NEXUS,LOG]: "https://logs.fd.io/production/vex-yul-rot-jenkins-1"
 192         URL[NEXUS,DOC]: "https://docs.fd.io/csit"
 193         DIR[NEXUS,DOC]: "report/_static/archive"
 194
 195       make-dirs:
 196       # List the directories which are created while preparing the environment.
 197       # All directories MUST be defined in "paths" section.
 198       - "DIR[WORKING,DATA]"
 199       - "DIR[STATIC,VPP]"
 200       - "DIR[STATIC,DPDK]"
 201       - "DIR[STATIC,ARCH]"
 202       - "DIR[BUILD,LATEX]"
 203       - "DIR[WORKING,SRC]"
 204       - "DIR[WORKING,SRC,STATIC]"
 205
 206       remove-dirs:
 207       # List the directories which are deleted while cleaning the environment.
 208       # All directories MUST be defined in "paths" section.
 209       #- "DIR[BUILD,HTML]"
 210
 211       build-dirs:
 212       # List the directories where the results (build) is stored.
 213       # All directories MUST be defined in "paths" section.
 214       - "DIR[BUILD,HTML]"
 215       - "DIR[BUILD,LATEX]"
 216
 217 It is possible to use defined items in the definition of other items, e.g.:
 218
 219 ::
 220
 221     DIR[WORKING,DATA]: "{DIR[WORKING]}/data"
 222
 223 will be automatically changed to
 224
 225 ::
 226
 227     DIR[WORKING,DATA]: "_tmp/data"
 228
 229
 230 Section: Configuration
 231 ''''''''''''''''''''''
 232
 233 This section specifies the groups of parameters which are repeatedly used in the
 234 elements defined later in the specification file. It has the following parts:
 235
 236  - data sets - Specification of data sets used later in element's specifications
 237    to define the input data.
 238  - plot layouts - Specification of plot layouts used later in plots'
 239    specifications to define the plot layout.
 240
 241 The structure of the section "Configuration" is as follows (example):
 242
 243 ::
 244
 245     -
 246       type: "configuration"
 247       data-sets:
 248         plot-vpp-throughput-latency:
 249           csit-vpp-perf-1710-all:
 250           - 11
 251           - 12
 252           - 13
 253           - 14
 254           - 15
 255           - 16
 256           - 17
 257           - 18
 258           - 19
 259           - 20
 260         vpp-perf-results:
 261           csit-vpp-perf-1710-all:
 262           - 20
 263           - 23
 264       plot-layouts:
 265         plot-throughput:
 266           xaxis:
 267             autorange: True
 268             autotick: False
 269             fixedrange: False
 270             gridcolor: "rgb(238, 238, 238)"
 271             linecolor: "rgb(238, 238, 238)"
 272             linewidth: 1
 273             showgrid: True
 274             showline: True
 275             showticklabels: True
 276             tickcolor: "rgb(238, 238, 238)"
 277             tickmode: "linear"
 278             title: "Indexed Test Cases"
 279             zeroline: False
 280           yaxis:
 281             gridcolor: "rgb(238, 238, 238)'"
 282             hoverformat: ".4s"
 283             linecolor: "rgb(238, 238, 238)"
 284             linewidth: 1
 285             range: []
 286             showgrid: True
 287             showline: True
 288             showticklabels: True
 289             tickcolor: "rgb(238, 238, 238)"
 290             title: "Packets Per Second [pps]"
 291             zeroline: False
 292           boxmode: "group"
 293           boxgroupgap: 0.5
 294           autosize: False
 295           margin:
 296             t: 50
 297             b: 20
 298             l: 50
 299             r: 20
 300           showlegend: True
 301           legend:
 302             orientation: "h"
 303           width: 700
 304           height: 1000
 305
 306 The definitions from this sections are used in the elements, e.g.:
 307
 308 ::
 309
 310     -
 311       type: "plot"
 312       title: "VPP Performance 64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
 313       algorithm: "plot_performance_box"
 314       output-file-type: ".html"
 315       output-file: "{DIR[STATIC,VPP]}/64B-1t1c-l2-sel1-ndrdisc"
 316       data:
 317         "plot-vpp-throughput-latency"
 318       filter: "'64B' and ('BASE' or 'SCALE') and 'NDRDISC' and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
 319       parameters:
 320       - "throughput"
 321       - "parent"
 322       traces:
 323         hoverinfo: "x+y"
 324         boxpoints: "outliers"
 325         whiskerwidth: 0
 326       layout:
 327         title: "64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
 328         layout:
 329           "plot-throughput"
 330
 331
 332 Section: Debug mode
 333 '''''''''''''''''''
 334
 335 This section is optional as it configures the debug mode. It is used if one
 336 does not want to download input data files and use local files instead.
 337
 338 If the debug mode is configured, the "input" section is ignored.
 339
 340 This section has the following parts:
 341
 342  - type: "debug" - says that this is the section "debug".
 343  - general:
 344
 345    - input-format - xml or zip.
 346    - extract - if "zip" is defined as the input format, this file is extracted
 347      from the zip file, otherwise this parameter is ignored.
 348
 349  - builds - list of builds from which the data is used. Must include a job
 350    name as a key and then a list of builds and their output files.
 351
 352 The structure of the section "Debug" is as follows (example):
 353
 354 ::
 355
 356     -
 357       type: "debug"
 358       general:
 359         input-format: "zip"  # zip or xml
 360         extract: "robot-plugin/output.xml"  # Only for zip
 361       builds:
 362         # The files must be in the directory DIR[WORKING,DATA]
 363         csit-dpdk-perf-1707-all:
 364         -
 365           build: 10
 366           file: "csit-dpdk-perf-1707-all__10.xml"
 367         -
 368           build: 9
 369           file: "csit-dpdk-perf-1707-all__9.xml"
 370         csit-vpp-functional-1707-ubuntu1604-virl:
 371         -
 372           build: lastSuccessfulBuild
 373           file: "csit-vpp-functional-1707-ubuntu1604-virl-lastSuccessfulBuild.xml"
 374         hc2vpp-csit-integration-1707-ubuntu1604:
 375         -
 376           build: lastSuccessfulBuild
 377           file: "hc2vpp-csit-integration-1707-ubuntu1604-lastSuccessfulBuild.xml"
 378         csit-vpp-perf-1707-all:
 379         -
 380           build: 16
 381           file: "csit-vpp-perf-1707-all__16__output.xml"
 382         -
 383           build: 17
 384           file: "csit-vpp-perf-1707-all__17__output.xml"
 385
 386
 387 Section: Static
 388 '''''''''''''''
 389
 390 This section defines the static content which is stored in git and will be used
 391 as a source to generate the report.
 392
 393 This section has these parts:
 394
 395  - type: "static" - says that this section is the "static".
 396  - src-path - path to the static content.
 397  - dst-path - destination path where the static content is copied and then
 398    processed.
 399
 400 ::
 401
 402     -
 403       type: "static"
 404       src-path: "{DIR[RST]}"
 405       dst-path: "{DIR[WORKING,SRC]}"
 406
 407
 408 Section: Input
 409 ''''''''''''''
 410
 411 This section defines the data used to generate elements. It is mandatory
 412 if the debug mode is not used.
 413
 414 This section has the following parts:
 415
 416  - type: "input" - says that this section is the "input".
 417  - general - parameters common to all builds:
 418
 419    - file-name: file to be downloaded.
 420    - file-format: format of the downloaded file, ".zip" or ".xml" are supported.
 421    - download-path: path to be added to url pointing to the file, e.g.:
 422      "{job}/{build}/robot/report/*zip*/{filename}"; {job}, {build} and
 423      {filename} are replaced by proper values defined in this section.
 424    - extract: file to be extracted from downloaded zip file, e.g.: "output.xml";
 425      if xml file is downloaded, this parameter is ignored.
 426
 427  - builds - list of jobs (keys) and numbers of builds which output data will be
 428    downloaded.
 429
 430 The structure of the section "Input" is as follows (example from 17.07 report):
 431
 432 ::
 433
 434     -
 435       type: "input"  # Ignored in debug mode
 436       general:
 437         file-name: "robot-plugin.zip"
 438         file-format: ".zip"
 439         download-path: "{job}/{build}/robot/report/*zip*/{filename}"
 440         extract: "robot-plugin/output.xml"
 441       builds:
 442         csit-vpp-perf-1707-all:
 443         - 9
 444         - 10
 445         - 13
 446         - 14
 447         - 15
 448         - 16
 449         - 17
 450         - 18
 451         - 19
 452         - 21
 453         - 22
 454         csit-dpdk-perf-1707-all:
 455         - 1
 456         - 2
 457         - 3
 458         - 4
 459         - 5
 460         - 6
 461         - 7
 462         - 8
 463         - 9
 464         - 10
 465         csit-vpp-functional-1707-ubuntu1604-virl:
 466         - lastSuccessfulBuild
 467         hc2vpp-csit-perf-master-ubuntu1604:
 468         - 8
 469         - 9
 470         hc2vpp-csit-integration-1707-ubuntu1604:
 471         - lastSuccessfulBuild
 472
 473 Section: Output
 474 '''''''''''''''
 475
 476 This section specifies which format(s) will be generated (html, pdf) and which
 477 versions will be generated for each format.
 478
 479 This section has the following parts:
 480
 481  - type: "output" - says that this section is the "output".
 482  - format: html or pdf.
 483  - version: defined for each format separately.
 484
 485 The structure of the section "Output" is as follows (example):
 486
 487 ::
 488
 489     -
 490       type: "output"
 491       format:
 492         html:
 493         - full
 494         pdf:
 495         - full
 496         - minimal
 497
 498 TODO: define the names of versions
 499
 500
 501 Content of "minimal" version
 502 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 503
 504 TODO: define the name and content of this version
 505
 506
 507 Section: Table
 508 ''''''''''''''
 509
 510 This section defines a table to be generated. There can be 0 or more "table"
 511 sections.
 512
 513 This section has the following parts:
 514
 515  - type: "table" - says that this section defines a table.
 516  - title: Title of the table.
 517  - algorithm: Algorithm which is used to generate the table. The other
 518    parameters in this section must provide all information needed by the used
 519    algorithm.
 520  - template: (optional) a .csv file used as a template while generating the
 521    table.
 522  - output-file-ext: extension of the output file.
 523  - output-file: file which the table will be written to.
 524  - columns: specification of table columns:
 525
 526    - title: The title used in the table header.
 527    - data: Specification of the data, it has two parts - command and arguments:
 528
 529      - command:
 530
 531        - template - take the data from template, arguments:
 532
 533          - number of column in the template.
 534
 535        - data - take the data from the input data, arguments:
 536
 537          - jobs and builds which data will be used.
 538
 539        - operation - performs an operation with the data already in the table,
 540          arguments:
 541
 542          - operation to be done, e.g.: mean, stdev, relative_change (compute
 543            the relative change between two columns) and display number of data
 544            samples ~= number of test jobs. The operations are implemented in the
 545            utils.py
 546            TODO: Move from utils,py to e.g. operations.py
 547          - numbers of columns which data will be used (optional).
 548
 549  - data: Specify the jobs and builds which data is used to generate the table.
 550  - filter: filter based on tags applied on the input data, if "template" is
 551    used, filtering is based on the template.
 552  - parameters: Only these parameters will be put to the output data structure.
 553
 554 The structure of the section "Table" is as follows (example of
 555 "table_performance_improvements"):
 556
 557 ::
 558
 559     -
 560       type: "table"
 561       title: "Performance improvements"
 562       algorithm: "table_performance_improvements"
 563       template: "{DIR[DTR,PERF,VPP,IMPRV]}/tmpl_performance_improvements.csv"
 564       output-file-ext: ".csv"
 565       output-file: "{DIR[DTR,PERF,VPP,IMPRV]}/performance_improvements"
 566       columns:
 567       -
 568         title: "VPP Functionality"
 569         data: "template 1"
 570       -
 571         title: "Test Name"
 572         data: "template 2"
 573       -
 574         title: "VPP-16.09 mean [Mpps]"
 575         data: "template 3"
 576       -
 577         title: "VPP-17.01 mean [Mpps]"
 578         data: "template 4"
 579       -
 580         title: "VPP-17.04 mean [Mpps]"
 581         data: "template 5"
 582       -
 583         title: "VPP-17.07 mean [Mpps]"
 584         data: "data csit-vpp-perf-1707-all mean"
 585       -
 586         title: "VPP-17.07 stdev [Mpps]"
 587         data: "data csit-vpp-perf-1707-all stdev"
 588       -
 589         title: "17.04 to 17.07 change [%]"
 590         data: "operation relative_change 5 4"
 591       data:
 592         csit-vpp-perf-1707-all:
 593         - 9
 594         - 10
 595         - 13
 596         - 14
 597         - 15
 598         - 16
 599         - 17
 600         - 18
 601         - 19
 602         - 21
 603       filter: "template"
 604       parameters:
 605       - "throughput"
 606
 607 Example of "table_details" which generates "Detailed Test Results - VPP
 608 Performance Results":
 609
 610 ::
 611
 612     -
 613       type: "table"
 614       title: "Detailed Test Results - VPP Performance Results"
 615       algorithm: "table_details"
 616       output-file-ext: ".csv"
 617       output-file: "{DIR[WORKING]}/vpp_performance_results"
 618       columns:
 619       -
 620         title: "Name"
 621         data: "data test_name"
 622       -
 623         title: "Documentation"
 624         data: "data test_documentation"
 625       -
 626         title: "Status"
 627         data: "data test_msg"
 628       data:
 629         csit-vpp-perf-1707-all:
 630         - 17
 631       filter: "all"
 632       parameters:
 633       - "parent"
 634       - "doc"
 635       - "msg"
 636
 637 Example of "table_details" which generates "Test configuration - VPP Performance
 638 Test Configs":
 639
 640 ::
 641
 642     -
 643       type: "table"
 644       title: "Test configuration - VPP Performance Test Configs"
 645       algorithm: "table_details"
 646       output-file-ext: ".csv"
 647       output-file: "{DIR[WORKING]}/vpp_test_configuration"
 648       columns:
 649       -
 650         title: "Name"
 651         data: "data name"
 652       -
 653         title: "VPP API Test (VAT) Commands History - Commands Used Per Test Case"
 654         data: "data show-run"
 655       data:
 656         csit-vpp-perf-1707-all:
 657         - 17
 658       filter: "all"
 659       parameters:
 660       - "parent"
 661       - "name"
 662       - "show-run"
 663
 664
 665 Section: Plot
 666 '''''''''''''
 667
 668 This section defines a plot to be generated. There can be 0 or more "plot"
 669 sections.
 670
 671 This section has these parts:
 672
 673  - type: "plot" - says that this section defines a plot.
 674  - title: Plot title used in the logs. Title which is displayed is in the
 675    section "layout".
 676  - output-file-type: format of the output file.
 677  - output-file: file which the plot will be written to.
 678  - algorithm: Algorithm used to generate the plot. The other parameters in this
 679    section must provide all information needed by plot.ly to generate the plot.
 680    For example:
 681
 682    - traces
 683    - layout
 684
 685    - These parameters are transparently passed to plot.ly.
 686
 687  - data: Specify the jobs and numbers of builds which data is used to generate
 688    the plot.
 689  - filter: filter applied on the input data.
 690  - parameters: Only these parameters will be put to the output data structure.
 691
 692 The structure of the section "Plot" is as follows (example of a plot showing
 693 throughput in a chart box-with-whiskers):
 694
 695 ::
 696
 697     -
 698       type: "plot"
 699       title: "VPP Performance 64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
 700       algorithm: "plot_performance_box"
 701       output-file-type: ".html"
 702       output-file: "{DIR[STATIC,VPP]}/64B-1t1c-l2-sel1-ndrdisc"
 703       data:
 704         csit-vpp-perf-1707-all:
 705         - 9
 706         - 10
 707         - 13
 708         - 14
 709         - 15
 710         - 16
 711         - 17
 712         - 18
 713         - 19
 714         - 21
 715       # Keep this formatting, the filter is enclosed with " (quotation mark) and
 716       # each tag is enclosed with ' (apostrophe).
 717       filter: "'64B' and 'BASE' and 'NDRDISC' and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
 718       parameters:
 719       - "throughput"
 720       - "parent"
 721       traces:
 722         hoverinfo: "x+y"
 723         boxpoints: "outliers"
 724         whiskerwidth: 0
 725       layout:
 726         title: "64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
 727         xaxis:
 728           autorange: True
 729           autotick: False
 730           fixedrange: False
 731           gridcolor: "rgb(238, 238, 238)"
 732           linecolor: "rgb(238, 238, 238)"
 733           linewidth: 1
 734           showgrid: True
 735           showline: True
 736           showticklabels: True
 737           tickcolor: "rgb(238, 238, 238)"
 738           tickmode: "linear"
 739           title: "Indexed Test Cases"
 740           zeroline: False
 741         yaxis:
 742           gridcolor: "rgb(238, 238, 238)'"
 743           hoverformat: ".4s"
 744           linecolor: "rgb(238, 238, 238)"
 745           linewidth: 1
 746           range: []
 747           showgrid: True
 748           showline: True
 749           showticklabels: True
 750           tickcolor: "rgb(238, 238, 238)"
 751           title: "Packets Per Second [pps]"
 752           zeroline: False
 753         boxmode: "group"
 754         boxgroupgap: 0.5
 755         autosize: False
 756         margin:
 757           t: 50
 758           b: 20
 759           l: 50
 760           r: 20
 761         showlegend: True
 762         legend:
 763           orientation: "h"
 764         width: 700
 765         height: 1000
 766
 767 The structure of the section "Plot" is as follows (example of a plot showing
 768 latency in a box chart):
 769
 770 ::
 771
 772     -
 773       type: "plot"
 774       title: "VPP Latency 64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
 775       algorithm: "plot_latency_box"
 776       output-file-type: ".html"
 777       output-file: "{DIR[STATIC,VPP]}/64B-1t1c-l2-sel1-ndrdisc-lat50"
 778       data:
 779         csit-vpp-perf-1707-all:
 780         - 9
 781         - 10
 782         - 13
 783         - 14
 784         - 15
 785         - 16
 786         - 17
 787         - 18
 788         - 19
 789         - 21
 790       filter: "'64B' and 'BASE' and 'NDRDISC' and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
 791       parameters:
 792       - "latency"
 793       - "parent"
 794       traces:
 795         boxmean: False
 796       layout:
 797         title: "64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
 798         xaxis:
 799           autorange: True
 800           autotick: False
 801           fixedrange: False
 802           gridcolor: "rgb(238, 238, 238)"
 803           linecolor: "rgb(238, 238, 238)"
 804           linewidth: 1
 805           showgrid: True
 806           showline: True
 807           showticklabels: True
 808           tickcolor: "rgb(238, 238, 238)"
 809           tickmode: "linear"
 810           title: "Indexed Test Cases"
 811           zeroline: False
 812         yaxis:
 813           gridcolor: "rgb(238, 238, 238)'"
 814           hoverformat: ""
 815           linecolor: "rgb(238, 238, 238)"
 816           linewidth: 1
 817           range: []
 818           showgrid: True
 819           showline: True
 820           showticklabels: True
 821           tickcolor: "rgb(238, 238, 238)"
 822           title: "Latency min/avg/max [uSec]"
 823           zeroline: False
 824         boxmode: "group"
 825         boxgroupgap: 0.5
 826         autosize: False
 827         margin:
 828           t: 50
 829           b: 20
 830           l: 50
 831           r: 20
 832         showlegend: True
 833         legend:
 834           orientation: "h"
 835         width: 700
 836         height: 1000
 837
 838 The structure of the section "Plot" is as follows (example of a plot showing
 839 VPP HTTP server performance in a box chart with pre-defined data
 840 "plot-vpp-http-server-performance" set and  plot layout "plot-cps"):
 841
 842 ::
 843
 844     -
 845       type: "plot"
 846       title: "VPP HTTP Server Performance"
 847       algorithm: "plot_http_server_perf_box"
 848       output-file-type: ".html"
 849       output-file: "{DIR[STATIC,VPP]}/http-server-performance-cps"
 850       data:
 851         "plot-vpp-httlp-server-performance"
 852       # Keep this formatting, the filter is enclosed with " (quotation mark) and
 853       # each tag is enclosed with ' (apostrophe).
 854       filter: "'HTTP' and 'TCP_CPS'"
 855       parameters:
 856       - "result"
 857       - "name"
 858       traces:
 859         hoverinfo: "x+y"
 860         boxpoints: "outliers"
 861         whiskerwidth: 0
 862       layout:
 863         title: "VPP HTTP Server Performance"
 864         layout:
 865           "plot-cps"
 866
 867
 868 Section: file
 869 '''''''''''''
 870
 871 This section defines a file to be generated. There can be 0 or more "file"
 872 sections.
 873
 874 This section has the following parts:
 875
 876  - type: "file" - says that this section defines a file.
 877  - title: Title of the table.
 878  - algorithm: Algorithm which is used to generate the file. The other
 879    parameters in this section must provide all information needed by the used
 880    algorithm.
 881  - output-file-ext: extension of the output file.
 882  - output-file: file which the file will be written to.
 883  - file-header: The header of the generated .rst file.
 884  - dir-tables: The directory with the tables.
 885  - data: Specify the jobs and builds which data is used to generate the table.
 886  - filter: filter based on tags applied on the input data, if "all" is
 887    used, no filtering is done.
 888  - parameters: Only these parameters will be put to the output data structure.
 889  - chapters: the hierarchy of chapters in the generated file.
 890  - start-level: the level of the the top-level chapter.
 891
 892 The structure of the section "file" is as follows (example):
 893
 894 ::
 895
 896     -
 897       type: "file"
 898       title: "VPP Performance Results"
 899       algorithm: "file_test_results"
 900       output-file-ext: ".rst"
 901       output-file: "{DIR[DTR,PERF,VPP]}/vpp_performance_results"
 902       file-header: "\n.. |br| raw:: html\n\n    <br />\n\n\n.. |prein| raw:: html\n\n    <pre>\n\n\n.. |preout| raw:: html\n\n    </pre>\n\n"
 903       dir-tables: "{DIR[DTR,PERF,VPP]}"
 904       data:
 905         csit-vpp-perf-1707-all:
 906         - 22
 907       filter: "all"
 908       parameters:
 909       - "name"
 910       - "doc"
 911       - "level"
 912       data-start-level: 2  # 0, 1, 2, ...
 913       chapters-start-level: 2  # 0, 1, 2, ...
 914
 915
 916 Static content
 917 ``````````````
 918
 919  - Manually created / edited files.
 920  - .rst files, static .csv files, static pictures (.svg), ...
 921  - Stored in CSIT git repository.
 922
 923 No more details about the static content in this document.
 924
 925
 926 Data to process
 927 ```````````````
 928
 929 The PAL processes tests results and other information produced by Jenkins jobs.
 930 The data are now stored as robot results in Jenkins (TODO: store the data in
 931 nexus) either as .zip and / or .xml files.
 932
 933
 934 Data processing
 935 ---------------
 936
 937 As the first step, the data are downloaded and stored locally (typically on a
 938 Jenkins slave). If .zip files are used, the given .xml files are extracted for
 939 further processing.
 940
 941 Parsing of the .xml files is performed by a class derived from
 942 "robot.api.ResultVisitor", only necessary methods are overridden. All and only
 943 necessary data is extracted from .xml file and stored in a structured form.
 944
 945 The parsed data are stored as the multi-indexed pandas.Series data type. Its
 946 structure is as follows:
 947
 948 ::
 949
 950     <job name>
 951       <build>
 952         <metadata>
 953         <suites>
 954         <tests>
 955
 956 "job name", "build", "metadata", "suites", "tests" are indexes to access the
 957 data. For example:
 958
 959 ::
 960
 961     data =
 962
 963     job 1 name:
 964       build 1:
 965         metadata: metadata
 966         suites: suites
 967         tests: tests
 968       ...
 969       build N:
 970         metadata: metadata
 971         suites: suites
 972         tests: tests
 973     ...
 974     job M name:
 975       build 1:
 976         metadata: metadata
 977         suites: suites
 978         tests: tests
 979       ...
 980       build N:
 981         metadata: metadata
 982         suites: suites
 983         tests: tests
 984
 985 Using indexes data["job 1 name"]["build 1"]["tests"] (e.g.:
 986 data["csit-vpp-perf-1704-all"]["17"]["tests"]) we get a list of all tests with
 987 all tests data.
 988
 989 Data will not be accessible directly using indexes, but using getters and
 990 filters.
 991
 992 **Structure of metadata:**
 993
 994 ::
 995
 996     "metadata": {
 997         "version": "VPP version",
 998         "job": "Jenkins job name"
 999         "build": "Information about the build"
1000     },
1001
1002 **Structure of suites:**
1003
1004 ::
1005
1006     "suites": {
1007         "Suite name 1": {
1008             "doc": "Suite 1 documentation"
1009             "parent": "Suite 1 parent"
1010         }
1011         "Suite name N": {
1012             "doc": "Suite N documentation"
1013             "parent": "Suite N parent"
1014         }
1015
1016 **Structure of tests:**
1017
1018 Performance tests:
1019
1020 ::
1021
1022     "tests": {
1023         "ID": {
1024             "name": "Test name",
1025             "parent": "Name of the parent of the test",
1026             "doc": "Test documentation"
1027             "msg": "Test message"
1028             "tags": ["tag 1", "tag 2", "tag n"],
1029             "type": "PDR" | "NDR",
1030             "throughput": {
1031                 "value": int,
1032                 "unit": "pps" | "bps" | "percentage"
1033             },
1034             "latency": {
1035                 "direction1": {
1036                     "100": {
1037                         "min": int,
1038                         "avg": int,
1039                         "max": int
1040                     },
1041                     "50": {  # Only for NDR
1042                         "min": int,
1043                         "avg": int,
1044                         "max": int
1045                     },
1046                     "10": {  # Only for NDR
1047                         "min": int,
1048                         "avg": int,
1049                         "max": int
1050                     }
1051                 },
1052                 "direction2": {
1053                     "100": {
1054                         "min": int,
1055                         "avg": int,
1056                         "max": int
1057                     },
1058                     "50": {  # Only for NDR
1059                         "min": int,
1060                         "avg": int,
1061                         "max": int
1062                     },
1063                     "10": {  # Only for NDR
1064                         "min": int,
1065                         "avg": int,
1066                         "max": int
1067                     }
1068                 }
1069             },
1070             "lossTolerance": "lossTolerance"  # Only for PDR
1071             "vat-history": "DUT1 and DUT2 VAT History"
1072             },
1073             "show-run": "Show Run"
1074         },
1075         "ID" {
1076             # next test
1077         }
1078
1079 Functional tests:
1080
1081 ::
1082
1083     "tests": {
1084         "ID": {
1085             "name": "Test name",
1086             "parent": "Name of the parent of the test",
1087             "doc": "Test documentation"
1088             "msg": "Test message"
1089             "tags": ["tag 1", "tag 2", "tag n"],
1090             "vat-history": "DUT1 and DUT2 VAT History"
1091             "show-run": "Show Run"
1092             "status": "PASS" | "FAIL"
1093         },
1094         "ID" {
1095             # next test
1096         }
1097     }
1098
1099 Note: ID is the lowercase full path to the test.
1100
1101
1102 Data filtering
1103 ``````````````
1104
1105 The first step when generating an element is getting the data needed to
1106 construct the element. The data are filtered from the processed input data.
1107
1108 The data filtering is based on:
1109
1110  - job name(s).
1111  - build number(s).
1112  - tag(s).
1113  - required data - only this data is included in the output.
1114
1115 WARNING: The filtering is based on tags, so be careful with tagging.
1116
1117 For example, the element which specification includes:
1118
1119 ::
1120
1121     data:
1122       csit-vpp-perf-1707-all:
1123       - 9
1124       - 10
1125       - 13
1126       - 14
1127       - 15
1128       - 16
1129       - 17
1130       - 18
1131       - 19
1132       - 21
1133     filter:
1134       - "'64B' and 'BASE' and 'NDRDISC' and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
1135
1136 will be constructed using data from the job "csit-vpp-perf-1707-all", for all
1137 listed builds and the tests with the list of tags matching the filter
1138 conditions.
1139
1140 The output data structure for filtered test data is:
1141
1142 ::
1143
1144     - job 1
1145       - build 1
1146         - test 1
1147           - parameter 1
1148           - parameter 2
1149           ...
1150           - parameter n
1151         ...
1152         - test n
1153         ...
1154       ...
1155       - build n
1156     ...
1157     - job n
1158
1159
1160 Data analytics
1161 ``````````````
1162
1163 Data analytics part implements:
1164
1165  - methods to compute statistical data from the filtered input data.
1166  - trending.
1167
1168 Throughput Speedup Analysis - Multi-Core with Multi-Threading
1169 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
1170
1171 Throughput Speedup Analysis (TSA) calculates throughput speedup ratios
1172 for tested 1-, 2- and 4-core multi-threaded VPP configurations using the
1173 following formula:
1174
1175 ::
1176
1177                                 N_core_throughput
1178     N_core_throughput_speedup = -----------------
1179                                 1_core_throughput
1180
1181 Multi-core throughput speedup ratios are plotted in grouped bar graphs
1182 for throughput tests with 64B/78B frame size, with number of cores on
1183 X-axis and speedup ratio on Y-axis.
1184
1185 For better comparison multiple test results' data sets are plotted per
1186 each graph:
1187
1188     - graph type: grouped bars;
1189     - graph X-axis: (testcase index, number of cores);
1190     - graph Y-axis: speedup factor.
1191
1192 Subset of existing performance tests is covered by TSA graphs.
1193
1194 **Model for TSA:**
1195
1196 ::
1197
1198     -
1199       type: "plot"
1200       title: "TSA: 64B-*-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
1201       algorithm: "plot_throughput_speedup_analysis"
1202       output-file-type: ".html"
1203       output-file: "{DIR[STATIC,VPP]}/10ge2p1x520-64B-l2-tsa-ndrdisc"
1204       data:
1205         "plot-throughput-speedup-analysis"
1206       filter: "'NIC_Intel-X520-DA2' and '64B' and 'BASE' and 'NDRDISC' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
1207       parameters:
1208       - "throughput"
1209       - "parent"
1210       - "tags"
1211       layout:
1212         title: "64B-*-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
1213         layout:
1214           "plot-throughput-speedup-analysis"
1215
1216
1217 Comparison of results from two sets of the same test executions
1218 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
1219
1220 This algorithm enables comparison of results coming from two sets of the
1221 same test executions. It is used to quantify performance changes across
1222 all tests after test environment changes e.g. Operating System
1223 upgrades/patches, Hardware changes.
1224
1225 It is assumed that each set of test executions includes multiple runs
1226 of the same tests, 10 or more, to verify test results repeatibility and
1227 to yield statistically meaningful results data.
1228
1229 Comparison results are presented in a table with a specified number of
1230 the best and the worst relative changes between the two sets. Following table
1231 columns are defined:
1232
1233     - name of the test;
1234     - throughput mean values of the reference set;
1235     - throughput standard deviation  of the reference set;
1236     - throughput mean values of the set to compare;
1237     - throughput standard deviation  of the set to compare;
1238     - relative change of the mean values.
1239
1240 **The model**
1241
1242 The model specifies:
1243
1244     - type: "table" - means this section defines a table.
1245     - title: Title of the table.
1246     - algorithm: Algorithm which is used to generate the table. The other
1247       parameters in this section must provide all information needed by the used
1248       algorithm.
1249     - output-file-ext: Extension of the output file.
1250     - output-file: File which the table will be written to.
1251     - reference - the builds which are used as the reference for comparison.
1252     - compare - the builds which are compared to the reference.
1253     - data: Specify the sources, jobs and builds, providing data for generating
1254       the table.
1255     - filter: Filter based on tags applied on the input data, if "template" is
1256       used, filtering is based on the template.
1257     - parameters: Only these parameters will be put to the output data
1258       structure.
1259     - nr-of-tests-shown: Number of the best and the worst tests presented in the
1260       table. Use 0 (zero) to present all tests.
1261
1262 *Example:*
1263
1264 ::
1265
1266     -
1267       type: "table"
1268       title: "Performance comparison"
1269       algorithm: "table_perf_comparison"
1270       output-file-ext: ".csv"
1271       output-file: "{DIR[DTR,PERF,VPP,IMPRV]}/vpp_performance_comparison"
1272       reference:
1273         title: "csit-vpp-perf-1801-all - 1"
1274         data:
1275           csit-vpp-perf-1801-all:
1276           - 1
1277           - 2
1278       compare:
1279         title: "csit-vpp-perf-1801-all - 2"
1280         data:
1281           csit-vpp-perf-1801-all:
1282           - 1
1283           - 2
1284       data:
1285         "vpp-perf-comparison"
1286       filter: "all"
1287       parameters:
1288       - "name"
1289       - "parent"
1290       - "throughput"
1291       nr-of-tests-shown: 20
1292
1293
1294 Advanced data analytics
1295 ```````````````````````
1296
1297 In the future advanced data analytics (ADA) will be added to analyze the
1298 telemetry data collected from SUT telemetry sources and correlate it to
1299 performance test results.
1300
1301 :TODO:
1302
1303     - describe the concept of ADA.
1304     - add specification.
1305
1306
1307 Data presentation
1308 -----------------
1309
1310 Generates the plots and tables according to the report models per
1311 specification file. The elements are generated using algorithms and data
1312 specified in their models.
1313
1314
1315 Tables
1316 ``````
1317
1318  - tables are generated by algorithms implemented in PAL, the model includes the
1319    algorithm and all necessary information.
1320  - output format: csv
1321  - generated tables are stored in specified directories and linked to .rst
1322    files.
1323
1324
1325 Plots
1326 `````
1327
1328  - `plot.ly <https://plot.ly/>`_ is currently used to generate plots, the model
1329    includes the type of plot and all the necessary information to render it.
1330  - output format: html.
1331  - generated plots are stored in specified directories and linked to .rst files.
1332
1333
1334 Report generation
1335 -----------------
1336
1337 Report is generated using Sphinx and Read_the_Docs template. PAL generates html
1338 and pdf formats. It is possible to define the content of the report by
1339 specifying the version (TODO: define the names and content of versions).
1340
1341
1342 The process
1343 ```````````
1344
1345 1. Read the specification.
1346 2. Read the input data.
1347 3. Process the input data.
1348 4. For element (plot, table, file) defined in specification:
1349
1350    a. Get the data needed to construct the element using a filter.
1351    b. Generate the element.
1352    c. Store the element.
1353
1354 5. Generate the report.
1355 6. Store the report (Nexus).
1356
1357 The process is model driven. The elements' models (tables, plots, files
1358 and report itself) are defined in the specification file. Script reads
1359 the elements' models from specification file and generates the elements.
1360
1361 It is easy to add elements to be generated in the report. If a new type
1362 of an element is required, only a new algorithm needs to be implemented
1363 and integrated.
1364
1365
1366 Continuous Performance Measurements and Trending
1367 ------------------------------------------------
1368
1369 Performance analysis and trending execution sequence:
1370 `````````````````````````````````````````````````````
1371
1372 CSIT PA runs performance analysis, change detection and trending using specified
1373 trend analysis metrics over the rolling window of last <N> sets of historical
1374 measurement data. PA is defined as follows:
1375
1376     #. PA job triggers:
1377
1378         #. By PT job at its completion.
1379         #. Manually from Jenkins UI.
1380
1381     #. Download and parse archived historical data and the new data:
1382
1383         #. New data from latest PT job is evaluated against the rolling window
1384            of <N> sets of historical data.
1385         #. Download RF output.xml files and compressed archived data.
1386         #. Parse out the data filtering test cases listed in PA specification
1387            (part of CSIT PAL specification file).
1388
1389     #. Calculate trend metrics for the rolling window of <N> sets of historical
1390        data:
1391
1392         #. Calculate quartiles Q1, Q2, Q3.
1393         #. Trim outliers using IQR.
1394         #. Calculate TMA and TMSD.
1395         #. Calculate normal trending range per test case based on TMA and TMSD.
1396
1397     #. Evaluate new test data against trend metrics:
1398
1399         #. If within the range of (TMA +/- 3*TMSD) => Result = Pass,
1400            Reason = Normal.
1401         #. If below the range => Result = Fail, Reason = Regression.
1402         #. If above the range => Result = Pass, Reason = Progression.
1403
1404     #. Generate and publish results
1405
1406         #. Relay evaluation result to job result.
1407         #. Generate a new set of trend analysis summary graphs and drill-down
1408            graphs.
1409
1410             #. Summary graphs to include measured values with Normal,
1411                Progression and Regression markers. MM shown in the background if
1412                possible.
1413             #. Drill-down graphs to include MM, TMA and TMSD.
1414
1415         #. Publish trend analysis graphs in html format on
1416            https://docs.fd.io/csit/master/trending/.
1417
1418
1419 Parameters to specify:
1420 ``````````````````````
1421
1422 *General section - parameters common to all plots:*
1423
1424     - type: "cpta";
1425     - title: The title of this section;
1426     - output-file-type: only ".html" is supported;
1427     - output-file: path where the generated files will be stored.
1428
1429 *Plots section:*
1430
1431     - plot title;
1432     - output file name;
1433     - input data for plots;
1434
1435         - job to be monitored - the Jenkins job which results are used as input
1436           data for this test;
1437         - builds used for trending plot(s) - specified by a list of build
1438           numbers or by a range of builds defined by the first and the last
1439           build number;
1440
1441     - tests to be displayed in the plot defined by a filter;
1442     - list of parameters to extract from the data;
1443     - plot layout
1444
1445 *Example:*
1446
1447 ::
1448
1449     -
1450       type: "cpta"
1451       title: "Continuous Performance Trending and Analysis"
1452       output-file-type: ".html"
1453       output-file: "{DIR[STATIC,VPP]}/cpta"
1454       plots:
1455
1456         - title: "VPP 1T1C L2 64B Packet Throughput - Trending"
1457           output-file-name: "l2-1t1c-x520"
1458           data: "plot-performance-trending-vpp"
1459           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'"
1460           parameters:
1461           - "result"
1462           layout: "plot-cpta-vpp"
1463
1464         - title: "DPDK 4T4C IMIX MRR Trending"
1465           output-file-name: "dpdk-imix-4t4c-xl710"
1466           data: "plot-performance-trending-dpdk"
1467           filter: "'NIC_Intel-XL710' and 'IMIX' and 'MRR' and '4T4C' and 'DPDK'"
1468           parameters:
1469           - "result"
1470           layout: "plot-cpta-dpdk"
1471
1472 The Dashboard
1473 `````````````
1474
1475 Performance dashboard tables provide the latest VPP throughput trend, trend
1476 compliance and detected anomalies, all on a per VPP test case basis.
1477 The Dashboard is generated as three tables for 1t1c, 2t2c and 4t4c MRR tests.
1478
1479 At first, the .csv tables are generated (only the table for 1t1c is shown):
1480
1481 ::
1482
1483     -
1484       type: "table"
1485       title: "Performance trending dashboard"
1486       algorithm: "table_perf_trending_dash"
1487       output-file-ext: ".csv"
1488       output-file: "{DIR[STATIC,VPP]}/performance-trending-dashboard-1t1c"
1489       data: "plot-performance-trending-all"
1490       filter: "'MRR' and '1T1C'"
1491       parameters:
1492       - "name"
1493       - "parent"
1494       - "result"
1495       ignore-list:
1496       - "tests.vpp.perf.l2.10ge2p1x520-eth-l2bdscale1mmaclrn-mrr.tc01-64b-1t1c-eth-l2bdscale1mmaclrn-ndrdisc"
1497       outlier-const: 1.5
1498       window: 14
1499       evaluated-window: 14
1500       long-trend-window: 180
1501
1502 Then, html tables stored inside .rst files are generated:
1503
1504 ::
1505
1506     -
1507       type: "table"
1508       title: "HTML performance trending dashboard 1t1c"
1509       algorithm: "table_perf_trending_dash_html"
1510       input-file: "{DIR[STATIC,VPP]}/performance-trending-dashboard-1t1c.csv"
1511       output-file: "{DIR[STATIC,VPP]}/performance-trending-dashboard-1t1c.rst"
1512
1513 Root Cause Analysis
1514 -------------------
1515
1516 Root Cause Analysis (RCA) by analysing archived performance results – re-analyse
1517 available data for specified:
1518
1519     - range of jobs builds,
1520     - set of specific tests and
1521     - PASS/FAIL criteria to detect performance change.
1522
1523 In addition, PAL generates trending plots to show performance over the specified
1524 time interval.
1525
1526 Root Cause Analysis - Option 1: Analysing Archived VPP Results
1527 ``````````````````````````````````````````````````````````````
1528
1529 It can be used to speed-up the process, or when the existing data is sufficient.
1530 In this case, PAL uses existing data saved in Nexus, searches for performance
1531 degradations and generates plots to show performance over the specified time
1532 interval for the selected tests.
1533
1534 Execution Sequence
1535 ''''''''''''''''''
1536
1537     #. Download and parse archived historical data and the new data.
1538     #. Calculate trend metrics.
1539     #. Find regression / progression.
1540     #. Generate and publish results:
1541
1542         #. Summary graphs to include measured values with Progression and
1543            Regression markers.
1544         #. List the DUT build(s) where the anomalies were detected.
1545
1546 CSIT PAL Specification
1547 ''''''''''''''''''''''
1548
1549     - What to test:
1550
1551         - first build (Good); specified by the Jenkins job name and the build
1552           number
1553         - last build (Bad); specified by the Jenkins job name and the build
1554           number
1555         - step (1..n).
1556
1557     - Data:
1558
1559         - tests of interest; list of tests (full name is used) which results are
1560           used
1561
1562 *Example:*
1563
1564 ::
1565
1566     TODO
1567
1568
1569 API
1570 ---
1571
1572 List of modules, classes, methods and functions
1573 ```````````````````````````````````````````````
1574
1575 ::
1576
1577     specification_parser.py
1578
1579         class Specification
1580
1581             Methods:
1582                 read_specification
1583                 set_input_state
1584                 set_input_file_name
1585
1586             Getters:
1587                 specification
1588                 environment
1589                 debug
1590                 is_debug
1591                 input
1592                 builds
1593                 output
1594                 tables
1595                 plots
1596                 files
1597                 static
1598
1599
1600     input_data_parser.py
1601
1602         class InputData
1603
1604             Methods:
1605                 read_data
1606                 filter_data
1607
1608             Getters:
1609                 data
1610                 metadata
1611                 suites
1612                 tests
1613
1614
1615     environment.py
1616
1617         Functions:
1618             clean_environment
1619
1620         class Environment
1621
1622             Methods:
1623                 set_environment
1624
1625             Getters:
1626                 environment
1627
1628
1629     input_data_files.py
1630
1631         Functions:
1632             download_data_files
1633             unzip_files
1634
1635
1636     generator_tables.py
1637
1638         Functions:
1639             generate_tables
1640
1641         Functions implementing algorithms to generate particular types of
1642         tables (called by the function "generate_tables"):
1643             table_details
1644             table_performance_improvements
1645
1646
1647     generator_plots.py
1648
1649         Functions:
1650             generate_plots
1651
1652         Functions implementing algorithms to generate particular types of
1653         plots (called by the function "generate_plots"):
1654             plot_performance_box
1655             plot_latency_box
1656
1657
1658     generator_files.py
1659
1660         Functions:
1661             generate_files
1662
1663         Functions implementing algorithms to generate particular types of
1664         files (called by the function "generate_files"):
1665             file_test_results
1666
1667
1668     report.py
1669
1670         Functions:
1671             generate_report
1672
1673         Functions implementing algorithms to generate particular types of
1674         report (called by the function "generate_report"):
1675             generate_html_report
1676             generate_pdf_report
1677
1678         Other functions called by the function "generate_report":
1679             archive_input_data
1680             archive_report
1681
1682
1683 PAL functional diagram
1684 ``````````````````````
1685
1686 .. only:: latex
1687
1688     .. raw:: latex
1689
1690         \begin{figure}[H]
1691             \centering
1692                 \graphicspath{{../_tmp/src/csit_framework_documentation/}}
1693                 \includegraphics[width=0.90\textwidth]{pal_func_diagram}
1694                 \label{fig:pal_func_diagram}
1695         \end{figure}
1696
1697 .. only:: html
1698
1699     .. figure:: pal_func_diagram.svg
1700         :alt: PAL functional diagram
1701         :align: center
1702
1703
1704 How to add an element
1705 `````````````````````
1706
1707 Element can be added by adding it's model to the specification file. If
1708 the element is to be generated by an existing algorithm, only it's
1709 parameters must be set.
1710
1711 If a brand new type of element needs to be added, also the algorithm
1712 must be implemented. Element generation algorithms are implemented in
1713 the files with names starting with "generator" prefix. The name of the
1714 function implementing the algorithm and the name of algorithm in the
1715 specification file have to be the same.