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             \includesvg[width=0.90\textwidth]{../_tmp/src/csit_framework_documentation/pal_layers}
  47             \label{fig:pal_layers}
  48         \end{figure}
  49
  50 .. only:: html
  51
  52     .. figure:: pal_layers.svg
  53         :alt: PAL Layers
  54         :align: center
  55
  56 Data
  57 ----
  58
  59 Report Specification
  60 ````````````````````
  61
  62 The report specification file defines which data is used and which outputs are
  63 generated. It is human readable and structured. It is easy to add / remove /
  64 change items. The specification includes:
  65
  66  - Specification of the environment.
  67  - Configuration of debug mode (optional).
  68  - Specification of input data (jobs, builds, files, ...).
  69  - Specification of the output.
  70  - What and how is generated:
  71    - What: plots, tables.
  72    - How: specification of all properties and parameters.
  73  - .yaml format.
  74
  75 Structure of the specification file
  76 '''''''''''''''''''''''''''''''''''
  77
  78 The specification file is organized as a list of dictionaries distinguished by
  79 the type:
  80
  81 ::
  82
  83     -
  84       type: "environment"
  85     -
  86       type: "configuration"
  87     -
  88       type: "debug"
  89     -
  90       type: "static"
  91     -
  92       type: "input"
  93     -
  94       type: "output"
  95     -
  96       type: "table"
  97     -
  98       type: "plot"
  99     -
 100       type: "file"
 101
 102 Each type represents a section. The sections "environment", "debug", "static",
 103 "input" and "output" are listed only once in the specification; "table", "file"
 104 and "plot" can be there multiple times.
 105
 106 Sections "debug", "table", "file" and "plot" are optional.
 107
 108 Table(s), files(s) and plot(s) are referred as "elements" in this text. It is
 109 possible to define and implement other elements if needed.
 110
 111
 112 Section: Environment
 113 ''''''''''''''''''''
 114
 115 This section has the following parts:
 116
 117  - type: "environment" - says that this is the section "environment".
 118  - configuration - configuration of the PAL.
 119  - paths - paths used by the PAL.
 120  - urls - urls pointing to the data sources.
 121  - make-dirs - a list of the directories to be created by the PAL while
 122    preparing the environment.
 123  - remove-dirs - a list of the directories to be removed while cleaning the
 124    environment.
 125  - build-dirs - a list of the directories where the results are stored.
 126
 127 The structure of the section "Environment" is as follows (example):
 128
 129 ::
 130
 131     -
 132       type: "environment"
 133       configuration:
 134         # Debug mode:
 135         # - Skip:
 136         #   - Download of input data files
 137         # - Do:
 138         #   - Read data from given zip / xml files
 139         #   - Set the configuration as it is done in normal mode
 140         # If the section "type: debug" is missing, CFG[DEBUG] is set to 0.
 141         CFG[DEBUG]: 0
 142
 143       paths:
 144         # Top level directories:
 145         ## Working directory
 146         DIR[WORKING]: "_tmp"
 147         ## Build directories
 148         DIR[BUILD,HTML]: "_build"
 149         DIR[BUILD,LATEX]: "_build_latex"
 150
 151         # Static .rst files
 152         DIR[RST]: "../../../docs/report"
 153
 154         # Working directories
 155         ## Input data files (.zip, .xml)
 156         DIR[WORKING,DATA]: "{DIR[WORKING]}/data"
 157         ## Static source files from git
 158         DIR[WORKING,SRC]: "{DIR[WORKING]}/src"
 159         DIR[WORKING,SRC,STATIC]: "{DIR[WORKING,SRC]}/_static"
 160
 161         # Static html content
 162         DIR[STATIC]: "{DIR[BUILD,HTML]}/_static"
 163         DIR[STATIC,VPP]: "{DIR[STATIC]}/vpp"
 164         DIR[STATIC,DPDK]: "{DIR[STATIC]}/dpdk"
 165         DIR[STATIC,ARCH]: "{DIR[STATIC]}/archive"
 166
 167         # Detailed test results
 168         DIR[DTR]: "{DIR[WORKING,SRC]}/detailed_test_results"
 169         DIR[DTR,PERF,DPDK]: "{DIR[DTR]}/dpdk_performance_results"
 170         DIR[DTR,PERF,VPP]: "{DIR[DTR]}/vpp_performance_results"
 171         DIR[DTR,PERF,HC]: "{DIR[DTR]}/honeycomb_performance_results"
 172         DIR[DTR,FUNC,VPP]: "{DIR[DTR]}/vpp_functional_results"
 173         DIR[DTR,FUNC,HC]: "{DIR[DTR]}/honeycomb_functional_results"
 174         DIR[DTR,FUNC,NSHSFC]: "{DIR[DTR]}/nshsfc_functional_results"
 175         DIR[DTR,PERF,VPP,IMPRV]: "{DIR[WORKING,SRC]}/vpp_performance_tests/performance_improvements"
 176
 177         # Detailed test configurations
 178         DIR[DTC]: "{DIR[WORKING,SRC]}/test_configuration"
 179         DIR[DTC,PERF,VPP]: "{DIR[DTC]}/vpp_performance_configuration"
 180         DIR[DTC,FUNC,VPP]: "{DIR[DTC]}/vpp_functional_configuration"
 181
 182         # Detailed tests operational data
 183         DIR[DTO]: "{DIR[WORKING,SRC]}/test_operational_data"
 184         DIR[DTO,PERF,VPP]: "{DIR[DTO]}/vpp_performance_operational_data"
 185
 186         # .css patch file to fix tables generated by Sphinx
 187         DIR[CSS_PATCH_FILE]: "{DIR[STATIC]}/theme_overrides.css"
 188         DIR[CSS_PATCH_FILE2]: "{DIR[WORKING,SRC,STATIC]}/theme_overrides.css"
 189
 190       urls:
 191         URL[JENKINS,CSIT]: "https://jenkins.fd.io/view/csit/job"
 192         URL[JENKINS,HC]: "https://jenkins.fd.io/view/hc2vpp/job"
 193
 194       make-dirs:
 195       # List the directories which are created while preparing the environment.
 196       # All directories MUST be defined in "paths" section.
 197       - "DIR[WORKING,DATA]"
 198       - "DIR[STATIC,VPP]"
 199       - "DIR[STATIC,DPDK]"
 200       - "DIR[STATIC,ARCH]"
 201       - "DIR[BUILD,LATEX]"
 202       - "DIR[WORKING,SRC]"
 203       - "DIR[WORKING,SRC,STATIC]"
 204
 205       remove-dirs:
 206       # List the directories which are deleted while cleaning the environment.
 207       # All directories MUST be defined in "paths" section.
 208       #- "DIR[BUILD,HTML]"
 209
 210       build-dirs:
 211       # List the directories where the results (build) is stored.
 212       # All directories MUST be defined in "paths" section.
 213       - "DIR[BUILD,HTML]"
 214       - "DIR[BUILD,LATEX]"
 215
 216 It is possible to use defined items in the definition of other items, e.g.:
 217
 218 ::
 219
 220     DIR[WORKING,DATA]: "{DIR[WORKING]}/data"
 221
 222 will be automatically changed to
 223
 224 ::
 225
 226     DIR[WORKING,DATA]: "_tmp/data"
 227
 228
 229 Section: Configuration
 230 ''''''''''''''''''''''
 231
 232 This section specifies the groups of parameters which are repeatedly used in the
 233 elements defined later in the specification file. It has the following parts:
 234
 235  - data sets - Specification of data sets used later in element's specifications
 236    to define the input data.
 237  - plot layouts - Specification of plot layouts used later in plots'
 238    specifications to define the plot layout.
 239
 240 The structure of the section "Configuration" is as follows (example):
 241
 242 ::
 243
 244     -
 245       type: "configuration"
 246       data-sets:
 247         plot-vpp-throughput-latency:
 248           csit-vpp-perf-1710-all:
 249           - 11
 250           - 12
 251           - 13
 252           - 14
 253           - 15
 254           - 16
 255           - 17
 256           - 18
 257           - 19
 258           - 20
 259         vpp-perf-results:
 260           csit-vpp-perf-1710-all:
 261           - 20
 262           - 23
 263       plot-layouts:
 264         plot-throughput:
 265           xaxis:
 266             autorange: True
 267             autotick: False
 268             fixedrange: False
 269             gridcolor: "rgb(238, 238, 238)"
 270             linecolor: "rgb(238, 238, 238)"
 271             linewidth: 1
 272             showgrid: True
 273             showline: True
 274             showticklabels: True
 275             tickcolor: "rgb(238, 238, 238)"
 276             tickmode: "linear"
 277             title: "Indexed Test Cases"
 278             zeroline: False
 279           yaxis:
 280             gridcolor: "rgb(238, 238, 238)'"
 281             hoverformat: ".4s"
 282             linecolor: "rgb(238, 238, 238)"
 283             linewidth: 1
 284             range: []
 285             showgrid: True
 286             showline: True
 287             showticklabels: True
 288             tickcolor: "rgb(238, 238, 238)"
 289             title: "Packets Per Second [pps]"
 290             zeroline: False
 291           boxmode: "group"
 292           boxgroupgap: 0.5
 293           autosize: False
 294           margin:
 295             t: 50
 296             b: 20
 297             l: 50
 298             r: 20
 299           showlegend: True
 300           legend:
 301             orientation: "h"
 302           width: 700
 303           height: 1000
 304
 305 The definitions from this sections are used in the elements, e.g.:
 306
 307 ::
 308
 309     -
 310       type: "plot"
 311       title: "VPP Performance 64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
 312       algorithm: "plot_performance_box"
 313       output-file-type: ".html"
 314       output-file: "{DIR[STATIC,VPP]}/64B-1t1c-l2-sel1-ndrdisc"
 315       data:
 316         "plot-vpp-throughput-latency"
 317       filter: "'64B' and ('BASE' or 'SCALE') and 'NDRDISC' and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
 318       parameters:
 319       - "throughput"
 320       - "parent"
 321       traces:
 322         hoverinfo: "x+y"
 323         boxpoints: "outliers"
 324         whiskerwidth: 0
 325       layout:
 326         title: "64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
 327         layout:
 328           "plot-throughput"
 329
 330
 331 Section: Debug mode
 332 '''''''''''''''''''
 333
 334 This section is optional as it configures the debug mode. It is used if one
 335 does not want to download input data files and use local files instead.
 336
 337 If the debug mode is configured, the "input" section is ignored.
 338
 339 This section has the following parts:
 340
 341  - type: "debug" - says that this is the section "debug".
 342  - general:
 343
 344    - input-format - xml or zip.
 345    - extract - if "zip" is defined as the input format, this file is extracted
 346      from the zip file, otherwise this parameter is ignored.
 347
 348  - builds - list of builds from which the data is used. Must include a job
 349    name as a key and then a list of builds and their output files.
 350
 351 The structure of the section "Debug" is as follows (example):
 352
 353 ::
 354
 355     -
 356       type: "debug"
 357       general:
 358         input-format: "zip"  # zip or xml
 359         extract: "robot-plugin/output.xml"  # Only for zip
 360       builds:
 361         # The files must be in the directory DIR[WORKING,DATA]
 362         csit-dpdk-perf-1707-all:
 363         -
 364           build: 10
 365           file: "csit-dpdk-perf-1707-all__10.xml"
 366         -
 367           build: 9
 368           file: "csit-dpdk-perf-1707-all__9.xml"
 369         csit-nsh_sfc-verify-func-1707-ubuntu1604-virl:
 370         -
 371           build: 2
 372           file: "csit-nsh_sfc-verify-func-1707-ubuntu1604-virl-2.xml"
 373         csit-vpp-functional-1707-ubuntu1604-virl:
 374         -
 375           build: lastSuccessfulBuild
 376           file: "csit-vpp-functional-1707-ubuntu1604-virl-lastSuccessfulBuild.xml"
 377         hc2vpp-csit-integration-1707-ubuntu1604:
 378         -
 379           build: lastSuccessfulBuild
 380           file: "hc2vpp-csit-integration-1707-ubuntu1604-lastSuccessfulBuild.xml"
 381         csit-vpp-perf-1707-all:
 382         -
 383           build: 16
 384           file: "csit-vpp-perf-1707-all__16__output.xml"
 385         -
 386           build: 17
 387           file: "csit-vpp-perf-1707-all__17__output.xml"
 388
 389
 390 Section: Static
 391 '''''''''''''''
 392
 393 This section defines the static content which is stored in git and will be used
 394 as a source to generate the report.
 395
 396 This section has these parts:
 397
 398  - type: "static" - says that this section is the "static".
 399  - src-path - path to the static content.
 400  - dst-path - destination path where the static content is copied and then
 401    processed.
 402
 403 ::
 404     -
 405       type: "static"
 406       src-path: "{DIR[RST]}"
 407       dst-path: "{DIR[WORKING,SRC]}"
 408
 409
 410 Section: Input
 411 ''''''''''''''
 412
 413 This section defines the data used to generate elements. It is mandatory
 414 if the debug mode is not used.
 415
 416 This section has the following parts:
 417
 418  - type: "input" - says that this section is the "input".
 419  - general - parameters common to all builds:
 420
 421    - file-name: file to be downloaded.
 422    - file-format: format of the downloaded file, ".zip" or ".xml" are supported.
 423    - download-path: path to be added to url pointing to the file, e.g.:
 424      "{job}/{build}/robot/report/*zip*/{filename}"; {job}, {build} and
 425      {filename} are replaced by proper values defined in this section.
 426    - extract: file to be extracted from downloaded zip file, e.g.: "output.xml";
 427      if xml file is downloaded, this parameter is ignored.
 428
 429  - builds - list of jobs (keys) and numbers of builds which output data will be
 430    downloaded.
 431
 432 The structure of the section "Input" is as follows (example from 17.07 report):
 433
 434 ::
 435
 436     -
 437       type: "input"  # Ignored in debug mode
 438       general:
 439         file-name: "robot-plugin.zip"
 440         file-format: ".zip"
 441         download-path: "{job}/{build}/robot/report/*zip*/{filename}"
 442         extract: "robot-plugin/output.xml"
 443       builds:
 444         csit-vpp-perf-1707-all:
 445         - 9
 446         - 10
 447         - 13
 448         - 14
 449         - 15
 450         - 16
 451         - 17
 452         - 18
 453         - 19
 454         - 21
 455         - 22
 456         csit-dpdk-perf-1707-all:
 457         - 1
 458         - 2
 459         - 3
 460         - 4
 461         - 5
 462         - 6
 463         - 7
 464         - 8
 465         - 9
 466         - 10
 467         csit-vpp-functional-1707-ubuntu1604-virl:
 468         - lastSuccessfulBuild
 469         hc2vpp-csit-perf-master-ubuntu1604:
 470         - 8
 471         - 9
 472         hc2vpp-csit-integration-1707-ubuntu1604:
 473         - lastSuccessfulBuild
 474         csit-nsh_sfc-verify-func-1707-ubuntu1604-virl:
 475         - 2
 476
 477
 478 Section: Output
 479 '''''''''''''''
 480
 481 This section specifies which format(s) will be generated (html, pdf) and which
 482 versions will be generated for each format.
 483
 484 This section has the following parts:
 485
 486  - type: "output" - says that this section is the "output".
 487  - format: html or pdf.
 488  - version: defined for each format separately.
 489
 490 The structure of the section "Output" is as follows (example):
 491
 492 ::
 493
 494     -
 495       type: "output"
 496       format:
 497         html:
 498         - full
 499         pdf:
 500         - full
 501         - minimal
 502
 503 TODO: define the names of versions
 504
 505
 506 Content of "minimal" version
 507 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 508
 509 TODO: define the name and content of this version
 510
 511
 512 Section: Table
 513 ''''''''''''''
 514
 515 This section defines a table to be generated. There can be 0 or more "table"
 516 sections.
 517
 518 This section has the following parts:
 519
 520  - type: "table" - says that this section defines a table.
 521  - title: Title of the table.
 522  - algorithm: Algorithm which is used to generate the table. The other
 523    parameters in this section must provide all information needed by the used
 524    algorithm.
 525  - template: (optional) a .csv file used as a template while generating the
 526    table.
 527  - output-file-ext: extension of the output file.
 528  - output-file: file which the table will be written to.
 529  - columns: specification of table columns:
 530
 531    - title: The title used in the table header.
 532    - data: Specification of the data, it has two parts - command and arguments:
 533
 534      - command:
 535
 536        - template - take the data from template, arguments:
 537
 538          - number of column in the template.
 539
 540        - data - take the data from the input data, arguments:
 541
 542          - jobs and builds which data will be used.
 543
 544        - operation - performs an operation with the data already in the table,
 545          arguments:
 546
 547          - operation to be done, e.g.: mean, stdev, relative_change (compute
 548            the relative change between two columns) and display number of data
 549            samples ~= number of test jobs. The operations are implemented in the
 550            utils.py
 551            TODO: Move from utils,py to e.g. operations.py
 552          - numbers of columns which data will be used (optional).
 553
 554  - data: Specify the jobs and builds which data is used to generate the table.
 555  - filter: filter based on tags applied on the input data, if "template" is
 556    used, filtering is based on the template.
 557  - parameters: Only these parameters will be put to the output data structure.
 558
 559 The structure of the section "Table" is as follows (example of
 560 "table_performance_improvements"):
 561
 562 ::
 563
 564     -
 565       type: "table"
 566       title: "Performance improvements"
 567       algorithm: "table_performance_improvements"
 568       template: "{DIR[DTR,PERF,VPP,IMPRV]}/tmpl_performance_improvements.csv"
 569       output-file-ext: ".csv"
 570       output-file: "{DIR[DTR,PERF,VPP,IMPRV]}/performance_improvements"
 571       columns:
 572       -
 573         title: "VPP Functionality"
 574         data: "template 1"
 575       -
 576         title: "Test Name"
 577         data: "template 2"
 578       -
 579         title: "VPP-16.09 mean [Mpps]"
 580         data: "template 3"
 581       -
 582         title: "VPP-17.01 mean [Mpps]"
 583         data: "template 4"
 584       -
 585         title: "VPP-17.04 mean [Mpps]"
 586         data: "template 5"
 587       -
 588         title: "VPP-17.07 mean [Mpps]"
 589         data: "data csit-vpp-perf-1707-all mean"
 590       -
 591         title: "VPP-17.07 stdev [Mpps]"
 592         data: "data csit-vpp-perf-1707-all stdev"
 593       -
 594         title: "17.04 to 17.07 change [%]"
 595         data: "operation relative_change 5 4"
 596       data:
 597         csit-vpp-perf-1707-all:
 598         - 9
 599         - 10
 600         - 13
 601         - 14
 602         - 15
 603         - 16
 604         - 17
 605         - 18
 606         - 19
 607         - 21
 608       filter: "template"
 609       parameters:
 610       - "throughput"
 611
 612 Example of "table_details" which generates "Detailed Test Results - VPP
 613 Performance Results":
 614
 615 ::
 616
 617     -
 618       type: "table"
 619       title: "Detailed Test Results - VPP Performance Results"
 620       algorithm: "table_details"
 621       output-file-ext: ".csv"
 622       output-file: "{DIR[WORKING]}/vpp_performance_results"
 623       columns:
 624       -
 625         title: "Name"
 626         data: "data test_name"
 627       -
 628         title: "Documentation"
 629         data: "data test_documentation"
 630       -
 631         title: "Status"
 632         data: "data test_msg"
 633       data:
 634         csit-vpp-perf-1707-all:
 635         - 17
 636       filter: "all"
 637       parameters:
 638       - "parent"
 639       - "doc"
 640       - "msg"
 641
 642 Example of "table_details" which generates "Test configuration - VPP Performance
 643 Test Configs":
 644
 645 ::
 646
 647     -
 648       type: "table"
 649       title: "Test configuration - VPP Performance Test Configs"
 650       algorithm: "table_details"
 651       output-file-ext: ".csv"
 652       output-file: "{DIR[WORKING]}/vpp_test_configuration"
 653       columns:
 654       -
 655         title: "Name"
 656         data: "data name"
 657       -
 658         title: "VPP API Test (VAT) Commands History - Commands Used Per Test Case"
 659         data: "data show-run"
 660       data:
 661         csit-vpp-perf-1707-all:
 662         - 17
 663       filter: "all"
 664       parameters:
 665       - "parent"
 666       - "name"
 667       - "show-run"
 668
 669
 670 Section: Plot
 671 '''''''''''''
 672
 673 This section defines a plot to be generated. There can be 0 or more "plot"
 674 sections.
 675
 676 This section has these parts:
 677
 678  - type: "plot" - says that this section defines a plot.
 679  - title: Plot title used in the logs. Title which is displayed is in the
 680    section "layout".
 681  - output-file-type: format of the output file.
 682  - output-file: file which the plot will be written to.
 683  - algorithm: Algorithm used to generate the plot. The other parameters in this
 684    section must provide all information needed by plot.ly to generate the plot.
 685    For example:
 686
 687    - traces
 688    - layout
 689
 690    - These parameters are transparently passed to plot.ly.
 691
 692  - data: Specify the jobs and numbers of builds which data is used to generate
 693    the plot.
 694  - filter: filter applied on the input data.
 695  - parameters: Only these parameters will be put to the output data structure.
 696
 697 The structure of the section "Plot" is as follows (example of a plot showing
 698 throughput in a chart box-with-whiskers):
 699
 700 ::
 701
 702     -
 703       type: "plot"
 704       title: "VPP Performance 64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
 705       algorithm: "plot_performance_box"
 706       output-file-type: ".html"
 707       output-file: "{DIR[STATIC,VPP]}/64B-1t1c-l2-sel1-ndrdisc"
 708       data:
 709         csit-vpp-perf-1707-all:
 710         - 9
 711         - 10
 712         - 13
 713         - 14
 714         - 15
 715         - 16
 716         - 17
 717         - 18
 718         - 19
 719         - 21
 720       # Keep this formatting, the filter is enclosed with " (quotation mark) and
 721       # each tag is enclosed with ' (apostrophe).
 722       filter: "'64B' and 'BASE' and 'NDRDISC' and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
 723       parameters:
 724       - "throughput"
 725       - "parent"
 726       traces:
 727         hoverinfo: "x+y"
 728         boxpoints: "outliers"
 729         whiskerwidth: 0
 730       layout:
 731         title: "64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
 732         xaxis:
 733           autorange: True
 734           autotick: False
 735           fixedrange: False
 736           gridcolor: "rgb(238, 238, 238)"
 737           linecolor: "rgb(238, 238, 238)"
 738           linewidth: 1
 739           showgrid: True
 740           showline: True
 741           showticklabels: True
 742           tickcolor: "rgb(238, 238, 238)"
 743           tickmode: "linear"
 744           title: "Indexed Test Cases"
 745           zeroline: False
 746         yaxis:
 747           gridcolor: "rgb(238, 238, 238)'"
 748           hoverformat: ".4s"
 749           linecolor: "rgb(238, 238, 238)"
 750           linewidth: 1
 751           range: []
 752           showgrid: True
 753           showline: True
 754           showticklabels: True
 755           tickcolor: "rgb(238, 238, 238)"
 756           title: "Packets Per Second [pps]"
 757           zeroline: False
 758         boxmode: "group"
 759         boxgroupgap: 0.5
 760         autosize: False
 761         margin:
 762           t: 50
 763           b: 20
 764           l: 50
 765           r: 20
 766         showlegend: True
 767         legend:
 768           orientation: "h"
 769         width: 700
 770         height: 1000
 771
 772 The structure of the section "Plot" is as follows (example of a plot showing
 773 latency in a box chart):
 774
 775 ::
 776
 777     -
 778       type: "plot"
 779       title: "VPP Latency 64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
 780       algorithm: "plot_latency_box"
 781       output-file-type: ".html"
 782       output-file: "{DIR[STATIC,VPP]}/64B-1t1c-l2-sel1-ndrdisc-lat50"
 783       data:
 784         csit-vpp-perf-1707-all:
 785         - 9
 786         - 10
 787         - 13
 788         - 14
 789         - 15
 790         - 16
 791         - 17
 792         - 18
 793         - 19
 794         - 21
 795       filter: "'64B' and 'BASE' and 'NDRDISC' and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
 796       parameters:
 797       - "latency"
 798       - "parent"
 799       traces:
 800         boxmean: False
 801       layout:
 802         title: "64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
 803         xaxis:
 804           autorange: True
 805           autotick: False
 806           fixedrange: False
 807           gridcolor: "rgb(238, 238, 238)"
 808           linecolor: "rgb(238, 238, 238)"
 809           linewidth: 1
 810           showgrid: True
 811           showline: True
 812           showticklabels: True
 813           tickcolor: "rgb(238, 238, 238)"
 814           tickmode: "linear"
 815           title: "Indexed Test Cases"
 816           zeroline: False
 817         yaxis:
 818           gridcolor: "rgb(238, 238, 238)'"
 819           hoverformat: ""
 820           linecolor: "rgb(238, 238, 238)"
 821           linewidth: 1
 822           range: []
 823           showgrid: True
 824           showline: True
 825           showticklabels: True
 826           tickcolor: "rgb(238, 238, 238)"
 827           title: "Latency min/avg/max [uSec]"
 828           zeroline: False
 829         boxmode: "group"
 830         boxgroupgap: 0.5
 831         autosize: False
 832         margin:
 833           t: 50
 834           b: 20
 835           l: 50
 836           r: 20
 837         showlegend: True
 838         legend:
 839           orientation: "h"
 840         width: 700
 841         height: 1000
 842
 843
 844 Section: file
 845 '''''''''''''
 846
 847 This section defines a file to be generated. There can be 0 or more "file"
 848 sections.
 849
 850 This section has the following parts:
 851
 852  - type: "file" - says that this section defines a file.
 853  - title: Title of the table.
 854  - algorithm: Algorithm which is used to generate the file. The other
 855    parameters in this section must provide all information needed by the used
 856    algorithm.
 857  - output-file-ext: extension of the output file.
 858  - output-file: file which the file will be written to.
 859  - file-header: The header of the generated .rst file.
 860  - dir-tables: The directory with the tables.
 861  - data: Specify the jobs and builds which data is used to generate the table.
 862  - filter: filter based on tags applied on the input data, if "all" is
 863    used, no filtering is done.
 864  - parameters: Only these parameters will be put to the output data structure.
 865  - chapters: the hierarchy of chapters in the generated file.
 866  - start-level: the level of the the top-level chapter.
 867
 868 The structure of the section "file" is as follows (example):
 869
 870 ::
 871
 872     -
 873       type: "file"
 874       title: "VPP Performance Results"
 875       algorithm: "file_test_results"
 876       output-file-ext: ".rst"
 877       output-file: "{DIR[DTR,PERF,VPP]}/vpp_performance_results"
 878       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"
 879       dir-tables: "{DIR[DTR,PERF,VPP]}"
 880       data:
 881         csit-vpp-perf-1707-all:
 882         - 22
 883       filter: "all"
 884       parameters:
 885       - "name"
 886       - "doc"
 887       - "level"
 888       data-start-level: 2  # 0, 1, 2, ...
 889       chapters-start-level: 2  # 0, 1, 2, ...
 890
 891
 892 Static content
 893 ``````````````
 894
 895  - Manually created / edited files.
 896  - .rst files, static .csv files, static pictures (.svg), ...
 897  - Stored in CSIT git repository.
 898
 899 No more details about the static content in this document.
 900
 901
 902 Data to process
 903 ```````````````
 904
 905 The PAL processes tests results and other information produced by Jenkins jobs.
 906 The data are now stored as robot results in Jenkins (TODO: store the data in
 907 nexus) either as .zip and / or .xml files.
 908
 909
 910 Data processing
 911 ---------------
 912
 913 As the first step, the data are downloaded and stored locally (typically on a
 914 Jenkins slave). If .zip files are used, the given .xml files are extracted for
 915 further processing.
 916
 917 Parsing of the .xml files is performed by a class derived from
 918 "robot.api.ResultVisitor", only necessary methods are overridden. All and only
 919 necessary data is extracted from .xml file and stored in a structured form.
 920
 921 The parsed data are stored as the multi-indexed pandas.Series data type. Its
 922 structure is as follows:
 923
 924 ::
 925
 926     <job name>
 927       <build>
 928         <metadata>
 929         <suites>
 930         <tests>
 931
 932 "job name", "build", "metadata", "suites", "tests" are indexes to access the
 933 data. For example:
 934
 935 ::
 936
 937     data =
 938
 939     job 1 name:
 940       build 1:
 941         metadata: metadata
 942         suites: suites
 943         tests: tests
 944       ...
 945       build N:
 946         metadata: metadata
 947         suites: suites
 948         tests: tests
 949     ...
 950     job M name:
 951       build 1:
 952         metadata: metadata
 953         suites: suites
 954         tests: tests
 955       ...
 956       build N:
 957         metadata: metadata
 958         suites: suites
 959         tests: tests
 960
 961 Using indexes data["job 1 name"]["build 1"]["tests"] (e.g.:
 962 data["csit-vpp-perf-1704-all"]["17"]["tests"]) we get a list of all tests with
 963 all tests data.
 964
 965 Data will not be accessible directly using indexes, but using getters and
 966 filters.
 967
 968 **Structure of metadata:**
 969
 970 ::
 971
 972     "metadata": {
 973         "version": "VPP version",
 974         "job": "Jenkins job name"
 975         "build": "Information about the build"
 976     },
 977
 978 **Structure of suites:**
 979
 980 ::
 981
 982     "suites": {
 983         "Suite name 1": {
 984             "doc": "Suite 1 documentation"
 985             "parent": "Suite 1 parent"
 986         }
 987         "Suite name N": {
 988             "doc": "Suite N documentation"
 989             "parent": "Suite N parent"
 990         }
 991
 992 **Structure of tests:**
 993
 994 Performance tests:
 995
 996 ::
 997
 998     "tests": {
 999         "ID": {
1000             "name": "Test name",
1001             "parent": "Name of the parent of the test",
1002             "doc": "Test documentation"
1003             "msg": "Test message"
1004             "tags": ["tag 1", "tag 2", "tag n"],
1005             "type": "PDR" | "NDR",
1006             "throughput": {
1007                 "value": int,
1008                 "unit": "pps" | "bps" | "percentage"
1009             },
1010             "latency": {
1011                 "direction1": {
1012                     "100": {
1013                         "min": int,
1014                         "avg": int,
1015                         "max": int
1016                     },
1017                     "50": {  # Only for NDR
1018                         "min": int,
1019                         "avg": int,
1020                         "max": int
1021                     },
1022                     "10": {  # Only for NDR
1023                         "min": int,
1024                         "avg": int,
1025                         "max": int
1026                     }
1027                 },
1028                 "direction2": {
1029                     "100": {
1030                         "min": int,
1031                         "avg": int,
1032                         "max": int
1033                     },
1034                     "50": {  # Only for NDR
1035                         "min": int,
1036                         "avg": int,
1037                         "max": int
1038                     },
1039                     "10": {  # Only for NDR
1040                         "min": int,
1041                         "avg": int,
1042                         "max": int
1043                     }
1044                 }
1045             },
1046             "lossTolerance": "lossTolerance"  # Only for PDR
1047             "vat-history": "DUT1 and DUT2 VAT History"
1048             },
1049             "show-run": "Show Run"
1050         },
1051         "ID" {
1052             # next test
1053         }
1054
1055 Functional tests:
1056
1057 ::
1058
1059     "tests": {
1060         "ID": {
1061             "name": "Test name",
1062             "parent": "Name of the parent of the test",
1063             "doc": "Test documentation"
1064             "msg": "Test message"
1065             "tags": ["tag 1", "tag 2", "tag n"],
1066             "vat-history": "DUT1 and DUT2 VAT History"
1067             "show-run": "Show Run"
1068             "status": "PASS" | "FAIL"
1069         },
1070         "ID" {
1071             # next test
1072         }
1073     }
1074
1075 Note: ID is the lowercase full path to the test.
1076
1077
1078 Data filtering
1079 ``````````````
1080
1081 The first step when generating an element is getting the data needed to
1082 construct the element. The data are filtered from the processed input data.
1083
1084 The data filtering is based on:
1085
1086  - job name(s).
1087  - build number(s).
1088  - tag(s).
1089  - required data - only this data is included in the output.
1090
1091 WARNING: The filtering is based on tags, so be careful with tagging.
1092
1093 For example, the element which specification includes:
1094
1095 ::
1096
1097     data:
1098       csit-vpp-perf-1707-all:
1099       - 9
1100       - 10
1101       - 13
1102       - 14
1103       - 15
1104       - 16
1105       - 17
1106       - 18
1107       - 19
1108       - 21
1109     filter:
1110       - "'64B' and 'BASE' and 'NDRDISC' and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
1111
1112 will be constructed using data from the job "csit-vpp-perf-1707-all", for all listed
1113 builds and the tests with the list of tags matching the filter conditions.
1114
1115 The output data structure for filtered test data is:
1116
1117 ::
1118
1119     - job 1
1120       - build 1
1121         - test 1
1122           - parameter 1
1123           - parameter 2
1124           ...
1125           - parameter n
1126         ...
1127         - test n
1128         ...
1129       ...
1130       - build n
1131     ...
1132     - job n
1133
1134
1135 Data analytics
1136 ``````````````
1137
1138 Data analytics part implements:
1139
1140  - methods to compute statistical data from the filtered input data.
1141  - trending.
1142
1143 Throughput Speedup Analysis - Multi-Core with Multi-Threading
1144 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
1145
1146 Throughput Speedup Analysis (TSA) calculates throughput speedup ratios
1147 for tested 1-, 2- and 4-core multi-threaded VPP configurations using the
1148 following formula:
1149
1150 ::
1151
1152                                 N_core_throughput
1153     N_core_throughput_speedup = -----------------
1154                                 1_core_throughput
1155
1156 Multi-core throughput speedup ratios are plotted in grouped bar graphs
1157 for throughput tests with 64B/78B frame size, with number of cores on
1158 X-axis and speedup ratio on Y-axis.
1159
1160 For better comparison multiple test results' data sets are plotted per
1161 each graph:
1162
1163     - graph type: grouped bars;
1164     - graph X-axis: (testcase index, number of cores);
1165     - graph Y-axis: speedup factor.
1166
1167 Subset of existing performance tests is covered by TSA graphs.
1168
1169 **Model for TSA:**
1170
1171 ::
1172
1173     -
1174       type: "plot"
1175       title: "TSA: 64B-*-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
1176       algorithm: "plot_throughput_speedup_analysis"
1177       output-file-type: ".html"
1178       output-file: "{DIR[STATIC,VPP]}/10ge2p1x520-64B-l2-tsa-ndrdisc"
1179       data:
1180         "plot-throughput-speedup-analysis"
1181       filter: "'NIC_Intel-X520-DA2' and '64B' and 'BASE' and 'NDRDISC' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
1182       parameters:
1183       - "throughput"
1184       - "parent"
1185       - "tags"
1186       layout:
1187         title: "64B-*-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
1188         layout:
1189           "plot-throughput-speedup-analysis"
1190
1191
1192 Advanced data analytics
1193 ```````````````````````
1194
1195 In the future advanced data analytics (ADA) will be added to analyze the
1196 telemetry data collected from SUT telemetry sources and correlate it to
1197 performance test results.
1198
1199 :TODO:
1200
1201     - describe the concept of ADA.
1202     - add specification.
1203
1204
1205 Data presentation
1206 -----------------
1207
1208 Generates the plots and tables according to the report models per
1209 specification file. The elements are generated using algorithms and data
1210 specified in their models.
1211
1212
1213 Tables
1214 ``````
1215
1216  - tables are generated by algorithms implemented in PAL, the model includes the
1217    algorithm and all necessary information.
1218  - output format: csv
1219  - generated tables are stored in specified directories and linked to .rst files.
1220
1221
1222 Plots
1223 `````
1224
1225  - `plot.ly <https://plot.ly/>`_ is currently used to generate plots, the model
1226    includes the type of plot and all the necessary information to render it.
1227  - output format: html.
1228  - generated plots are stored in specified directories and linked to .rst files.
1229
1230
1231 Report generation
1232 -----------------
1233
1234 Report is generated using Sphinx and Read_the_Docs template. PAL generates html
1235 and pdf formats. It is possible to define the content of the report by specifying
1236 the version (TODO: define the names and content of versions).
1237
1238
1239 The process
1240 ```````````
1241
1242 1. Read the specification.
1243 2. Read the input data.
1244 3. Process the input data.
1245 4. For element (plot, table, file) defined in specification:
1246
1247    a. Get the data needed to construct the element using a filter.
1248    b. Generate the element.
1249    c. Store the element.
1250
1251 5. Generate the report.
1252 6. Store the report (Nexus).
1253
1254 The process is model driven. The elementsâ€™ models (tables, plots, files and
1255 report itself) are defined in the specification file. Script reads the elementsâ€™
1256 models from specification file and generates the elements.
1257
1258 It is easy to add elements to be generated, if a new kind of element is
1259 required, only a new algorithm is implemented and integrated.
1260
1261
1262 API
1263 ---
1264
1265 List of modules, classes, methods and functions
1266 ```````````````````````````````````````````````
1267
1268 ::
1269
1270     specification_parser.py
1271
1272         class Specification
1273
1274             Methods:
1275                 read_specification
1276                 set_input_state
1277                 set_input_file_name
1278
1279             Getters:
1280                 specification
1281                 environment
1282                 debug
1283                 is_debug
1284                 input
1285                 builds
1286                 output
1287                 tables
1288                 plots
1289                 files
1290                 static
1291
1292
1293     input_data_parser.py
1294
1295         class InputData
1296
1297             Methods:
1298                 read_data
1299                 filter_data
1300
1301             Getters:
1302                 data
1303                 metadata
1304                 suites
1305                 tests
1306
1307
1308     environment.py
1309
1310         Functions:
1311             clean_environment
1312
1313         class Environment
1314
1315             Methods:
1316                 set_environment
1317
1318             Getters:
1319                 environment
1320
1321
1322     input_data_files.py
1323
1324         Functions:
1325             download_data_files
1326             unzip_files
1327
1328
1329     generator_tables.py
1330
1331         Functions:
1332             generate_tables
1333
1334         Functions implementing algorithms to generate particular types of
1335         tables (called by the function "generate_tables"):
1336             table_details
1337             table_performance_improvements
1338
1339
1340     generator_plots.py
1341
1342         Functions:
1343             generate_plots
1344
1345         Functions implementing algorithms to generate particular types of
1346         plots (called by the function "generate_plots"):
1347             plot_performance_box
1348             plot_latency_box
1349
1350
1351     generator_files.py
1352
1353         Functions:
1354             generate_files
1355
1356         Functions implementing algorithms to generate particular types of
1357         files (called by the function "generate_files"):
1358             file_test_results
1359
1360
1361     report.py
1362
1363         Functions:
1364             generate_report
1365
1366         Functions implementing algorithms to generate particular types of
1367         report (called by the function "generate_report"):
1368             generate_html_report
1369             generate_pdf_report
1370
1371         Other functions called by the function "generate_report":
1372             archive_input_data
1373             archive_report
1374
1375
1376 PAL functional diagram
1377 ``````````````````````
1378
1379 .. only:: latex
1380
1381     .. raw:: latex
1382
1383         \begin{figure}[H]
1384         \centering
1385             \includesvg[width=0.90\textwidth]{../_tmp/src/csit_framework_documentation/pal_func_diagram}
1386             \label{fig:pal_func_diagram}
1387         \end{figure}
1388
1389 .. only:: html
1390
1391     .. figure:: pal_func_diagram.svg
1392         :alt: PAL functional diagram
1393         :align: center
1394
1395
1396 How to add an element
1397 `````````````````````
1398
1399 Element can be added by adding its model to the specification file. If the
1400 element will be generated by an existing algorithm, only its parameters must be
1401 set.
1402
1403 If a brand new type of element will be added, also the algorithm must be
1404 implemented.
1405 The algorithms are implemented in the files which names start with "generator".
1406 The name of the function implementing the algorithm and the name of algorithm in
1407 the specification file had to be the same.