X-Git-Url: https://gerrit.fd.io/r/gitweb?p=csit.git;a=blobdiff_plain;f=resources%2Ftools%2Fpresentation%2Fdoc%2Fpal_lld.rst;h=64bde3e5febc61ae6d055292c89d92bf885c3674;hp=3a2137366dce864a2c5c47c0133f4fa7f24f2140;hb=0f6410d3c95eb28164fdd349778155c6525e1a79;hpb=fec161451268791e57e5dfe76dbaedd897e99aae diff --git a/resources/tools/presentation/doc/pal_lld.rst b/resources/tools/presentation/doc/pal_lld.rst index 3a2137366d..64bde3e5fe 100644 --- a/resources/tools/presentation/doc/pal_lld.rst +++ b/resources/tools/presentation/doc/pal_lld.rst @@ -1,6 +1,5 @@ -=================================================== -Presentation and Analytics Layer - Low Level Design -=================================================== +Presentation and Analytics Layer +================================ Overview -------- @@ -38,9 +37,21 @@ sub-layers, bottom up: - formats: html, pdf - versions: minimal, full (TODO: define the names and scope of versions) -.. figure:: pal_layers.svg - :alt: PAL Layers - :align: center +.. only:: latex + + .. raw:: latex + + \begin{figure}[H] + \centering + \includesvg[width=0.90\textwidth]{../_tmp/src/csit_framework_documentation/pal_layers} + \label{fig:pal_layers} + \end{figure} + +.. only:: html + + .. figure:: pal_layers.svg + :alt: PAL Layers + :align: center Data ---- @@ -71,6 +82,8 @@ the type: - type: "environment" + - + type: "configuration" - type: "debug" - @@ -112,6 +125,7 @@ This section has the following parts: - build-dirs - a list of the directories where the results are stored. The structure of the section "Environment" is as follows (example): + :: - @@ -212,6 +226,108 @@ will be automatically changed to DIR[WORKING,DATA]: "_tmp/data" +Section: Configuration +'''''''''''''''''''''' + +This section specifies the groups of parameters which are repeatedly used in the +elements defined later in the specification file. It has the following parts: + + - data sets - Specification of data sets used later in element's specifications + to define the input data. + - plot layouts - Specification of plot layouts used later in plots' + specifications to define the plot layout. + +The structure of the section "Configuration" is as follows (example): + +:: + + - + type: "configuration" + data-sets: + plot-vpp-throughput-latency: + csit-vpp-perf-1710-all: + - 11 + - 12 + - 13 + - 14 + - 15 + - 16 + - 17 + - 18 + - 19 + - 20 + vpp-perf-results: + csit-vpp-perf-1710-all: + - 20 + - 23 + plot-layouts: + plot-throughput: + xaxis: + autorange: True + autotick: False + fixedrange: False + gridcolor: "rgb(238, 238, 238)" + linecolor: "rgb(238, 238, 238)" + linewidth: 1 + showgrid: True + showline: True + showticklabels: True + tickcolor: "rgb(238, 238, 238)" + tickmode: "linear" + title: "Indexed Test Cases" + zeroline: False + yaxis: + gridcolor: "rgb(238, 238, 238)'" + hoverformat: ".4s" + linecolor: "rgb(238, 238, 238)" + linewidth: 1 + range: [] + showgrid: True + showline: True + showticklabels: True + tickcolor: "rgb(238, 238, 238)" + title: "Packets Per Second [pps]" + zeroline: False + boxmode: "group" + boxgroupgap: 0.5 + autosize: False + margin: + t: 50 + b: 20 + l: 50 + r: 20 + showlegend: True + legend: + orientation: "h" + width: 700 + height: 1000 + +The definitions from this sections are used in the elements, e.g.: + +:: + + - + type: "plot" + title: "VPP Performance 64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc" + algorithm: "plot_performance_box" + output-file-type: ".html" + output-file: "{DIR[STATIC,VPP]}/64B-1t1c-l2-sel1-ndrdisc" + data: + "plot-vpp-throughput-latency" + filter: "'64B' and ('BASE' or 'SCALE') and 'NDRDISC' and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'" + parameters: + - "throughput" + - "parent" + traces: + hoverinfo: "x+y" + boxpoints: "outliers" + whiskerwidth: 0 + layout: + title: "64B-1t1c-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc" + layout: + "plot-throughput" + + Section: Debug mode ''''''''''''''''''' @@ -993,8 +1109,9 @@ For example, the element which specification includes: filter: - "'64B' and 'BASE' and 'NDRDISC' and '1T1C' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'" -will be constructed using data from the job "csit-vpp-perf-1707-all", for all listed -builds and the tests with the list of tags matching the filter conditions. +will be constructed using data from the job "csit-vpp-perf-1707-all", for all +listed builds and the tests with the list of tags matching the filter +conditions. The output data structure for filtered test data is: @@ -1023,19 +1140,144 @@ Data analytics part implements: - methods to compute statistical data from the filtered input data. - trending. - - etc. + +Throughput Speedup Analysis - Multi-Core with Multi-Threading +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +Throughput Speedup Analysis (TSA) calculates throughput speedup ratios +for tested 1-, 2- and 4-core multi-threaded VPP configurations using the +following formula: + +:: + + N_core_throughput + N_core_throughput_speedup = ----------------- + 1_core_throughput + +Multi-core throughput speedup ratios are plotted in grouped bar graphs +for throughput tests with 64B/78B frame size, with number of cores on +X-axis and speedup ratio on Y-axis. + +For better comparison multiple test results' data sets are plotted per +each graph: + + - graph type: grouped bars; + - graph X-axis: (testcase index, number of cores); + - graph Y-axis: speedup factor. + +Subset of existing performance tests is covered by TSA graphs. + +**Model for TSA:** + +:: + + - + type: "plot" + title: "TSA: 64B-*-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc" + algorithm: "plot_throughput_speedup_analysis" + output-file-type: ".html" + output-file: "{DIR[STATIC,VPP]}/10ge2p1x520-64B-l2-tsa-ndrdisc" + data: + "plot-throughput-speedup-analysis" + filter: "'NIC_Intel-X520-DA2' and '64B' and 'BASE' and 'NDRDISC' and ('L2BDMACSTAT' or 'L2BDMACLRN' or 'L2XCFWD') and not 'VHOST'" + parameters: + - "throughput" + - "parent" + - "tags" + layout: + title: "64B-*-(eth|dot1q|dot1ad)-(l2xcbase|l2bdbasemaclrn)-ndrdisc" + layout: + "plot-throughput-speedup-analysis" + + +Comparison of results from two sets of the same test executions +''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' + +This algorithm enables comparison of results coming from two sets of the +same test executions. It is used to quantify performance changes across +all tests after test environment changes e.g. Operating System +upgrades/patches, Hardware changes. + +It is assumed that each set of test executions includes multiple runs +of the same tests, 10 or more, to verify test results repeatibility and +to yield statistically meaningful results data. + +Comparison results are presented in a table with a specified number of +the best and the worst relative changes between the two sets. Following table +columns are defined: + + - name of the test; + - throughput mean values of the reference set; + - throughput standard deviation of the reference set; + - throughput mean values of the set to compare; + - throughput standard deviation of the set to compare; + - relative change of the mean values. + +**The model** + +The model specifies: + + - type: "table" - means this section defines a table. + - title: Title of the table. + - algorithm: Algorithm which is used to generate the table. The other + parameters in this section must provide all information needed by the used + algorithm. + - output-file-ext: Extension of the output file. + - output-file: File which the table will be written to. + - reference - the builds which are used as the reference for comparison. + - compare - the builds which are compared to the reference. + - data: Specify the sources, jobs and builds, providing data for generating + the table. + - filter: Filter based on tags applied on the input data, if "template" is + used, filtering is based on the template. + - parameters: Only these parameters will be put to the output data + structure. + - nr-of-tests-shown: Number of the best and the worst tests presented in the + table. Use 0 (zero) to present all tests. + +*Example:* + +:: + + - + type: "table" + title: "Performance comparison" + algorithm: "table_performance_comparison" + output-file-ext: ".csv" + output-file: "{DIR[DTR,PERF,VPP,IMPRV]}/vpp_performance_comparison" + reference: + title: "csit-vpp-perf-1801-all - 1" + data: + csit-vpp-perf-1801-all: + - 1 + - 2 + compare: + title: "csit-vpp-perf-1801-all - 2" + data: + csit-vpp-perf-1801-all: + - 1 + - 2 + data: + "vpp-perf-comparison" + filter: "all" + parameters: + - "name" + - "parent" + - "throughput" + nr-of-tests-shown: 20 Advanced data analytics ``````````````````````` -As the next steps, advanced data analytics (ADA) will be implemented using -machine learning (ML) and artificial intelligence (AI). +In the future advanced data analytics (ADA) will be added to analyze the +telemetry data collected from SUT telemetry sources and correlate it to +performance test results. -TODO: +:TODO: - - describe the concept of ADA. - - add specification. + - describe the concept of ADA. + - add specification. Data presentation @@ -1052,7 +1294,8 @@ Tables - tables are generated by algorithms implemented in PAL, the model includes the algorithm and all necessary information. - output format: csv - - generated tables are stored in specified directories and linked to .rst files. + - generated tables are stored in specified directories and linked to .rst + files. Plots @@ -1068,8 +1311,8 @@ Report generation ----------------- Report is generated using Sphinx and Read_the_Docs template. PAL generates html -and pdf formats. It is possible to define the content of the report by specifying -the version (TODO: define the names and content of versions). +and pdf formats. It is possible to define the content of the report by +specifying the version (TODO: define the names and content of versions). The process @@ -1087,12 +1330,13 @@ The process 5. Generate the report. 6. Store the report (Nexus). -The process is model driven. The elements’ models (tables, plots, files and -report itself) are defined in the specification file. Script reads the elements’ -models from specification file and generates the elements. +The process is model driven. The elements' models (tables, plots, files +and report itself) are defined in the specification file. Script reads +the elements' models from specification file and generates the elements. -It is easy to add elements to be generated, if a new kind of element is -required, only a new algorithm is implemented and integrated. +It is easy to add elements to be generated in the report. If a new type +of an element is required, only a new algorithm needs to be implemented +and integrated. API @@ -1212,20 +1456,32 @@ List of modules, classes, methods and functions PAL functional diagram `````````````````````` -.. figure:: pal_func_diagram.svg - :alt: PAL functional diagram - :align: center +.. only:: latex + + .. raw:: latex + + \begin{figure}[H] + \centering + \includesvg[width=0.90\textwidth]{../_tmp/src/csit_framework_documentation/pal_func_diagram} + \label{fig:pal_func_diagram} + \end{figure} + +.. only:: html + + .. figure:: pal_func_diagram.svg + :alt: PAL functional diagram + :align: center How to add an element ````````````````````` -Element can be added by adding its model to the specification file. If the -element will be generated by an existing algorithm, only its parameters must be -set. +Element can be added by adding it's model to the specification file. If +the element is to be generated by an existing algorithm, only it's +parameters must be set. -If a brand new type of element will be added, also the algorithm must be -implemented. -The algorithms are implemented in the files which names start with "generator". -The name of the function implementing the algorithm and the name of algorithm in -the specification file had to be the same. +If a brand new type of element needs to be added, also the algorithm +must be implemented. Element generation algorithms are implemented in +the files with names starting with "generator" prefix. The name of the +function implementing the algorithm and the name of algorithm in the +specification file have to be the same.