docs/release/userguide/collectd.ves.userguide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. (c) OPNFV, Intel Corporation and others.
   4
   5 ==========================
   6 VES Application User Guide
   7 ==========================
   8 The Barometer repository contains a python based application for VES.
   9
  10 The application currently supports pushing platform relevant metrics through the
  11 additional measurements field for VES.
  12
  13 Collectd has a write_kafka plugin that will send collectd metrics and values to
  14 a Kafka Broker.
  15 The VES application uses Kafka Consumer to receive metrics from the Kafka
  16 Broker.
  17
  18 Installation Instructions:
  19 --------------------------
  20 1. Clone this repo:
  21
  22     .. code:: bash
  23
  24         git clone https://gerrit.opnfv.org/gerrit/barometer
  25
  26 2. Install collectd
  27
  28     .. code:: bash
  29
  30         $ sudo apt-get install collectd
  31
  32     CentOS 7.x use:
  33
  34     .. code:: bash
  35
  36         $ sudo yum install collectd
  37
  38     .. note:: You may need to add epel repository if the above does not work.
  39
  40     .. code:: bash
  41
  42         $ sudo yun install epel-release
  43
  44 3. Modify the collectd configuration script: `/etc/collectd/collectd.conf`
  45
  46     .. code:: bash
  47
  48         <Plugin write_kafka>
  49             Property "metadata.broker.list" "localhost:9092"
  50             <Topic "collectd">
  51                 Format JSON
  52             </Topic>
  53         </Plugin>
  54
  55     .. note::
  56
  57         The above configuration is for a single host setup. Simply change localhost to remote
  58         server IP addess or hostname.
  59
  60 Install Kafka Broker
  61 --------------------
  62
  63 1. Dependencies: install JAVA & Zookeeper.
  64
  65     JAVA:
  66
  67     .. code:: bash
  68
  69         $ sudo apt install default-jre
  70
  71     CentOS 7.x use:
  72
  73     .. code:: bash
  74
  75         $ sudo yum install java-1.6.0-openjdk
  76
  77     Zookeeper:
  78
  79     .. code:: bash
  80
  81         $ sudo apt install zookeeperd
  82
  83     CentOS 7.x use:
  84
  85     .. code:: bash
  86
  87         $ sudo yum install zookeeper
  88
  89     .. note:: You may need to add the the repository that contains zookeeper
  90
  91     .. code:: bash
  92
  93         $ sudo yum install
  94         https://archive.cloudera.com/cdh5/one-click-install/redhat/7/x86_64/cloudera-cdh-5-0.x86_64.rpm
  95
  96     CentOS 7.x start zookeeper:
  97
  98     .. code:: bash
  99
 100         $ sudo zookeeper-server start
 101
 102     To test if Zookeeper is running as a daemon.
 103
 104     .. code:: bash
 105
 106         $ sudo telnet localhost 2181
 107
 108     Type 'ruok' & hit enter.
 109     Expected response is 'imok'. Zookeeper is running fine.
 110
 111     .. note::
 112
 113         VES doesn't work with version 0.9.4 of kafka-python.
 114         The recommended/tested version is 1.3.3.
 115
 116     .. code:: bash
 117
 118         $ sudo pip install kafka-python
 119
 120 2. Download Kafka:
 121
 122     .. code:: bash
 123
 124         $ sudo wget "http://www-eu.apache.org/dist/kafka/0.11.0.0/kafka_2.11-0.11.0.0.tgz"
 125
 126 3. Extract the archive:
 127
 128     .. code:: bash
 129
 130         $ sudo tar -xvzf kafka_2.11-0.11.0.0.tgz
 131
 132 4. Configure Kafka Server:
 133
 134     .. code:: bash
 135
 136         $ sudo vi kafka_2.11-0.11.0.0/config/server.properties
 137
 138     By default Kafka does not allow you to delete topics. Please uncomment:
 139
 140     .. code:: bash
 141
 142         delete.topic.enable=true
 143
 144 5. Start the Kafka Server.
 145
 146     Run 'kafka-server-start.sh' with nohup as a background process:
 147
 148     .. code:: bash
 149
 150         $ sudo nohup kafka_2.11-0.11.0.0/bin/kafka-server-start.sh \
 151           kafka_2.11-0.11.0.0/config/server.properties > kafka_2.11-0.11.0.0/kafka.log 2>&1 &
 152
 153 6. Test Kafka Broker Installation
 154
 155     To test if the installation worked correctly there are two scripts, producer and consumer scripts.
 156     These will allow you to see messages pushed to broker and receive from broker.
 157
 158     Producer (Publish "Hello World"):
 159
 160     .. code:: bash
 161
 162         $ echo "Hello, World" | kafka_2.11-0.11.0.0/bin/kafka-console-producer.sh \
 163           --broker-list localhost:9092 --topic TopicTest > /dev/null
 164
 165     Consumer (Receive "Hello World"):
 166
 167     .. code:: bash
 168
 169         $ kafka_2.11-0.11.0.0/bin/kafka-console-consumer.sh --zookeeper \
 170           localhost:2181 --topic TopicTest --from-beginning
 171
 172
 173 VES application configuration description:
 174 ------------------------------------------
 175
 176 Within the VES directory there is a configuration file called 'ves_app.conf'.
 177
 178 .. note:: Details of the Vendor Event Listener REST service
 179
 180 REST resources are defined with respect to a ServerRoot:
 181
 182 .. code:: bash
 183
 184     ServerRoot = https://{Domain}:{Port}/{optionalRoutingPath}
 185
 186 REST resources are of the form:
 187
 188 .. code:: bash
 189
 190     {ServerRoot}/eventListener/v{apiVersion}`
 191     {ServerRoot}/eventListener/v{apiVersion}/{topicName}`
 192     {ServerRoot}/eventListener/v{apiVersion}/eventBatch`
 193
 194 **Domain** *"host"*
 195   VES domain name. It can be IP address or hostname of VES collector
 196   (default: `127.0.0.1`)
 197
 198 **Port** *port*
 199   VES port (default: `30000`)
 200
 201 **Path** *"path"*
 202   Used as the "optionalRoutingPath" element in the REST path (default: `empty`)
 203
 204 **Topic** *"path"*
 205   Used as the "topicName" element in the REST  path (default: `empty`)
 206
 207 **UseHttps** *true|false*
 208   Allow application to use HTTPS instead of HTTP (default: `false`)
 209
 210 **Username** *"username"*
 211   VES collector user name (default: `empty`)
 212
 213 **Password** *"passwd"*
 214   VES collector password (default: `empty`)
 215
 216 **FunctionalRole** *"role"*
 217   Used as the 'functionalRole' field of 'commonEventHeader' event (default:
 218   `Collectd VES Agent`)
 219
 220 **SendEventInterval** *interval*
 221   This configuration option controls how often (sec) collectd data is sent to
 222   Vendor Event Listener (default: `20`)
 223
 224 **ApiVersion** *version*
 225   Used as the "apiVersion" element in the REST path (default: `5.1`)
 226
 227 **KafkaPort** *port*
 228   Kafka Port (Default ``9092``)
 229
 230 **KafkaBroker** *host*
 231   Kafka Broker domain name. It can be an IP address or hostname of local or remote server
 232   (default: localhost)
 233
 234 Other collectd.conf configurations
 235 ----------------------------------
 236 Please ensure that FQDNLookup is set to false
 237
 238 .. code:: bash
 239
 240     FQDNLookup   false
 241
 242 Please ensure that the virt plugin is enabled and configured as follows.
 243
 244 .. code:: bash
 245
 246     LoadPlugin virt
 247
 248     <Plugin virt>
 249             Connection "qemu:///system"
 250             RefreshInterval 60
 251             HostnameFormat uuid
 252             PluginInstanceFormat name
 253             ExtraStats "cpu_util perf"
 254     </Plugin>
 255
 256
 257 .. note:: For more detailed information on the `virt` plugin configuration,
 258   requirements etc., please see the userguide of the collectd virt plugin.
 259
 260 Please ensure that the cpu plugin is enabled and configured as follows
 261
 262 .. code:: bash
 263
 264     LoadPlugin cpu
 265
 266     <Plugin cpu>
 267         ReportByCpu false
 268         ValuesPercentage true
 269     </Plugin>
 270
 271 .. note::
 272
 273     The ``ReportByCpu`` option should be set to `true` (default)
 274     if VES application is running on guest machine ('GuestRunning' = true).
 275
 276 Please ensure that the aggregation plugin is enabled and configured as follows
 277 (required if 'GuestRunning' = true)
 278
 279 .. code:: bash
 280
 281     LoadPlugin aggregation
 282
 283     <Plugin aggregation>
 284         <Aggregation>
 285                 Plugin "cpu"
 286                 Type "percent"
 287                 GroupBy "Host"
 288                 GroupBy "TypeInstance"
 289                 SetPlugin "cpu-aggregation"
 290                 CalculateAverage true
 291         </Aggregation>
 292     </Plugin>
 293
 294 If application is running on a guest side, it is important to enable uuid plugin
 295 too. In this case the hostname in event message will be represented as UUID
 296 instead of system host name.
 297
 298 .. code:: bash
 299
 300     LoadPlugin uuid
 301
 302 If a custom UUID needs to be provided, the following configuration is required in collectd.conf
 303 file:
 304
 305 .. code:: bash
 306
 307     <Plugin uuid>
 308         UUIDFile "/etc/uuid"
 309     </Plugin>
 310
 311 Where "/etc/uuid" is a file containing custom UUID.
 312
 313 Please also ensure that the following plugins are enabled:
 314
 315 .. code:: bash
 316
 317     LoadPlugin disk
 318     LoadPlugin interface
 319     LoadPlugin memory
 320
 321 VES application with collectd notifications example
 322 ---------------------------------------------------
 323
 324 A good example of collectD notification is monitoring of the total CPU usage on a VM
 325 using the 'threshold' plugin. The following configuration will setup VES plugin to send 'Fault'
 326 event every time a total VM CPU value is out of range (e.g.: WARNING: VM CPU TOTAL > 50%,
 327 CRITICAL: VM CPU TOTAL > 96%) and send 'Fault' NORMAL event if the CPU value is back
 328 to normal. In the example below, there is one VM with two CPUs configured which is running
 329 on the host with a total of 48 cores. Thus, the threshold value 2.08 (100/48) means that
 330 one CPU of the VM is fully loaded (e.g.: 50% of total CPU usage of the VM) and 4.0 means
 331 96% of total CPU usage of the VM. Those values can also be obtained by virt-top
 332 command line tool.
 333
 334 .. code:: bash
 335
 336     LoadPlugin threshold
 337
 338     <Plugin "threshold">
 339         <Plugin "virt">
 340             <Type "percent">
 341                 WarningMax    2.08
 342                 FailureMax    4.0
 343                 Instance      "virt_cpu_total"
 344             </Type>
 345         </Plugin>
 346     </Plugin>
 347
 348 More detailed information on how to configure collectD thresholds can be found at
 349 https://collectd.org/documentation/manpages/collectd-threshold.5.shtml