From 0800146a1ed466e96dfd4a5909df1f683d1013db Mon Sep 17 00:00:00 2001 From: "maryam.tahhan" Date: Mon, 9 Jan 2017 17:13:27 +0000 Subject: collectd VES agent: collectd VES agent code Add the code for the VES collectd agent to barometer. Change-Id: I39d9b0af4003e381fcaee1a8cbd38d9e54d9ac33 Signed-off-by: Volodymyr Mytnyk Signed-off-by: Maryam Tahhan --- docs/userguide/collectd.ves.userguide.rst | 196 ++++++++++++++++++++++++++++++ docs/userguide/index.rst | 1 + 2 files changed, 197 insertions(+) create mode 100644 docs/userguide/collectd.ves.userguide.rst (limited to 'docs') diff --git a/docs/userguide/collectd.ves.userguide.rst b/docs/userguide/collectd.ves.userguide.rst new file mode 100644 index 00000000..a83b6469 --- /dev/null +++ b/docs/userguide/collectd.ves.userguide.rst @@ -0,0 +1,196 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) OPNFV, Intel Corporation and others. + +collectd VES plugin +=================== +The Barometer repository contains a python based write plugin for VES. + +The plugin currently supports pushing platform relevant metrics through the +additional measurements field for VES. + +**Please note**: Hardcoded configuration values will be modified so that they +are configurable through the configuration file. + +Installation Instructions: +-------------------------- +1. Clone this repo +2. Install collectd + +.. code:: bash + + $ sudo apt-get install collectd + +3. Modify the collectd configuration script: `/etc/collectd/collectd.conf` + +.. code:: bash + + + Globals true + + + + ModulePath "/path/to/your/python/modules" + LogTraces true + Interactive false + Import "ves_plugin" + + # VES plugin configuration (see next section below) + + + +where "/path/to/your/python/modules" is the path to where you cloned this repo + +VES python plugin configuration description: +-------------------------------------------- + +**Note** Details of the Vendor Event Listener REST service + +REST resources are defined with respect to a ServerRoot: + +.. code:: bash + + ServerRoot = https://{Domain}:{Port}/{optionalRoutingPath} + +REST resources are of the form: + +.. code:: bash + + {ServerRoot}/eventListener/v{apiVersion}` + {ServerRoot}/eventListener/v{apiVersion}/{topicName}` + {ServerRoot}/eventListener/v{apiVersion}/eventBatch` + + +**Domain** *"host"* +* VES domain name. It can be IP address or hostname of VES collector +(default: `127.0.0.1`) + +**Port** *port* +* VES port (default: `30000`) + +**Path** *"path"* +* Used as the "optionalRoutingPath" element in the REST path (default: `empty`) + +**Topic** *"path"* +* Used as the "topicName" element in the REST path (default: `empty`) + +**UseHttps** *true|false* +* Allow plugin to use HTTPS instead of HTTP (default: `false`) + +**Username** *"username"* +* VES collector user name (default: `empty`) + +**Password** *"passwd"* +* VES collector password (default: `empty`) + +**FunctionalRole** *"role"* +* Used as the 'functionalRole' field of 'commonEventHeader' event (default: +`Collectd VES Agent`) + +**GuestRunning** *true|false* +* This option is used if the collectd is running on a guest machine, e.g this +option should be set to `true` in this case. Defaults to `false`. + +Other collectd.conf configurations +---------------------------------- +Please ensure that FQDNLookup is set to false + +.. code:: bash + + FQDNLookup false + + +Please ensure that the virt plugin is enabled and configured as follows. This configuration +is is required only on a host side ('GuestRunning' = false). + +.. code:: bash + + LoadPlugin virt + + + Connection "qemu:///system" + RefreshInterval 60 + HostnameFormat uuid + + +Please ensure that the cpu plugin is enabled and configured as follows + +.. code:: bash + + LoadPlugin cpu + + + ReportByCpu false + ValuesPercentage true + + +Please ensure that the aggregation plugin is enabled and configured as follows + +.. code:: bash + + LoadPlugin aggregation + + + + Plugin "cpu" + Type "percent" + GroupBy "Host" + GroupBy "TypeInstance" + SetPlugin "cpu-aggregation" + CalculateAverage true + + + +If plugin is running on a guest side, it is important to enable uuid plugin +too. In this case the hostname in event message will be represented as UUID +instead of system host name. + +LoadPlugin uuid + +If custom UUID needs to be provided, the following configuration is required in collectd.conf +file: + +.. code:: bash + + + UUIDFile "/etc/uuid" + + +Where "/etc/uuid" is a file containing custom UUID. + +Please also ensure that the following plugins are enabled: + +.. code:: bash + + LoadPlugin disk + LoadPlugin interface + LoadPlugin memory + +VES plugin notification example +------------------------------- + +A good example of collectD notification is monitoring of CPU load on a host or guest using +'threshold' plugin. The following configuration will setup VES plugin to send 'Fault' +event every time a CPU idle value is out of range (e.g.: WARNING: CPU-IDLE < 50%, CRITICAL: +CPU-IDLE < 30%) and send 'Fault' NORMAL event if CPU idle value is back to normal. + +.. code:: bash + + LoadPlugin threshold + + + + + WarningMin 50.0 + WarningMax 100.0 + FailureMin 30.0 + FailureMax 100.0 + Instance "idle" + Hits 1 + + + + +More detailed information on how to configure collectD thresholds(memory, cpu +etc.) can be found here at +https://collectd.org/documentation/manpages/collectd-threshold.5.shtml diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst index bf62a43d..aaeadf91 100644 --- a/docs/userguide/index.rst +++ b/docs/userguide/index.rst @@ -16,3 +16,4 @@ Barometer user guide :maxdepth: 3 collectd.userguide.rst + collectd.ves.userguide.rst -- cgit 1.2.3-korg