CSIT-902: Compare performance results before/after meltdown/spectre
[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
1113 listed builds and the tests with the list of tags matching the filter
1114 conditions.
1115
1116 The output data structure for filtered test data is:
1117
1118 ::
1119
1120     - job 1
1121       - build 1
1122         - test 1
1123           - parameter 1
1124           - parameter 2
1125           ...
1126           - parameter n
1127         ...
1128         - test n
1129         ...
1130       ...
1131       - build n
1132     ...
1133     - job n
1134
1135
1136 Data analytics
1137 ``````````````
1138
1139 Data analytics part implements:
1140
1141  - methods to compute statistical data from the filtered input data.
1142  - trending.
1143
1144 Throughput Speedup Analysis - Multi-Core with Multi-Threading
1145 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
1146
1147 Throughput Speedup Analysis (TSA) calculates throughput speedup ratios
1148 for tested 1-, 2- and 4-core multi-threaded VPP configurations using the
1149 following formula:
1150
1151 ::
1152
1153                                 N_core_throughput
1154     N_core_throughput_speedup = -----------------
1155                                 1_core_throughput
1156
1157 Multi-core throughput speedup ratios are plotted in grouped bar graphs
1158 for throughput tests with 64B/78B frame size, with number of cores on
1159 X-axis and speedup ratio on Y-axis.
1160
1161 For better comparison multiple test results' data sets are plotted per
1162 each graph:
1163
1164     - graph type: grouped bars;
1165     - graph X-axis: (testcase index, number of cores);
1166     - graph Y-axis: speedup factor.
1167
1168 Subset of existing performance tests is covered by TSA graphs.
1169
1170 **Model for TSA:**
1171
1172 ::
1173
1174     -
1175       type: "plot"
1176       title: "TSA: 64B-*-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
1177       algorithm: "plot_throughput_speedup_analysis"
1178       output-file-type: ".html"
1179       output-file: "{DIR[STATIC,VPP]}/10ge2p1x520-64B-l2-tsa-ndrdisc"
1180       data:
1181         "plot-throughput-speedup-analysis"
1182       filter: "'NIC_Intel-X520-DA2' and '64B' and 'BASE' and 'NDRDISC' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'"
1183       parameters:
1184       - "throughput"
1185       - "parent"
1186       - "tags"
1187       layout:
1188         title: "64B-*-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc"
1189         layout:
1190           "plot-throughput-speedup-analysis"
1191
1192
1193 Comparison of results from two sets of the same test executions
1194 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
1195
1196 This algorithm enables comparison of results coming from two sets of the
1197 same test executions. It is used to quantify performance changes across
1198 all tests after test environment changes e.g. Operating System
1199 upgrades/patches, Hardware changes.
1200
1201 It is assumed that each set of test executions includes multiple runs
1202 of the same tests, 10 or more, to verify test results repeatibility and
1203 to yield statistically meaningful results data.
1204
1205 Comparison results are presented in a table with a specified number of
1206 the best and the worst relative changes between the two sets. Following table
1207 columns are defined:
1208
1209     - name of the test;
1210     - throughput mean values of the reference set;
1211     - throughput standard deviation  of the reference set;
1212     - throughput mean values of the set to compare;
1213     - throughput standard deviation  of the set to compare;
1214     - relative change of the mean values.
1215
1216 **The model**
1217
1218 The model specifies:
1219
1220     - type: "table" - means this section defines a table.
1221     - title: Title of the table.
1222     - algorithm: Algorithm which is used to generate the table. The other
1223       parameters in this section must provide all information needed by the used
1224       algorithm.
1225     - output-file-ext: Extension of the output file.
1226     - output-file: File which the table will be written to.
1227     - reference - the builds which are used as the reference for comparison.
1228     - compare - the builds which are compared to the reference.
1229     - data: Specify the sources, jobs and builds, providing data for generating
1230       the table.
1231     - filter: Filter based on tags applied on the input data, if "template" is
1232       used, filtering is based on the template.
1233     - parameters: Only these parameters will be put to the output data
1234       structure.
1235     - nr-of-tests-shown: Number of the best and the worst tests presented in the
1236       table. Use 0 (zero) to present all tests.
1237
1238 *Example:*
1239
1240 ::
1241
1242     -
1243       type: "table"
1244       title: "Performance comparison"
1245       algorithm: "table_performance_comparison"
1246       output-file-ext: ".csv"
1247       output-file: "{DIR[DTR,PERF,VPP,IMPRV]}/vpp_performance_comparison"
1248       reference:
1249         title: "csit-vpp-perf-1801-all - 1"
1250         data:
1251           csit-vpp-perf-1801-all:
1252           - 1
1253           - 2
1254       compare:
1255         title: "csit-vpp-perf-1801-all - 2"
1256         data:
1257           csit-vpp-perf-1801-all:
1258           - 1
1259           - 2
1260       data:
1261         "vpp-perf-comparison"
1262       filter: "all"
1263       parameters:
1264       - "name"
1265       - "parent"
1266       - "throughput"
1267       nr-of-tests-shown: 20
1268
1269
1270 Advanced data analytics
1271 ```````````````````````
1272
1273 In the future advanced data analytics (ADA) will be added to analyze the
1274 telemetry data collected from SUT telemetry sources and correlate it to
1275 performance test results.
1276
1277 :TODO:
1278
1279     - describe the concept of ADA.
1280     - add specification.
1281
1282
1283 Data presentation
1284 -----------------
1285
1286 Generates the plots and tables according to the report models per
1287 specification file. The elements are generated using algorithms and data
1288 specified in their models.
1289
1290
1291 Tables
1292 ``````
1293
1294  - tables are generated by algorithms implemented in PAL, the model includes the
1295    algorithm and all necessary information.
1296  - output format: csv
1297  - generated tables are stored in specified directories and linked to .rst
1298    files.
1299
1300
1301 Plots
1302 `````
1303
1304  - `plot.ly <https://plot.ly/>`_ is currently used to generate plots, the model
1305    includes the type of plot and all the necessary information to render it.
1306  - output format: html.
1307  - generated plots are stored in specified directories and linked to .rst files.
1308
1309
1310 Report generation
1311 -----------------
1312
1313 Report is generated using Sphinx and Read_the_Docs template. PAL generates html
1314 and pdf formats. It is possible to define the content of the report by
1315 specifying the version (TODO: define the names and content of versions).
1316
1317
1318 The process
1319 ```````````
1320
1321 1. Read the specification.
1322 2. Read the input data.
1323 3. Process the input data.
1324 4. For element (plot, table, file) defined in specification:
1325
1326    a. Get the data needed to construct the element using a filter.
1327    b. Generate the element.
1328    c. Store the element.
1329
1330 5. Generate the report.
1331 6. Store the report (Nexus).
1332
1333 The process is model driven. The elements' models (tables, plots, files
1334 and report itself) are defined in the specification file. Script reads
1335 the elements' models from specification file and generates the elements.
1336
1337 It is easy to add elements to be generated in the report. If a new type
1338 of an element is required, only a new algorithm needs to be implemented
1339 and integrated.
1340
1341
1342 API
1343 ---
1344
1345 List of modules, classes, methods and functions
1346 ```````````````````````````````````````````````
1347
1348 ::
1349
1350     specification_parser.py
1351
1352         class Specification
1353
1354             Methods:
1355                 read_specification
1356                 set_input_state
1357                 set_input_file_name
1358
1359             Getters:
1360                 specification
1361                 environment
1362                 debug
1363                 is_debug
1364                 input
1365                 builds
1366                 output
1367                 tables
1368                 plots
1369                 files
1370                 static
1371
1372
1373     input_data_parser.py
1374
1375         class InputData
1376
1377             Methods:
1378                 read_data
1379                 filter_data
1380
1381             Getters:
1382                 data
1383                 metadata
1384                 suites
1385                 tests
1386
1387
1388     environment.py
1389
1390         Functions:
1391             clean_environment
1392
1393         class Environment
1394
1395             Methods:
1396                 set_environment
1397
1398             Getters:
1399                 environment
1400
1401
1402     input_data_files.py
1403
1404         Functions:
1405             download_data_files
1406             unzip_files
1407
1408
1409     generator_tables.py
1410
1411         Functions:
1412             generate_tables
1413
1414         Functions implementing algorithms to generate particular types of
1415         tables (called by the function "generate_tables"):
1416             table_details
1417             table_performance_improvements
1418
1419
1420     generator_plots.py
1421
1422         Functions:
1423             generate_plots
1424
1425         Functions implementing algorithms to generate particular types of
1426         plots (called by the function "generate_plots"):
1427             plot_performance_box
1428             plot_latency_box
1429
1430
1431     generator_files.py
1432
1433         Functions:
1434             generate_files
1435
1436         Functions implementing algorithms to generate particular types of
1437         files (called by the function "generate_files"):
1438             file_test_results
1439
1440
1441     report.py
1442
1443         Functions:
1444             generate_report
1445
1446         Functions implementing algorithms to generate particular types of
1447         report (called by the function "generate_report"):
1448             generate_html_report
1449             generate_pdf_report
1450
1451         Other functions called by the function "generate_report":
1452             archive_input_data
1453             archive_report
1454
1455
1456 PAL functional diagram
1457 ``````````````````````
1458
1459 .. only:: latex
1460
1461     .. raw:: latex
1462
1463         \begin{figure}[H]
1464         \centering
1465             \includesvg[width=0.90\textwidth]{../_tmp/src/csit_framework_documentation/pal_func_diagram}
1466             \label{fig:pal_func_diagram}
1467         \end{figure}
1468
1469 .. only:: html
1470
1471     .. figure:: pal_func_diagram.svg
1472         :alt: PAL functional diagram
1473         :align: center
1474
1475
1476 How to add an element
1477 `````````````````````
1478
1479 Element can be added by adding it's model to the specification file. If
1480 the element is to be generated by an existing algorithm, only it's
1481 parameters must be set.
1482
1483 If a brand new type of element needs to be added, also the algorithm
1484 must be implemented. Element generation algorithms are implemented in
1485 the files with names starting with "generator" prefix. The name of the
1486 function implementing the algorithm and the name of algorithm in the
1487 specification file have 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.