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