docs/release/userguide/kvmfornfv.cyclictest-dashboard.userguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2
   3 .. http://creativecommons.org/licenses/by/4.0
   4
   5 =======================
   6 KVM4NFV Dashboard Guide
   7 =======================
   8
   9 Dashboard for KVM4NFV Daily Test Results
  10 ----------------------------------------
  11
  12 Abstract
  13 --------
  14
  15 This chapter explains the procedure to configure the InfluxDB and Grafana on Node1 or Node2
  16 depending on the testtype to publish KVM4NFV test results. The cyclictest cases are executed
  17 and results are published on Yardstick Dashboard(Grafana). InfluxDB is the database which will
  18 store the cyclictest results and Grafana is a visualisation suite to view the maximum,minimum and
  19 average values of the time series data of cyclictest results.The framework is shown in below image.
  20
  21 .. figure:: images/dashboard-architecture.png
  22    :name: dashboard-architecture
  23    :width: 100%
  24    :align: center
  25
  26 Version Features
  27 ----------------
  28
  29 +-----------------------------+--------------------------------------------+
  30 |                             |                                            |
  31 |      **Release**            |               **Features**                 |
  32 |                             |                                            |
  33 +=============================+============================================+
  34 |                             | - Data published in Json file format       |
  35 |       Colorado              | - No database support to store the test's  |
  36 |                             |   latency values of cyclictest             |
  37 |                             | - For each run, the previous run's output  |
  38 |                             |   file is replaced with a new file with    |
  39 |                             |   currents latency values.                 |
  40 +-----------------------------+--------------------------------------------+
  41 |                             | - Test results are stored in Influxdb      |
  42 |                             | - Graphical representation of the latency  |
  43 |       Danube                |   values using Grafana suite. (Dashboard)  |
  44 |                             | - Supports graphical view for multiple     |
  45 |                             |   testcases and test-types (Stress/Idle)   |
  46 +-----------------------------+--------------------------------------------+
  47
  48
  49 Installation Steps:
  50 -------------------
  51 To configure Yardstick, InfluxDB and Grafana for KVM4NFV project following sequence of steps are followed:
  52
  53 **Note:**
  54
  55 All the below steps are done as per the script, which is a part of CICD integration of kvmfornfv.
  56
  57 .. code:: bash
  58
  59    For Yardstick:
  60    git clone https://gerrit.opnfv.org/gerrit/yardstick
  61
  62    For InfluxDB:
  63    docker pull tutum/influxdb
  64    docker run -d --name influxdb -p 8083:8083 -p 8086:8086 --expose 8090 --expose 8099 tutum/influxdb
  65    docker exec -it influxdb bash
  66    $influx
  67    >CREATE USER root WITH PASSWORD 'root' WITH ALL PRIVILEGES
  68    >CREATE DATABASE yardstick;
  69    >use yardstick;
  70    >show MEASUREMENTS;
  71
  72    For Grafana:
  73    docker pull grafana/grafana
  74    docker run -d --name grafana -p 3000:3000 grafana/grafana
  75
  76 The Yardstick document for Grafana and InfluxDB configuration can be found `here`_.
  77
  78 .. _here: https://wiki.opnfv.org/display/yardstick/How+to+deploy+InfluxDB+and+Grafana+locally
  79
  80 Configuring the Dispatcher Type:
  81 ---------------------------------
  82 Need to configure the dispatcher type in /etc/yardstick/yardstick.conf depending on the dispatcher
  83 methods which are used to store the cyclictest results. A sample yardstick.conf can be found at
  84 /yardstick/etc/yardstick.conf.sample, which can be copied to /etc/yardstick.
  85
  86 .. code:: bash
  87
  88     mkdir -p /etc/yardstick/
  89     cp /yardstick/etc/yardstick.conf.sample /etc/yardstick/yardstick.conf
  90
  91 **Dispatcher Modules:**
  92
  93 Three type of dispatcher methods are available to store the cyclictest results.
  94
  95 - File
  96 - InfluxDB
  97 - HTTP
  98
  99 **1. File**:  Default Dispatcher module is file. If the dispatcher module is configured as a file,
 100 then the test results are stored in a temporary file yardstick.out(default path: /tmp/yardstick.out).
 101 Dispatcher module of "Verify Job" is "Default". So,the results are stored in Yardstick.out file for
 102 verify job. Storing all the verify jobs in InfluxDB database causes redundancy of latency values.
 103 Hence, a File output format is prefered.
 104
 105 .. code:: bash
 106
 107     [DEFAULT]
 108     debug = False
 109     dispatcher = file
 110
 111     [dispatcher_file]
 112     file_path = /tmp/yardstick.out
 113     max_bytes = 0
 114     backup_count = 0
 115
 116 **2. Influxdb**: If the dispatcher module is configured as influxdb, then the test results are
 117 stored in Influxdb. Users can check test resultsstored in the Influxdb(Database) on Grafana which is
 118 used to visualizethe time series data.
 119
 120 To configure the influxdb, the following content in /etc/yardstick/yardstick.conf need to updated
 121
 122 .. code:: bash
 123
 124     [DEFAULT]
 125     debug = False
 126     dispatcher = influxdb
 127
 128     [dispatcher_influxdb]
 129     timeout = 5
 130     target = http://127.0.0.1:8086  ##Mention the IP where influxdb is running
 131     db_name = yardstick
 132     username = root
 133     password = root
 134
 135 Dispatcher module of "Daily Job" is Influxdb. So, the results are stored in influxdb and then
 136 published to Dashboard.
 137
 138 **3. HTTP**: If the dispatcher module is configured as http, users can check test result on OPNFV
 139 testing dashboard which uses MongoDB as backend.
 140
 141 .. code:: bash
 142
 143     [DEFAULT]
 144     debug = False
 145     dispatcher = http
 146
 147     [dispatcher_http]
 148     timeout = 5
 149     target = http://127.0.0.1:8000/results
 150
 151 .. figure:: images/UseCaseDashboard.png
 152
 153
 154 Detailing the dispatcher module in verify and daily Jobs:
 155 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 156
 157 KVM4NFV updates the dispatcher module in the yardstick configuration (/etc/yardstick/yardstick.conf)
 158 file depending on the Job type(Verify/Daily). Once the test is completed, results are published to
 159 the respective dispatcher modules.
 160
 161 Dispatcher module is configured for each Job type as mentioned below.
 162
 163 1. ``Verify Job`` : Default "DISPATCHER_TYPE" i.e. file(/tmp/yardstick.out) is used. User can also
 164 see the test results on Jenkins console log.
 165
 166 .. code:: bash
 167
 168      *"max": "00030", "avg": "00006", "min": "00006"*
 169
 170 2. ``Daily Job`` : Opnfv Influxdb url is configured as dispatcher module.
 171
 172 .. code:: bash
 173
 174      DISPATCHER_TYPE=influxdb
 175      DISPATCHER_INFLUXDB_TARGET="http://104.197.68.199:8086"
 176
 177 Influxdb only supports line protocol, and the json protocol is deprecated.
 178
 179 For example, the raw_result of cyclictest in json format is:
 180    ::
 181
 182     "benchmark": {
 183          "timestamp": 1478234859.065317,
 184          "errors": "",
 185          "data": {
 186             "max": "00012",
 187             "avg": "00008",
 188             "min": "00007"
 189          },
 190        "sequence": 1
 191        },
 192       "runner_id": 23
 193     }
 194
 195
 196 With the help of "influxdb_line_protocol", the json is transformed as a line string:
 197    ::
 198
 199      'kvmfornfv_cyclictest_idle_idle,deploy_scenario=unknown,host=kvm.LF,
 200      installer=unknown,pod_name=unknown,runner_id=23,scenarios=Cyclictest,
 201      task_id=e7be7516-9eae-406e-84b6-e931866fa793,version=unknown
 202      avg="00008",max="00012",min="00007" 1478234859065316864'
 203
 204
 205
 206 Influxdb api which is already implemented in `Influxdb`_ will post the data in line format into the
 207 database.
 208
 209 ``Displaying Results on Grafana dashboard:``
 210
 211 - Once the test results are stored in Influxdb, dashboard configuration file(Json) which used to
 212 display the cyclictest results on Grafana need to be created by following the `Grafana-procedure`_
 213 and then pushed into `yardstick-repo`_\
 214
 215 - Grafana can be accessed at `Login`_ using credentials opnfv/opnfv and used for visualizing the
 216 collected test data as shown in `Visual`_\
 217
 218
 219 .. figure:: images/Dashboard-screenshot-1.png
 220    :name: dashboard-screenshot-1
 221    :width: 100%
 222    :align: center
 223
 224 .. figure:: images/Dashboard-screenshot-2.png
 225    :name: dashboard-screenshot-2
 226    :width: 100%
 227    :align: center
 228
 229 .. _Influxdb: https://git.opnfv.org/cgit/yardstick/tree/yardstick/dispatcher/influxdb.py
 230
 231 .. _Visual: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest
 232
 233 .. _Login: http://testresults.opnfv.org/grafana/login
 234
 235 .. _Grafana-procedure: https://wiki.opnfv.org/display/yardstick/How+to+work+with+grafana+dashboard
 236
 237 .. _yardstick-repo: https://git.opnfv.org/cgit/yardstick/tree/dashboard/KVMFORNFV-Cyclictest
 238
 239 .. _GrafanaDoc: http://docs.grafana.org/
 240
 241 Understanding Kvm4nfv Grafana Dashboard
 242 ---------------------------------------
 243
 244 The Kvm4nfv dashboard found at http://testresults.opnfv.org/ currently supports graphical view of
 245 cyclictest. For viewing Kvm4nfv dashboarduse,
 246
 247 .. code:: bash
 248
 249     http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest
 250
 251     The login details are:
 252
 253         Username: opnfv
 254         Password: opnfv
 255
 256
 257 .. code:: bash
 258
 259     The JSON of the kvmfonfv-cyclictest dashboard can be found at.,
 260
 261     $ git clone https://gerrit.opnfv.org/gerrit/yardstick.git
 262     $ cd yardstick/dashboard
 263     $ cat KVMFORNFV-Cyclictest
 264
 265 The Dashboard has four tables, each representing a specific test-type of cyclictest case,
 266
 267 - Kvmfornfv_Cyclictest_Idle-Idle
 268 - Kvmfornfv_Cyclictest_CPUstress-Idle
 269 - Kvmfornfv_Cyclictest_Memorystress-Idle
 270 - Kvmfornfv_Cyclictest_IOstress-Idle
 271
 272 Note:
 273
 274 - For all graphs, X-axis is marked with time stamps, Y-axis with value in microsecond units.
 275
 276 **A brief about what each graph of the dashboard represents:**
 277
 278 1. Idle-Idle Graph
 279 ~~~~~~~~~~~~~~~~~~~~
 280 `Idle-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by running
 281 Idle_Idle test-type of the cyclictest.
 282 Idle_Idle implies that no stress is applied on the Host or the Guest.
 283
 284 .. _Idle-Idle: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest?panelId=10&fullscreen
 285
 286 .. figure:: images/Idle-Idle.png
 287    :name: Idle-Idle graph
 288    :width: 100%
 289    :align: center
 290
 291 2. CPU_Stress-Idle Graph
 292 ~~~~~~~~~~~~~~~~~~~~~~~~~
 293 `Cpu_Stress-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by
 294 running Cpu-stress_Idle test-type of the cyclictest. Cpu-stress_Idle implies that CPU stress is
 295 applied on the Host and no stress on the Guest.
 296
 297 .. _Cpu_stress-Idle: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest?panelId=11&fullscreen
 298
 299 .. figure:: images/Cpustress-Idle.png
 300    :name: cpustress-idle graph
 301    :width: 100%
 302    :align: center
 303
 304 3. Memory_Stress-Idle Graph
 305 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 306 `Memory_Stress-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by
 307 running Memory-stress_Idle test-type of the Cyclictest. Memory-stress_Idle implies that Memory
 308 stress is applied on the Host and no stress on the Guest.
 309
 310 .. _Memory_Stress-Idle: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest?panelId=12&fullscreen
 311
 312 .. figure:: images/Memorystress-Idle.png
 313    :name: memorystress-idle graph
 314    :width: 100%
 315    :align: center
 316
 317 4. IO_Stress-Idle Graph
 318 ~~~~~~~~~~~~~~~~~~~~~~~~~
 319 `IO_Stress-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by running
 320 IO-stress_Idle test-type of the Cyclictest. IO-stress_Idle implies that IO stress is applied on the
 321 Host and no stress on the Guest.
 322
 323 .. _IO_Stress-Idle: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest?panelId=13&fullscreen
 324
 325 .. figure:: images/IOstress-Idle.png
 326    :name: iostress-idle graph
 327    :width: 100%
 328    :align: center
 329
 330 Packet Forwarding Results
 331 ~~~~~~~~~~~~~~~~~~~~~~~~~
 332
 333 Understanding Kvm4nfv Grafana Dashboard
 334 ---------------------------------------
 335
 336 The Kvm4nfv dashboard found at http://testresults.opnfv.org/grafana/ currently supports graphical
 337 view of packet forwarding as well. For viewing Kvm4nfv packet forwarding dashboard use,
 338
 339 .. code:: bash
 340
 341     http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-packet-forwarding
 342
 343     The login details are:
 344
 345         Username: opnfv
 346         Password: opnfv
 347
 348
 349 .. code:: bash
 350
 351     The JSON of the KVMFORNFV-Packet-Forwarding dashboard can be found at.,
 352
 353     $ git clone https://gerrit.opnfv.org/gerrit/yardstick.git
 354     $ cd yardstick/dashboard
 355     $ cat KVMFORNFV-Packet-Forwarding
 356
 357 The Dashboard has five tables for each specific test of packet forwarding, one for each frame size.
 358
 359 - KVM4NFV-PHY2PHY-TPUT-OVS_WITH_DPDK_AND_VHOST_USER
 360 - KVM4NFV-PVP-TPUT-OVS_WITH_DPDK_AND_VHOST_USER
 361 - KVM4NFV-PVP-TPUT-SRIOV
 362 - KVM4NFV-PVVP-TPUT-OVS_WITH_DPDK_AND_VHOST_USER
 363 - KVM4NFV-PVVP-TPUT-OVS_WITH_DPDK_AND_VHOST_USER
 364
 365 Note:
 366
 367 - For all graphs, X-axis is marked with time stamps, Y-axis with value in microsecond units.
 368
 369 Future Scope
 370 ------------
 371 The future work will include adding new tables to packet forwarding Grafana dashboard to publish the
 372 results of new packet forwarding test cases to be added if any.