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,then the test results are stored in a temporary file yardstick.out
 100 ( default path: /tmp/yardstick.out).
 101 Dispatcher module of "Verify Job" is "Default". So,the results are stored in Yardstick.out file for verify job.
 102 Storing all the verify jobs in InfluxDB database causes redundancy of latency values. Hence, a File output format is prefered.
 103
 104 .. code:: bash
 105
 106     [DEFAULT]
 107     debug = False
 108     dispatcher = file
 109
 110     [dispatcher_file]
 111     file_path = /tmp/yardstick.out
 112     max_bytes = 0
 113     backup_count = 0
 114
 115 **2. Influxdb**: If the dispatcher module is configured as influxdb, then the test results are stored in Influxdb.
 116 Users can check test resultsstored in the Influxdb(Database) on Grafana which is used to visualize the time series data.
 117
 118 To configure the influxdb, the following content in /etc/yardstick/yardstick.conf need to updated
 119
 120 .. code:: bash
 121
 122     [DEFAULT]
 123     debug = False
 124     dispatcher = influxdb
 125
 126     [dispatcher_influxdb]
 127     timeout = 5
 128     target = http://127.0.0.1:8086  ##Mention the IP where influxdb is running
 129     db_name = yardstick
 130     username = root
 131     password = root
 132
 133 Dispatcher module of "Daily Job" is Influxdb. So, the results are stored in influxdb and then published to Dashboard.
 134
 135 **3. HTTP**: If the dispatcher module is configured as http, users can check test result on OPNFV testing dashboard which uses MongoDB as backend.
 136
 137 .. code:: bash
 138
 139     [DEFAULT]
 140     debug = False
 141     dispatcher = http
 142
 143     [dispatcher_http]
 144     timeout = 5
 145     target = http://127.0.0.1:8000/results
 146
 147 .. figure:: images/UseCaseDashboard.png
 148
 149
 150 Detailing the dispatcher module in verify and daily Jobs:
 151 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 152
 153 KVM4NFV updates the dispatcher module in the yardstick configuration file(/etc/yardstick/yardstick.conf) depending on the Job type(Verify/Daily).
 154 Once the test is completed, results are published to the respective dispatcher modules.
 155
 156 Dispatcher module is configured for each Job type as mentioned below.
 157
 158 1. ``Verify Job`` : Default "DISPATCHER_TYPE" i.e. file(/tmp/yardstick.out) is used. User can also see the test results on Jenkins console log.
 159
 160 .. code:: bash
 161
 162      *"max": "00030", "avg": "00006", "min": "00006"*
 163
 164 2. ``Daily Job`` : Opnfv Influxdb url is configured as dispatcher module.
 165
 166 .. code:: bash
 167
 168      DISPATCHER_TYPE=influxdb
 169      DISPATCHER_INFLUXDB_TARGET="http://104.197.68.199:8086"
 170
 171 Influxdb only supports line protocol, and the json protocol is deprecated.
 172
 173 For example, the raw_result of cyclictest in json format is:
 174    ::
 175
 176     "benchmark": {
 177          "timestamp": 1478234859.065317,
 178          "errors": "",
 179          "data": {
 180             "max": "00012",
 181             "avg": "00008",
 182             "min": "00007"
 183          },
 184        "sequence": 1
 185        },
 186       "runner_id": 23
 187     }
 188
 189
 190 With the help of "influxdb_line_protocol", the json is transformed as a line string:
 191    ::
 192
 193      'kvmfornfv_cyclictest_idle_idle,deploy_scenario=unknown,host=kvm.LF,
 194      installer=unknown,pod_name=unknown,runner_id=23,scenarios=Cyclictest,
 195      task_id=e7be7516-9eae-406e-84b6-e931866fa793,version=unknown
 196      avg="00008",max="00012",min="00007" 1478234859065316864'
 197
 198
 199
 200 Influxdb api which is already implemented in `Influxdb`_ will post the data in line format into the database.
 201
 202 ``Displaying Results on Grafana dashboard:``
 203
 204 - Once the test results are stored in Influxdb, dashboard configuration file(Json) which used to display the cyclictest results
 205 on Grafana need to be created by following the `Grafana-procedure`_ and then pushed into `yardstick-repo`_\
 206
 207 - Grafana can be accessed at `Login`_ using credentials opnfv/opnfv and used for visualizing the collected test data as shown in `Visual`_\
 208
 209
 210 .. figure:: images/Dashboard-screenshot-1.png
 211    :name: dashboard-screenshot-1
 212    :width: 100%
 213    :align: center
 214
 215 .. figure:: images/Dashboard-screenshot-2.png
 216    :name: dashboard-screenshot-2
 217    :width: 100%
 218    :align: center
 219
 220 .. _Influxdb: https://git.opnfv.org/cgit/yardstick/tree/yardstick/dispatcher/influxdb.py
 221
 222 .. _Visual: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest
 223
 224 .. _Login: http://testresults.opnfv.org/grafana/login
 225
 226 .. _Grafana-procedure: https://wiki.opnfv.org/display/yardstick/How+to+work+with+grafana+dashboard
 227
 228 .. _yardstick-repo: https://git.opnfv.org/cgit/yardstick/tree/dashboard/KVMFORNFV-Cyclictest
 229
 230 .. _GrafanaDoc: http://docs.grafana.org/
 231
 232 Understanding Kvm4nfv Grafana Dashboard
 233 ---------------------------------------
 234
 235 The Kvm4nfv dashboard found at http://testresults.opnfv.org/ currently supports graphical view of cyclictest. For viewing Kvm4nfv dashboarduse,
 236
 237 .. code:: bash
 238
 239     http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest
 240
 241     The login details are:
 242
 243         Username: opnfv
 244         Password: opnfv
 245
 246
 247 .. code:: bash
 248
 249     The JSON of the kvmfonfv-cyclictest dashboard can be found at.,
 250
 251     $ git clone https://gerrit.opnfv.org/gerrit/yardstick.git
 252     $ cd yardstick/dashboard
 253     $ cat KVMFORNFV-Cyclictest
 254
 255 The Dashboard has four tables, each representing a specific test-type of cyclictest case,
 256
 257 - Kvmfornfv_Cyclictest_Idle-Idle
 258 - Kvmfornfv_Cyclictest_CPUstress-Idle
 259 - Kvmfornfv_Cyclictest_Memorystress-Idle
 260 - Kvmfornfv_Cyclictest_IOstress-Idle
 261
 262 Note:
 263
 264 - For all graphs, X-axis is marked with time stamps, Y-axis with value in microsecond units.
 265
 266 **A brief about what each graph of the dashboard represents:**
 267
 268 1. Idle-Idle Graph
 269 ~~~~~~~~~~~~~~~~~~~~
 270 `Idle-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by running Idle_Idle test-type of the cyclictest.
 271 Idle_Idle implies that no stress is applied on the Host or the Guest.
 272
 273 .. _Idle-Idle: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest?panelId=10&fullscreen
 274
 275 .. figure:: images/Idle-Idle.png
 276    :name: Idle-Idle graph
 277    :width: 100%
 278    :align: center
 279
 280 2. CPU_Stress-Idle Graph
 281 ~~~~~~~~~~~~~~~~~~~~~~~~~
 282 `Cpu_Stress-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by running Cpu-stress_Idle test-type of the cyclictest.
 283 Cpu-stress_Idle implies that CPU stress is applied on the Host and no stress on the Guest.
 284
 285 .. _Cpu_stress-Idle: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest?panelId=11&fullscreen
 286
 287 .. figure:: images/Cpustress-Idle.png
 288    :name: cpustress-idle graph
 289    :width: 100%
 290    :align: center
 291
 292 3. Memory_Stress-Idle Graph
 293 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 294 `Memory_Stress-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by running Memory-stress_Idle test-type of the Cyclictest.
 295 Memory-stress_Idle implies that Memory stress is applied on the Host and no stress on the Guest.
 296
 297 .. _Memory_Stress-Idle: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest?panelId=12&fullscreen
 298
 299 .. figure:: images/Memorystress-Idle.png
 300    :name: memorystress-idle graph
 301    :width: 100%
 302    :align: center
 303
 304 4. IO_Stress-Idle Graph
 305 ~~~~~~~~~~~~~~~~~~~~~~~~~
 306 `IO_Stress-Idle`_ graph displays the Average, Maximum and Minimum latency values obtained by running IO-stress_Idle test-type of the Cyclictest.
 307 IO-stress_Idle implies that IO stress is applied on the Host and no stress on the Guest.
 308
 309 .. _IO_Stress-Idle: http://testresults.opnfv.org/grafana/dashboard/db/kvmfornfv-cyclictest?panelId=13&fullscreen
 310
 311 .. figure:: images/IOstress-Idle.png
 312    :name: iostress-idle graph
 313    :width: 100%
 314    :align: center
 315
 316 Future Scope
 317 -------------
 318 The future work will include adding the kvmfornfv_Packet-forwarding test results into Grafana and influxdb.