CSIT-834: Add HLD picture
[csit.git] / 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.

©2016 FD.io a Linux Foundation Collaborative Project. All Rights Reserved.
Linux Foundation is a registered trademark of The Linux Foundation. Linux is a registered trademark of Linus Torvalds.
Please see our privacy policy and terms of use.