From cf621db3ee86bdccb78bdf304a6189e853b5e060 Mon Sep 17 00:00:00 2001 From: "Mytnyk, Volodymyr" Date: Tue, 30 May 2017 14:49:32 +0100 Subject: VES userguide: Updated documentation. Updated VES documentation to reflect latest changes in the VES plugin and VES schema. Change-Id: I618d7e181a1c6de698e44b7be74d4358513d2441 Signed-off-by: Mytnyk, Volodymyr --- docs/release/userguide/collectd.ves.userguide.rst | 74 +++++++++-------------- 1 file changed, 27 insertions(+), 47 deletions(-) diff --git a/docs/release/userguide/collectd.ves.userguide.rst b/docs/release/userguide/collectd.ves.userguide.rst index 7ed6be9e..fdf90187 100644 --- a/docs/release/userguide/collectd.ves.userguide.rst +++ b/docs/release/userguide/collectd.ves.userguide.rst @@ -40,7 +40,8 @@ Installation Instructions: -where "/path/to/your/python/modules" is the path to where you cloned this repo +where "/path/to/your/python/modules" is the path to ves_plugin.py, +which is located in this repo. VES python plugin configuration description: -------------------------------------------- @@ -87,16 +88,12 @@ REST resources are of the form: 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`. - **SendEventInterval** *interval* This configuration option controls how often (sec) collectd data is sent to Vendor Event Listener (default: `20`) **ApiVersion** *version* - Used as the "apiVersion" element in the REST path (default: `1`) + Used as the "apiVersion" element in the REST path (default: `5.1`) Other collectd.conf configurations ---------------------------------- @@ -106,8 +103,7 @@ Please ensure that FQDNLookup is set to false 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). +Please ensure that the virt plugin is enabled and configured as follows. .. code:: bash @@ -117,8 +113,14 @@ is is required only on a host side ('GuestRunning' = false). Connection "qemu:///system" RefreshInterval 60 HostnameFormat uuid + PluginInstanceFormat name + ExtraStats "cpu_util perf" + +.. note:: For more detailed information on the `virt` plugin configuration, + requirements etc., please see the userguide of the collectd virt plugin. + Please ensure that the cpu plugin is enabled and configured as follows .. code:: bash @@ -130,36 +132,13 @@ Please ensure that the cpu plugin is enabled and configured as follows ValuesPercentage true -**Note**: The `ReportByCpu` option should be set to `true` (default) if VES pugin -is running on guest machine ('GuestRunning' = true). - -Please ensure that the aggregation plugin is enabled and configured as follows -(required if 'GuestRunning' = true) - -.. 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. +To report the host name as a UUID the uuid plugin can be used. .. code:: bash - LoadPlugin uuid + LoadPlugin uuid -If custom UUID needs to be provided, the following configuration is required in collectd.conf +If a custom UUID needs to be provided, the following configuration is required in collectd.conf file: .. code:: bash @@ -181,28 +160,29 @@ Please also ensure that the following plugins are enabled: 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. +A good example of collectD notification is monitoring of the total CPU usage on a VM +using the 'threshold' plugin. The following configuration will setup VES plugin to send 'Fault' +event every time a total VM CPU value is out of range (e.g.: WARNING: VM CPU TOTAL > 50%, +CRITICAL: VM CPU TOTAL > 96%) and send 'Fault' NORMAL event if the CPU value is back +to normal. In the example below, there is one VM with two CPUs configured which is running +on the host with a total of 48 cores. Thus, the threshold value 2.08 (100/48) means that +one CPU of the VM is fully loaded (e.g.: 50% of total CPU usage of the VM) and 4.0 means +96% of total CPU usage of the VM. Those values can also be obtained by virt-top +command line tool. .. code:: bash LoadPlugin threshold - + - WarningMin 50.0 - WarningMax 100.0 - FailureMin 30.0 - FailureMax 100.0 - Instance "idle" - Hits 1 + WarningMax 2.08 + FailureMax 4.0 + Instance "virt_cpu_total" -More detailed information on how to configure collectD thresholds(memory, cpu -etc.) can be found here at +More detailed information on how to configure collectD thresholds can be found at https://collectd.org/documentation/manpages/collectd-threshold.5.shtml -- cgit 1.2.3-korg