docs/testing/ecosystem/energy-monitoring.rst

   1 .. _energy-monitoring:
   2
   3 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   4 .. SPDX-License-Identifier: CC-BY-4.0
   5 .. (c) Open Platform for NFV Project, Inc. and its contributors
   6
   7 Power Consumption Monitoring Framework
   8 ======================================
   9
  10 Overview
  11 --------
  12 Power consumption is a key driver for NFV.
  13 As an end user is interested to know which application is good or bad regarding
  14 power consumption and explains why he/she has to plug his/her smartphone every
  15 day, we would be interested to know which VNF is power consuming.
  16
  17 Power consumption is hard to evaluate empirically. It is however possible to
  18 collect information and leverage Pharos federation to try to detect some
  19 profiles/footprints.
  20 In fact thanks to CI, we know that we are running a known/deterministic list of
  21 cases. The idea is to correlate this knowledge with the power consumption to try
  22 at the end to find statistical biais.
  23
  24
  25 High Level Architecture
  26 -----------------------
  27
  28 The energy recorder high level architecture may be described as follows:
  29
  30 .. figure:: ../../images/energyrecorder.png
  31    :align: center
  32    :alt: Energy recorder high level architecture
  33
  34 The energy monitoring system in based on 3 software components:
  35
  36    * Power info collector: poll server to collect instantaneous power consumption information
  37    * Energy recording API + influxdb: On one leg receive servers consumption and
  38      on the other, scenarios notfication. It then able to establish te correlation
  39      between consumption and scenario and stores it into a time-series database (influxdb)
  40    * Python SDK: A Python SDK using decorator to send notification to Energy
  41      recording API from testcases scenarios
  42
  43 Power Info Collector
  44 --------------------
  45 It collects instantaneous power consumption information and send it to Event
  46 API in charge of data storing.
  47 The collector use different connector to read the power consumption on remote
  48 servers:
  49
  50   * IPMI: this is the basic method and is manufacturer dependent. Depending on manufacturer, refreshing delay may vary (generally for 10 to 30 sec.)
  51   * RedFish: redfish is an industry RESTFUL API for hardware managment. Unfortunatly it is not yet supported by many suppliers.
  52   * ILO: HP RESTFULL API: This connector support as well 2.1 as 2.4 version of HP-ILO
  53
  54 IPMI is supported by at least:
  55
  56   * HP
  57   * IBM
  58   * Dell
  59   * Nokia
  60   * Advantech
  61   * Lenovo
  62   * Huawei
  63
  64 Redfish API has been successfully tested on:
  65
  66   * HP
  67   * Dell
  68   * Huawei (E9000 class servers used in OPNFV Community Labs are  IPMI 2.0
  69     compliant and use Redfish login Interface through Browsers supporting JRE1.7/1.8)
  70
  71 Several test campaigns done with physical Wattmeter showed that IPMI results
  72 were notvery accurate but RedFish were. So if Redfish is available, it is
  73 highly recommended to use it.
  74
  75 Installation
  76 ^^^^^^^^^^^^
  77
  78 To run the server power consumption collector agent, you need to deploy a
  79 docker container locally on your infrastructure.
  80
  81 This container requires:
  82
  83   * Connectivy on the LAN where server administration services (ILO, eDrac, IPMI,...) are configured and IP access to the POD's servers
  84   * Outgoing HTTP access to the Event API (internet)
  85
  86 Build the image by typing::
  87
  88   curl -s https://raw.githubusercontent.com/bherard/energyrecorder/master/docker/server-collector.dockerfile|docker build -t energyrecorder/collector -
  89
  90 Create local folder on your host for logs and config files::
  91
  92   mkdir -p /etc/energyrecorder
  93   mkdir -p /var/log/energyrecorder
  94
  95 In /etc/energyrecorder create a configuration for logging in a file named
  96 collector-logging.conf::
  97
  98   curl -s https://raw.githubusercontent.com/bherard/energyrecorder/master/server-collector/conf/collector-logging.conf.sample > /etc/energyrecorder/collector-logging.conf
  99
 100 Check configuration for this file (folders, log levels.....)
 101 In /etc/energyrecorder create a configuration for the collector in a file named
 102 collector-settings.yaml::
 103
 104   curl -s https://raw.githubusercontent.com/bherard/energyrecorder/master/server-collector/conf/collector-settings.yaml.sample > /etc/energyrecorder/collector-settings.yaml
 105
 106 Define the "PODS" section and their "servers" section according to the
 107 environment to monitor.
 108 Note: The "environment" key should correspond to the pod name, as defined in
 109 the "NODE_NAME" environment variable by CI when running.
 110
 111 **IMPORTANT NOTE**: To apply a new configuration, you need to kill the running
 112 container an start a new one (see below)
 113
 114 Run Collector
 115 ^^^^^^^^^^^^^
 116
 117 To run the container, you have to map folder located on the host to folders in
 118 the container (config, logs)::
 119
 120   docker run -d --name energy-collector --restart=always -v /etc/energyrecorder:/usr/local/energyrecorder/server-collector/conf -v /var/log/energyrecorder:/var/log/energyrecorder energyrecorder/collector
 121
 122
 123 Energy Recording API
 124 --------------------
 125 An event API to insert contextual information when monitoring energy (e.g.
 126 start Functest, start Tempest, destroy VM, ..)
 127 It is associated with an influxDB to store the power consumption measures
 128 It is hosted on a shared environment with the folling access points:
 129
 130 +------------------------------------+----------------------------------------+
 131 |   Component                        |    Connectivity                        |
 132 +====================================+========================================+
 133 | Energy recording API documentation | http://energy.opnfv.fr/resources/doc/  |
 134 +------------------------------------+----------------------------------------+
 135 | influxDB (data)                    | http://energy.opnfv.fr:8086            |
 136 +------------------------------------+----------------------------------------+
 137
 138 In you need, you can also host your own version of the Energy recording API
 139 (in such case, the Python SDK may requires a settings update)
 140 If you plan to use the default shared API, following steps are not required.
 141
 142 Image creation
 143 ^^^^^^^^^^^^^^
 144 First, you need to buid an image::
 145
 146   curl -s https://raw.githubusercontent.com/bherard/energyrecorder/master/docker/recording-api.dockerfile|docker build -t energyrecorder/api -
 147
 148 Setup
 149 ^^^^^
 150 Create local folder on your host for logs and config files::
 151
 152   mkdir -p /etc/energyrecorder
 153   mkdir -p /var/log/energyrecorder
 154   mkdir -p /var/lib/influxdb
 155
 156 In /etc/energyrecorder create a configuration for logging in a file named
 157 webapp-logging.conf::
 158
 159   curl -s https://raw.githubusercontent.com/bherard/energyrecorder/master/recording-api/conf/webapp-logging.conf.sample > /etc/energyrecorder/webapp-logging.conf
 160
 161 Check configuration for this file (folders, log levels.....)
 162
 163 In /etc/energyrecorder create a configuration for the collector in a file
 164 named webapp-settings.yaml::
 165
 166   curl -s https://raw.githubusercontent.com/bherard/energyrecorder/master/recording-api/conf/webapp-settings.yaml.sample > /etc/energyrecorder/webapp-settings.yaml
 167
 168 Normaly included configuration is ready to use except username/passwer for
 169 influx (see run-container.sh bellow). Use here the admin user.
 170
 171 **IMPORTANT NOTE**: To apply a new configuration, you need to kill the running
 172 container an start a new one (see bellow)
 173
 174 Run API
 175 ^^^^^^^
 176 To run the container, you have to map folder located on the host to folders in
 177 the container (config, logs)::
 178
 179   docker run -d --name energyrecorder-api -p 8086:8086 -p 8888:8888  -v /etc/energyrecorder:/usr/local/energyrecorder/web.py/conf -v /var/log/energyrecorder/:/var/log/energyrecorder -v /var/lib/influxdb:/var/lib/influxdb energyrecorder/webapp admin-influx-user-name admin-password readonly-influx-user-name user-password
 180
 181 with
 182
 183 +---------------------------+--------------------------------------------+
 184 | Parameter name            | Description                                |
 185 +===========================+============================================+
 186 | admin-influx-user-name    | Influx user with admin grants to create    |
 187 +---------------------------+--------------------------------------------+
 188 | admin-password            | Influx password to set to admin user       |
 189 +---------------------------+--------------------------------------------+
 190 | readonly-influx-user-name | Influx user with readonly grants to create |
 191 +---------------------------+--------------------------------------------+
 192 | user-password             | Influx password to set to readonly user    |
 193 +---------------------------+--------------------------------------------+
 194
 195 **NOTE**: Local folder /var/lib/influxdb is the location web influx data are
 196 stored. You may used anything else at your convience. Just remember to define
 197 this mapping properly when running the container.
 198
 199 Power consumption Python SDK
 200 ----------------------------
 201 a Python SDK - almost not intrusive, based on python decorator to trigger call
 202 to the event API.
 203
 204 It is currently hosted in Functest repo but if other projects adopt it, a
 205 dedicated project could be created and/or it could be hosted in Releng.
 206
 207 How to use the SDK
 208 ^^^^^^^^^^^^^^^^^^
 209
 210 import the energy library::
 211
 212   import functest.energy.energy as energy
 213
 214 Notify that you want power recording in your testcase::
 215
 216   @energy.enable_recording
 217   def run(self):
 218       self.do_some_stuff1()
 219       self.do_some_stuff2()
 220
 221 If you want to register additional steps during the scenarios you can to it in
 222 2 different ways.
 223
 224 Notify step on method definition::
 225
 226     @energy.set_step("step1")
 227     def do_some_stuff1(self):
 228     ...
 229     @energy.set_step("step2")
 230     def do_some_stuff2(self):
 231
 232 Notify directly from code::
 233
 234     @energy.enable_recording
 235     def run(self):
 236       Energy.set_step("step1")
 237       self.do_some_stuff1()
 238       ...
 239       Energy.set_step("step2")
 240       self.do_some_stuff2()
 241
 242 SDK Setting
 243 ^^^^^^^^^^^
 244 Settings delivered in the project git are ready to use and assume that you will
 245 use the sahre energy recording API.
 246 If you want to use an other instance, you have to update the key
 247 "energy_recorder.api_url" in <FUNCTEST>/functest/ci/config_functest.yaml" by
 248 setting the proper hostname/IP
 249
 250 Results
 251 -------
 252 Here is an example of result comming from LF POD2. This sequence represents
 253 several CI runs in a raw. (0 power corresponds to hard reboot of the servers)
 254
 255 You may connect http://energy.opnfv.fr:3000 for more results (ask for
 256 credentials to infra team).
 257
 258 .. figure:: ../../images/energy_LF2.png
 259    :align: center
 260    :alt: Energy monitoring of LF POD2