resources/tools/presentation/doc/graphs_improvements.rst

   1 ================================
   2  Envisioning information by PAL
   3 ================================
   4
   5 Introduction
   6 ------------
   7
   8 This document describes possible improvements in data presentation provided by
   9 PAL for the `Report <https://s3-docs.fd.io/csit/master/report/>`_ and the
  10 `Trending <https://s3-docs.fd.io/csit/master/trending/>`_
  11
  12 You can generate a standalone html version of this document using e.g.
  13 rst2html5 tool:
  14
  15 .. code:: bash
  16
  17     rst2html5 --stylesheet graphs_improvements.css graphs_improvements.rst >> graphs_improvements.html
  18
  19 **Modifications of existing graphs**
  20
  21 - `Speedup Multi-core`_
  22 - `Packet Throughput`_
  23 - `Packet Latency`_
  24
  25 **New graphs to be added**
  26
  27 - `Comparison between releases`_
  28 - `Comparison between processor architectures`_
  29 - `Comparison between 2-node and 3-node topologies`_
  30 - `Comparison between different physical testbed instances`_
  31 - `Comparison between NICs`_
  32 - `Other comparisons`_
  33
  34 **Export of static images**
  35
  36 - low priority
  37 - make possible to `export static images`_ which are available via link on the
  38   web page.
  39 - vector formats (svg, pdf) are preferred
  40
  41 Priorities
  42 ----------
  43
  44 **Target CSIT-18.10**
  45
  46 - `Speedup Multi-core`_
  47 - `Packet Throughput`_
  48
  49 **Nice to have in CSIT-18.10**
  50
  51 .. note::
  52
  53     Only if above done, and target CSIT-18.10 is in time , otherwise next
  54     release.
  55
  56 - `Packet Latency`_
  57
  58 Modifications of existing graphs
  59 --------------------------------
  60
  61 The proposed modifications include the changes in:
  62
  63 - the layout of the graphs,
  64 - the data and way how it is presented,
  65 - the test cases presented in the graphs.
  66
  67 The first two points are described below, the last one will be added later as a
  68 separate chapter.
  69
  70 .. _Speedup Multi-core:
  71
  72 Speedup Multi-core
  73 ``````````````````
  74
  75 The "Speedup Multicore" graph will display the measured data together with
  76 perfect values calculated as multiples of the best value measured using one
  77 core. The relative difference between measured and perfect values will be
  78 displayed in the hover next to each data point.
  79
  80 .. image:: pic/graph-speedup.svg
  81     :width: 800 px
  82     :scale: 50 %
  83     :align: center
  84     :alt: Graph "Speedup Multi-core: not found.
  85
  86 **Description:**
  87
  88 *Data displayed:*
  89
  90 - one or more data series from the same area, keep the number of displayed
  91   data series as low as possible (max 6)
  92 - x-axis: number of cores
  93 - y-axis: throughput (measured and perfect) [Mpps], linear scale, beginning
  94   with 0
  95 - hover information: Throughput [Mpps], Speedup [1], Relative difference between
  96   measured and ideal values [%], Perfect Throughput [%]
  97 - Limits of ethernet links, NICs and PCIe. See `Physical performance limits`_.
  98
  99 *Layout:*
 100
 101 - plot type: lines with data points (plotly.graph_objs.Scatter)
 102 - data series format:
 103     - measured: solid line with data points
 104     - perfect: dashed line with data points, the same color as "measured"
 105 - title: "Speedup Multi-core: <area, scaling, features, ...>",
 106   top, centered, font size 18; configurable in specification file: visible /
 107   hidden, text
 108 - x-axis: integers, starting with 1 (core), linear, font size 16, bottom
 109 - x-axis label: "Number of cores [qty]", bottom, centered, font size 16
 110 - y-axis: float, starting with 0, dynamic range, linear, font size 16, left
 111 - y-axis label: "Packet Throughput [Mpps]", middle, left
 112 - legend: list of presented test cases, bottom, left, font size 16; the order
 113   of displayed tests is configurable in the specification file
 114 - annotation: text: "dashed: perfect<br>solid: measured", top, left,
 115   font size 16
 116
 117 .. _Packet Throughput:
 118
 119 Packet Throughput
 120 `````````````````
 121
 122 The "Packet Throughput" graph will display the measured data using
 123 statistical box graph. Each data point is constructed from 10 samples.
 124 The statistical data are displayed as hover information.
 125
 126 .. image:: pic/graph-throughput.svg
 127     :width: 800 px
 128     :scale: 50 %
 129     :align: center
 130     :alt: Graph "Packet Throughput" not found.
 131
 132 **Description:**
 133
 134 *Data displayed:*
 135
 136 - one or more data points from the same area, keep the number of displayed
 137   data points as low as possible (max 6)
 138 - x-axis: indexed test cases
 139 - y-axis: throughput [Mpps], linear scale, beginning with 0
 140 - hover information: statistical data (min, lower fence, q1, median, q3,
 141   higher fence, max), test case name
 142
 143 *Layout:*
 144
 145 - plot type: statistical box (plotly.graph_objs.Box)
 146 - data series format: box
 147 - title: "Packet Throughput: <area, scaling, features, framesize, cores, ...>",
 148   top, centered, font size 18; configurable in specification file: visible /
 149   hidden, text
 150 - x-axis: integers, starting with 1, linear, font size 16, bottom; the order
 151   of displayed tests is configurable in the specification file
 152 - x-axis label: "Indices of Test Cases [Index]", bottom, centered, font size 16
 153 - y-axis: floats, starting with 0, dynamic range, linear, font size 16, left
 154 - y-axis label: "Packet Throughput [Mpps]", middle, left
 155 - legend: "Indexed Test Cases [idx]", bottom, left, font size 16
 156
 157 .. _Packet Latency:
 158
 159 Packet Latency
 160 ``````````````
 161
 162 The "Packet Latency" graph will display the measured data using
 163 statistical box graph. Each data point is constructed from 10 samples.
 164 The statistical data are displayed as hover information.
 165
 166 .. image:: pic/graph-latency.svg
 167     :width: 800 px
 168     :scale: 50 %
 169     :align: center
 170     :alt: Graph "Packet Latency" not found.
 171
 172 **Description:**
 173
 174 *Data displayed:*
 175
 176 - one or more data points from the same area, keep the number of displayed
 177   data points as low as possible (max 6)
 178 - x-axis: data flow directions
 179 - y-axis: latency min/avg/max [uSec], linear scale, beginning with 0
 180 - hover information: statistical data (min, avg, max), test case name, direction
 181
 182 *Layout:*
 183
 184 - plot type: scatter with errors (plotly.graph_objs.Scatter)
 185 - data series format: data point with min amd max values
 186 - title: "Packet Latency: <area, scaling, features, framesize, cores, ...>",
 187   top, centered, font size 18; configurable in specification file: visible /
 188   hidden, text
 189 - x-axis: text, font size 16, bottom; the order of displayed tests is
 190   configurable in the specification file
 191 - x-axis label: "Direction", bottom, centered
 192 - y-axis: integers, starting with 0, dynamic range, linear, font size 16, left
 193 - y-axis label: "Packet Latency min/avg/max [uSec]", middle, left
 194 - legend: "Indexed Test Cases [idx]", bottom, left, font size 16
 195
 196 New graphs to be added
 197 ----------------------
 198
 199 - *Comparison between releases*
 200
 201     - compare MRR, NDR, PDR between releases
 202     - use as many releases as available
 203
 204 - *Comparison between processor architectures*
 205
 206     - compare MRR, NDR, PDR between processor architectures
 207     - HSW vs SKX (vs ARM when available)
 208
 209 - *Comparison between 2-node and 3-node topologies*
 210
 211     - compare MRR, NDR, PDR between topologies
 212     - 3n-skx vs 2n-skx
 213
 214 - *Comparison between different physical testbed instances*
 215
 216     - compare the results of the same test (MRR, NDR, PDR) run on different
 217       instances of the same testbed, e.g. HSW
 218     - HSW vs HSW, SKX vs SKX
 219
 220 - *Comparison between NICs*
 221
 222     - compare the results of the same test (MRR, NDR, PDR) run on different NICs
 223       but on the same instance of a physical testbed.
 224     - x520 vs x710 vs xl710 on HSW
 225     - x710 vs xxv710 on SKX
 226
 227 - *Other comparisons*
 228
 229 .. note::
 230
 231     - Partially based on the existing tables in the Report
 232     - Only selected TCs
 233
 234 .. _Comparison between releases:
 235
 236 Comparison between releases
 237 ```````````````````````````
 238
 239 This graph will compare the results of the same test from different releases.
 240 One graph can present the data from one or more tests logically grouped. See
 241 `Grouping of tests in graphs`_ for more information.
 242 Each data point is constructed from 10 samples. The statistical data are
 243 displayed as hover information.
 244
 245 .. image:: pic/graph_cmp_releases.svg
 246     :width: 800 px
 247     :scale: 50 %
 248     :align: center
 249     :alt: Graph "Comparison between releases" not found.
 250
 251 **Description:**
 252
 253 *Data displayed:*
 254
 255 - data: packet throughput
 256 - x-axis: release
 257 - y-axis: packet throughput [Mpps], linear scale, beginning with 0
 258 - hover information: statistical data (median, stdev), test case name, release
 259
 260 *Layout:*
 261
 262 - plot type: scatter with line
 263 - data series format: line with markers
 264 - title: "Packet Throughput: <area, scaling, features, framesize, cores, ...>",
 265   top, centered, font size 18
 266 - x-axis: strings, font size 16, bottom
 267 - x-axis label: "Release", bototm, centered, font size 16
 268 - y-axis: floats, starting with 0, dynamic range, linear, bottom, font size 16
 269 - y-axis label: "Packet Throughput [Mpps]", middle, left, font size 16
 270 - legend: "Test Cases", bottom, left, font size 16
 271
 272 .. _Comparison between processor architectures:
 273
 274 Comparison between processor architectures
 275 ``````````````````````````````````````````
 276
 277 This graph will compare the results of the same test from the same release run
 278 on the different processor architectures (HSW, SKX, later ARM).
 279 One graph can present the data from one or more tests logically grouped. See
 280 `Grouping of tests in graphs`_ for more information.
 281 Each data point is constructed from 10 samples. The statistical data are
 282 displayed as hover information.
 283
 284 .. image:: pic/graph_cmp_arch.svg
 285     :width: 800 px
 286     :scale: 50 %
 287     :align: center
 288     :alt: Graph "Comparison between processor architectures" not found.
 289
 290 **Description:**
 291
 292 *Data displayed:*
 293
 294 - data: packet throughput
 295 - x-axis: processor architecture
 296 - y-axis: throughput [Mpps], linear scale, beginning with 0
 297 - hover information: statistical data (median, stdev), test case name, processor
 298   architecture
 299
 300 *Layout:*
 301
 302 - plot type: scatter with line
 303 - data series format: line with markers
 304 - title: "Packet Throughput: <area, scaling, features, framesize, cores, ...>",
 305   top, centered, font size 18
 306 - x-axis: strings, font size 16, bottom, centered
 307 - x-axis label: "Processor architecture", bottom, centered, font size 16
 308 - y-axis: floats, starting with 0, dynamic range, linear, font size 16, left
 309 - y-axis label: "Packet Throughput [Mpps]", middle, left
 310 - legend: "Test cases", bottom, left, font size 16
 311
 312 .. _Comparison between 2-node and 3-node topologies:
 313
 314 Comparison between 2-node and 3-node topologies
 315 ```````````````````````````````````````````````
 316
 317 This graph will compare the results of the same test from the same release run
 318 on the same processor architecture but different topologies (3n-skx, 2n-skx).
 319 One graph can present the data from one or more tests logically grouped. See
 320 `Grouping of tests in graphs`_ for more information.
 321 Each data point is constructed from 10 samples. The statistical data are
 322 displayed as hover information.
 323
 324 .. image:: pic/graph_cmp_topo.svg
 325     :width: 800 px
 326     :scale: 50 %
 327     :align: center
 328     :alt: Graph "Comparison between 2-node and 3-node topologies" not found.
 329
 330 **Description:**
 331
 332 *Data displayed:*
 333
 334 - data: packet throughput
 335 - x-axis: topology
 336 - y-axis: throughput [Mpps], linear scale, beginning with 0
 337 - hover information: statistical data (median, stdev), test case name, topology
 338
 339 *Layout:*
 340
 341 - plot type: scatter with line
 342 - data series format: line with markers
 343 - title: "Packet Throughput: <area, scaling, features, framesize, cores, ...>",
 344   top, centered, font size 18
 345 - x-axis: strings, font size 16, bottom, centered
 346 - x-axis label: "Topology", bottom, centered, font size 16
 347 - y-axis: floats, starting with 0, dynamic range, linear, font size 16, left
 348 - y-axis label: "Packet Throughput [Mpps]", middle, left, font size 16
 349 - legend: "Test cases", bottom, left, font size 16
 350
 351 .. _Comparison between different physical testbed instances:
 352
 353 Comparison between different physical testbed instances
 354 ```````````````````````````````````````````````````````
 355
 356 This graph will compare the results of the same test from the same release run
 357 on the same processor architecture, the same topology but different physical
 358 testbed instances.
 359 One graph can present the data from one or more tests logically grouped. See
 360 `Grouping of tests in graphs`_ for more information.
 361 Each data point is constructed from 10 samples. The statistical data are
 362 displayed as hover information.
 363
 364
 365 .. image:: pic/graph_cmp_testbed.svg
 366     :width: 800 px
 367     :scale: 50 %
 368     :align: center
 369     :alt: Graph "Comparison between different physical testbed instances" not
 370           found.
 371
 372 **Description:**
 373
 374 *Data displayed:*
 375
 376 - data: packet throughput
 377 - x-axis: physical testbed instances
 378 - y-axis: throughput [Mpps], linear scale, beginning with 0
 379 - hover information: statistical data (median, stdev), test case name, physical
 380   testbed instance
 381
 382 *Layout:*
 383
 384 - plot type: scatter with line
 385 - data series format: line with markers
 386 - title: "Packet Throughput: <area, scaling, features, framesize, cores, ...>",
 387   top, centered, font size 18
 388 - x-axis: strings, font size 16, bottom, centered
 389 - x-axis label: "Physical Testbed Instance", bottom, centered, font size 16
 390 - y-axis: floats, starting with 0, dynamic range, linear, font size 16, left
 391 - y-axis label: "Packet Throughput [Mpps]", middle, left, font size 16
 392 - legend: "Test cases", bottom, left, font size 16
 393
 394 .. _Comparison between NICs:
 395
 396 Comparison between NICs
 397 ```````````````````````
 398
 399 This graph will compare the results of the same test from the same release run
 400 on the same processor architecture, the same topology but different NICs.
 401 One graph can present the data from one or more tests logically grouped. See
 402 `Grouping of tests in graphs`_ for more information.
 403 Each data point is constructed from 10 samples. The statistical data are
 404 displayed as hover information.
 405
 406 .. image:: pic/graph_cmp_nics.svg
 407     :width: 800 px
 408     :scale: 50 %
 409     :align: center
 410     :alt: Graph "Comparison between NICs" not found.
 411
 412 **Description:**
 413
 414 *Data displayed:*
 415
 416 - data: packet throughput
 417 - x-axis: NICs
 418 - y-axis: packet throughput [Mpps], linear scale, beginning with 0
 419 - hover information: statistical data (median, stdev), test case name, NIC
 420
 421 *Layout:*
 422
 423 - plot type: scatter with line
 424 - data series format: line with markers
 425 - title: "Packet Throughput: <area, scaling, features, framesize, cores, ...>",
 426   top, centered, font size 18
 427 - x-axis: strings, font size 16, bottom
 428 - x-axis label: "NIC", bottom, centered, font size 16
 429 - y-axis: floats, starting with 0, dynamic range, linear, font size 16, left
 430 - y-axis label: "Packet Throughput [Mpps]", middle, left, font size 16
 431 - legend: "Test cases", bottom, left, font size 16
 432
 433 .. _Other comparisons:
 434
 435 Other comparisons
 436 `````````````````
 437
 438 **Other tests results comparisons**
 439
 440 - compare packet throughput for vhost vs memif
 441
 442 **Other views on collected data**
 443
 444 - per `Vratko Polak email on csit-dev <https://lists.fd.io/g/csit-dev/message/3008>`_.
 445
 446 .. _Grouping of tests in graphs:
 447
 448 Grouping of tests in graphs
 449 ---------------------------
 450
 451 A graph can present results of one or more tests. The tests are grouped
 452 according to the defined criteria. In the ideal case, all graphs use the same
 453 groups of tests.
 454
 455 The grouping of tests is described in a separate document.
 456
 457 .. TODO: [MK], [TF]: Create the document.
 458 .. TODO: [TF]: Add the link.
 459 .. TODO: [TF]: Remove/edit the next paragraph when the document is ready.
 460
 461 **Example of data grouping:**
 462
 463 - ip4: ip4base, ip4scale20k, ip4scale200k, ip4scale2m
 464     - data presented in this order from left to right
 465 - ip6: similar to ip4
 466 - l2bd: similar to ip4.
 467
 468 .. _Sorting of tests presented in a graph:
 469
 470 Sorting of tests presented in a graph
 471 -------------------------------------
 472
 473 It is possible to specify the order of tests (suites) on the x-axis presented in
 474 a graph:
 475
 476 - `Packet Throughput`_
 477 - `Packet Latency`_
 478
 479 It is possible to specify the order of tests (suites) in the legend presented in
 480 a graph:
 481
 482 - `Speedup Multi-core`_
 483
 484 In both cases the order is defined in the specification file for each plot
 485 separately, e.g.:
 486
 487 .. code:: yaml
 488
 489     -
 490       type: "plot"
 491       <other parameters>
 492       sort:
 493       - "IP4BASE"
 494       - "FIB_20K"
 495       - "FIB_200K"
 496       - "FIB_2M"
 497
 498 The sorting is based on tags. If more then one test has the same tag, only the
 499 first one is taken. The remaining tests and the tests without listed tags are
 500 placed at the end of the list in random order.
 501
 502 .. _export static images:
 503
 504 Export of static images
 505 -----------------------
 506
 507 Not implemented yet. For more information see:
 508
 509 - `Plotly: Static image export <https://plot.ly/python/static-image-export/>`_
 510 - prefered vector formats (svg, pdf)
 511 - requirements:
 512     - plotly-orca
 513         - `Orca <https://github.com/plotly/orca>`_
 514         - `Orca releases <https://github.com/plotly/orca/releases>`_
 515         - `Orca management in Python <https://plot.ly/python/orca-management/>`_
 516     - psutil
 517
 518 .. _Physical performance limits:
 519
 520 Physical performance limits
 521 ---------------------------
 522
 523 +-----------------+----------------+
 524 | Ethernet links  | pps @64B       |
 525 +=================+================+
 526 |  10ge           |  14,880,952.38 |
 527 +-----------------+----------------+
 528 |  25ge           |  37,202,380.95 |
 529 +-----------------+----------------+
 530 |  40ge           |  59,523,809.52 |
 531 +-----------------+----------------+
 532 |  100ge          | 148,809,523.81 |
 533 +-----------------+----------------+
 534
 535
 536 +-----------------+----------------+
 537 | Ethernet links  | bps            |
 538 +=================+================+
 539 | 64B             |                |
 540 +-----------------+----------------+
 541 | IMIX            |                |
 542 +-----------------+----------------+
 543 | 1518B           |                |
 544 +-----------------+----------------+
 545 | 9000B           |                |
 546 +-----------------+----------------+
 547
 548
 549 +-----------------+----------------+
 550 | NIC             | pps @64B       |
 551 +=================+================+
 552 | x520            | 24,460,000     |
 553 +-----------------+----------------+
 554 | x710            | 35,800,000     |
 555 +-----------------+----------------+
 556 | xxv710          | 35,800,000     |
 557 +-----------------+----------------+
 558 | xl710           | 35,800,000     |
 559 +-----------------+----------------+
 560
 561
 562 +-----------------+----------------+
 563 | NIC             | bw ??B         |
 564 +=================+================+
 565 | x520            |                |
 566 +-----------------+----------------+
 567 | x710            |                |
 568 +-----------------+----------------+
 569 | xxv710          |                |
 570 +-----------------+----------------+
 571 | xl710           |                |
 572 +-----------------+----------------+
 573
 574
 575 +-----------------+----------------+
 576 | PCIe            | bps            |
 577 +=================+================+
 578 | PCIe Gen3 x8    | 50,000,000,000 |
 579 +-----------------+----------------+
 580 | PCIe Gen3 x16   | 100,000,000,000|
 581 +-----------------+----------------+
 582
 583
 584 +-----------------+----------------+
 585 | PCIe            | pps @64B       |
 586 +=================+================+
 587 | PCIe Gen3 x8    |  74,404,761.90 |
 588 +-----------------+----------------+
 589 | PCIe Gen3 x16   | 148,809,523.81 |
 590 +-----------------+----------------+