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