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