summaryrefslogtreecommitdiffstats
path: root/docs/userguide
diff options
context:
space:
mode:
Diffstat (limited to 'docs/userguide')
-rw-r--r--docs/userguide/collectd.userguide.rst126
-rw-r--r--docs/userguide/collectd.ves.userguide.rst196
-rw-r--r--docs/userguide/index.rst1
3 files changed, 308 insertions, 15 deletions
diff --git a/docs/userguide/collectd.userguide.rst b/docs/userguide/collectd.userguide.rst
index 1030e46e..42fe308d 100644
--- a/docs/userguide/collectd.userguide.rst
+++ b/docs/userguide/collectd.userguide.rst
@@ -42,8 +42,10 @@ Other plugins under development or existing as a pull request into collectd mast
collectd metrics to relavent OIDs. Will only support SNMP: get, getnext and
walk.
-* Legacy/IPMI: A read plugin that will report platform thermals, voltages,
- fanspeed....
+* Legacy/IPMI: A read plugin that reports platform thermals, voltages,
+ fanspeed, current, flow, power etc. Also, the plugin monitors Intelligent
+ Platform Management Interface (IPMI) System Event Log (SEL) and sends the
+ collectd notification once a new record appears in the SEL.
Building collectd with the Barometer plugins and installing the dependencies
=============================================================================
@@ -252,6 +254,87 @@ include:
For more information on the plugin parameters, please see:
https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
+IPMI Plugin
+-----------
+Repo: https://github.com/maryamtahhan/collectd
+
+Branch: feat_ipmi_events, feat_ipmi_analog
+
+Dependencies: OpenIPMI library
+
+The IPMI plugin is already implemented in the latest collectd and sensors
+like temperature, voltage, fanspeed, current are already supported there.
+The list of supported IPMI sensors has been extended and sensors like flow,
+power are supported now. Also, a System Event Log (SEL) notification feature
+has been introduced.
+
+* The feat_ipmi_events branch includes new SEL feature support in collectd
+ IPMI plugin. If this feature is enabled, the collectd IPMI plugin will
+ dispatch notifications about new events in System Event Log.
+
+* The feat_ipmi_analog branch includes the support of extended IPMI sensors in
+ collectd IPMI plugin.
+
+On Ubuntu, install the dependencies:
+
+.. code:: bash
+
+ $ sudo apt-get install libopenipmi-dev
+
+Enable IPMI support in the kernel:
+
+.. code:: bash
+
+ $ sudo modprobe ipmi_devintf
+ $ sudo modprobe ipmi_si
+
+**Note**: If HW supports IPMI, the ``/dev/ipmi0`` character device will be
+created.
+
+Clone and install the collectd IPMI plugin:
+
+.. code:: bash
+
+ $ git clone https://github.com/maryamtahhan/collectd
+ $ cd collectd
+ $ git checkout $BRANCH
+ $ ./build.sh
+ $ ./configure --enable-syslog --enable-logfile --enable-debug
+ $ make
+ $ sudo make install
+
+Where $BRANCH is feat_ipmi_events or feat_ipmi_analog.
+
+This will install collectd to default folder ``/opt/collectd``. The collectd
+configuration file (``collectd.conf``) can be found at ``/opt/collectd/etc``. To
+configure the IPMI plugin you need to modify the file to include:
+
+.. code:: bash
+
+ LoadPlugin ipmi
+ <Plugin ipmi>
+ SELEnabled true # only feat_ipmi_events branch supports this
+ </Plugin>
+
+**Note**: By default, IPMI plugin will read all available analog sensor values,
+dispatch the values to collectd and send SEL notifications.
+
+For more information on the IPMI plugin parameters and SEL feature configuration,
+please see:
+
+https://github.com/maryamtahhan/collectd/blob/feat_ipmi_events/src/collectd.conf.pod
+
+Extended analog sensors support doesn't require addition configuration. The usual
+collectd IPMI documentation can be used.
+
+https://collectd.org/wiki/index.php/Plugin:IPMI
+https://collectd.org/documentation/manpages/collectd.conf.5.shtml#plugin_ipmi
+
+IPMI documentation:
+
+https://www.kernel.org/doc/Documentation/IPMI.txt
+http://www.intel.com/content/www/us/en/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html
+
Mcelog Plugin:
--------------
Repo: https://github.com/collectd/collectd
@@ -450,7 +533,6 @@ configure the ovsdb-server manager:
$ sudo ovs-vsctl set-manager ptcp:6640
-
Clone and install the collectd ovs plugin:
.. code:: bash
@@ -467,15 +549,14 @@ where $REPO is one of the repos listed at the top of this section.
Where $BRANCH is master or feat_ovs_stats.
-This will install collectd to /opt/collectd
-The collectd configuration file can be found at /opt/collectd/etc
-To configure the OVS plugins you need to modify the configuration file to
-include:
+This will install collectd to /opt/collectd. The collectd configuration file
+can be found at /opt/collectd/etc. To configure the OVS events plugin you
+need to modify the configuration file to include:
.. code:: bash
<LoadPlugin ovs_events>
- Interval 1
+ Interval 1
</LoadPlugin>
<Plugin "ovs_events">
Port 6640
@@ -484,6 +565,21 @@ include:
SendNotification false
</Plugin>
+To configure the OVS stats plugin you need to modify the configuration file
+to include:
+
+.. code:: bash
+
+ <LoadPlugin ovs_stats>
+ Interval 1
+ </LoadPlugin>
+ <Plugin ovs_stats>
+ Port "6640"
+ Address "127.0.0.1"
+ Socket "/var/run/openvswitch/db.sock"
+ Bridges "br0" "br_ext"
+ </Plugin>
+
For more information on the plugin parameters, please see:
https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod
and
@@ -594,13 +690,13 @@ To see this demo in action please checkout: `Barometer OPNFV Summit demo`_
References
----------
-[1] https://collectd.org/wiki/index.php/Naming_schema
-[2] https://github.com/collectd/collectd/blob/master/src/daemon/plugin.h
-[3] https://collectd.org/wiki/index.php/Value_list_t
-[4] https://collectd.org/wiki/index.php/Data_set
-[5] https://collectd.org/documentation/manpages/types.db.5.shtml
-[6] https://collectd.org/wiki/index.php/Data_source
-[7] https://collectd.org/wiki/index.php/Meta_Data_Interface
+.. [1] https://collectd.org/wiki/index.php/Naming_schema
+.. [2] https://github.com/collectd/collectd/blob/master/src/daemon/plugin.h
+.. [3] https://collectd.org/wiki/index.php/Value_list_t
+.. [4] https://collectd.org/wiki/index.php/Data_set
+.. [5] https://collectd.org/documentation/manpages/types.db.5.shtml
+.. [6] https://collectd.org/wiki/index.php/Data_source
+.. [7] https://collectd.org/wiki/index.php/Meta_Data_Interface
.. _Barometer OPNFV Summit demo: https://prezi.com/kjv6o8ixs6se/software-fastpath-service-quality-metrics-demo/
.. _ceilometer plugin: https://github.com/openstack/collectd-ceilometer-plugin/tree/stable/mitaka
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
+
+ <LoadPlugin python>
+ Globals true
+ </LoadPlugin>
+
+ <Plugin python>
+ ModulePath "/path/to/your/python/modules"
+ LogTraces true
+ Interactive false
+ Import "ves_plugin"
+ <Module ves_plugin>
+ # VES plugin configuration (see next section below)
+ </Module>
+ </Plugin>
+
+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
+
+ <Plugin virt>
+ Connection "qemu:///system"
+ RefreshInterval 60
+ HostnameFormat uuid
+ </Plugin>
+
+Please ensure that the cpu plugin is enabled and configured as follows
+
+.. code:: bash
+
+ LoadPlugin cpu
+
+ <Plugin cpu>
+ ReportByCpu false
+ ValuesPercentage true
+ </Plugin>
+
+Please ensure that the aggregation plugin is enabled and configured as follows
+
+.. code:: bash
+
+ LoadPlugin aggregation
+
+ <Plugin aggregation>
+ <Aggregation>
+ Plugin "cpu"
+ Type "percent"
+ GroupBy "Host"
+ GroupBy "TypeInstance"
+ SetPlugin "cpu-aggregation"
+ CalculateAverage true
+ </Aggregation>
+ </Plugin>
+
+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
+
+ <Plugin uuid>
+ UUIDFile "/etc/uuid"
+ </Plugin>
+
+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
+
+ <Plugin "threshold">
+ <Plugin "cpu-aggregation">
+ <Type "percent">
+ WarningMin 50.0
+ WarningMax 100.0
+ FailureMin 30.0
+ FailureMax 100.0
+ Instance "idle"
+ Hits 1
+ </Type>
+ </Plugin>
+ </Plugin>
+
+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