docs/testing/user/userguide/08-grafana.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International
   2 .. License.
   3 .. http://creativecommons.org/licenses/by/4.0
   4 .. (c) 2016 Huawei Technologies Co.,Ltd and others
   5
   6 .. Convention for heading levels in Yardstick documentation:
   7
   8    =======  Heading 0 (reserved for the title in a document)
   9    -------  Heading 1
  10    ^^^^^^^  Heading 2
  11    +++++++  Heading 3
  12    '''''''  Heading 4
  13
  14    Avoid deeper levels because they do not render well.
  15
  16 =================
  17 Grafana dashboard
  18 =================
  19
  20
  21 Abstract
  22 --------
  23
  24 This chapter describes the Yardstick grafana dashboard. The Yardstick grafana
  25 dashboard can be found here: http://testresults.opnfv.org/grafana/
  26
  27
  28 .. image:: images/login.png
  29    :width: 800px
  30    :alt: Yardstick grafana dashboard
  31
  32
  33 Public access
  34 -------------
  35
  36 Yardstick provids a public account for accessing to the dashboard. The username
  37 and password are both set to ‘opnfv’.
  38
  39
  40 Testcase dashboard
  41 ------------------
  42
  43 For each test case, there is a dedicated dashboard. Shown here is the dashboard
  44 of TC002.
  45
  46
  47 .. image:: images/TC002.png
  48    :width: 800px
  49    :alt: TC002 dashboard
  50
  51 For each test case dashboard. On the top left, we have a dashboard selection,
  52 you can switch to different test cases using this pull-down menu.
  53
  54 Underneath, we have a pod and scenario selection.
  55 All the pods and scenarios that have ever published test data to the InfluxDB
  56 will be shown here.
  57
  58 You can check multiple pods or scenarios.
  59
  60 For each test case, we have a short description and a link to detailed test
  61 case information in Yardstick user guide.
  62
  63 Underneath, it is the result presentation section.
  64 You can use the time period selection on the top right corner to zoom in or
  65 zoom out the chart.
  66
  67
  68 Administration access
  69 ---------------------
  70
  71 For a user with administration rights it is easy to update and save any
  72 dashboard configuration. Saved updates immediately take effect and become live.
  73 This may cause issues like:
  74
  75 - Changes and updates made to the live configuration in Grafana can compromise
  76   existing Grafana content in an unwanted, unpredicted or incompatible way.
  77   Grafana as such is not version controlled, there exists one single Grafana
  78   configuration per dashboard.
  79 - There is a risk several people can disturb each other when doing updates to
  80   the same Grafana dashboard at the same time.
  81
  82 Any change made by administrator should be careful.
  83
  84
  85 Add a dashboard into Yardstick Grafana
  86 --------------------------------------
  87
  88 Due to security concern, users that using the public opnfv account are not able
  89 to edit the yardstick grafana directly. It takes a few more steps for a
  90 non-yardstick user to add a custom dashboard into yardstick grafana.
  91
  92 There are 6 steps to go.
  93
  94
  95 .. image:: images/add.png
  96    :width: 800px
  97    :alt: Add a dashboard into yardstick grafana
  98
  99
 100 1. You need to build a local influxdb and grafana, so you can do the work
 101    locally. You can refer to How to deploy InfluxDB and Grafana locally wiki
 102    page about how to do this.
 103
 104 2. Once step one is done, you can fetch the existing grafana dashboard
 105    configuration file from the yardstick repository and import it to your local
 106    grafana. After import is done, you grafana dashboard will be ready to use
 107    just like the community’s dashboard.
 108
 109 3. The third step is running some test cases to generate test results and
 110    publishing it to your local influxdb.
 111
 112 4. Now you have some data to visualize in your dashboard. In the fourth step,
 113    it is time to create your own dashboard. You can either modify an existing
 114    dashboard or try to create a new one from scratch. If you choose to modify
 115    an existing dashboard then in the curtain menu of the existing dashboard do
 116    a "Save As..." into a new dashboard copy instance, and then continue doing
 117    all updates and saves within the dashboard copy.
 118
 119 5. When finished with all Grafana configuration changes in this temporary
 120    dashboard then chose "export" of the updated dashboard copy into a JSON file
 121    and put it up for review in Gerrit, in file
 122    ``/yardstick/dashboard/Yardstick-TCxxx-yyyyyyyyyyyyy``.
 123    For instance a typical default name of the file would be
 124    ``Yardstick-TC001 Copy-1234567891234``.
 125
 126 6. Once you finish your dashboard, the next step is exporting the configuration
 127    file and propose a patch into Yardstick. Yardstick team will review and
 128    merge it into Yardstick repository. After approved review Yardstick team
 129    will do an "import" of the JSON file and also a "save dashboard" as soon as
 130    possible to replace the old live dashboard configuration.
 131