Report: CSIT Framework Documentation
[csit.git] / 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.

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