diff options
Diffstat (limited to 'docs/userguide')
| -rw-r--r-- | docs/userguide/collectd.userguide.rst | 126 | ||||
| -rw-r--r-- | docs/userguide/collectd.ves.userguide.rst | 196 | ||||
| -rw-r--r-- | docs/userguide/index.rst | 1 |
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 |