resources/tools/presentation/doc/pal_lld.rst

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