9c2446ea9102100442a12d4d75feb75a889599e1
[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
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.

©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.