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