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