resources/tools/presentation/doc/pal_lld.rst

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