diff options
Diffstat (limited to 'docs/release')
| -rw-r--r-- | docs/release/01-release.rst | 40 | ||||
| -rw-r--r-- | docs/release/configguide/featureconfig.rst | 60 | ||||
| -rw-r--r-- | docs/release/configguide/index.rst | 15 | ||||
| -rw-r--r-- | docs/release/configguide/postinstall.rst | 81 | ||||
| -rw-r--r-- | docs/release/release-notes/Features_to_date1.png (renamed from docs/release/Features_to_date1.png) | bin | 80139 -> 80139 bytes | |||
| -rw-r--r-- | docs/release/release-notes/Features_to_date2.png (renamed from docs/release/Features_to_date2.png) | bin | 111037 -> 111037 bytes | |||
| -rw-r--r-- | docs/release/release-notes/index.rst (renamed from docs/release/index.rst) | 13 | ||||
| -rw-r--r-- | docs/release/release-notes/release-notes.rst | 245 | ||||
| -rw-r--r-- | docs/release/scenarios/index.rst | 16 | ||||
| -rw-r--r-- | docs/release/scenarios/os-nosdn-kvm_ovs_dpdk_bar-ha/scenario.description.rst | 118 | ||||
| -rw-r--r-- | docs/release/userguide/collectd.ves.userguide.rst | 197 | ||||
| -rw-r--r-- | docs/release/userguide/feature.userguide.rst | 855 | ||||
| -rw-r--r-- | docs/release/userguide/index.rst | 23 | ||||
| -rw-r--r-- | docs/release/userguide/monitoring_interfaces.png | bin | 0 -> 94097 bytes |
14 files changed, 1617 insertions, 46 deletions
diff --git a/docs/release/01-release.rst b/docs/release/01-release.rst deleted file mode 100644 index dcf6e180..00000000 --- a/docs/release/01-release.rst +++ /dev/null @@ -1,40 +0,0 @@ -.. 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. - -Features to Date -================ -This section provides a summary of the features implemented to date and their -relevant upstream projects. - -.. Figure:: Features_to_date1.png - - Barometer features to date - -.. Figure:: Features_to_date2.png - - Barometer features to date cont. - -Please note the timeline denotes DPDK releases. - -Release B -========= -The features implemented for OPNFV release B (as part of SFQM) in DPDK include: - -* Callback API to enable TX/RX timestamping to measure latency through DPDK. -* Extended NIC statistics API for 1GB, 10GB and 40GB NICs to expose detailed - statistics for DPDK interfaces in addition to the overall aggregate statistics. -* DPDK Keep Alive. - -Release C -========= -The features implemented for OPNFV release C (as part of SFQM) include: - -* DPDK extended NIC stats API improvement; migrate from key value pairs to - using id value pairs. -* DPDK Keep Alive improvement, so that core status is exposed through a posix - shared memory object. -* collectd dpdkstat plugin that can retrieve DPDK interface statistics. -* collectd ceilometer plugin that can publish any statistics collected by - collectd to ceilometer. -* Fuel plugin support for the collectd ceilometer plugin for OPNFV. diff --git a/docs/release/configguide/featureconfig.rst b/docs/release/configguide/featureconfig.rst new file mode 100644 index 00000000..f7f7ec5e --- /dev/null +++ b/docs/release/configguide/featureconfig.rst @@ -0,0 +1,60 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +======================== +Barometer Configuration +======================== +This document provides guidelines on how to install and configure the Barometer +plugin when using Fuel as a deployment tool. The plugin name is: Collectd +Ceilometer Plugin. This plugin installs collectd on a compute node and enables +a number of collectd plugins to collect metrics and events from the platform +and send them to ceilometer. + +.. contents:: + :depth: 3 + :local: + +Pre-configuration activities +---------------------------- +The Barometer Fuel plugin can be found in /opt/opnfv on the fuel master. +To enable this plugin: + +.. code:: bash + + $ cd /opt/opnfv + $ fuel plugins --install fuel-plugin-collectd-ceilometer-1.0-1.0.0-1.noarch.rpm + +On the Fuel UI, create a new environment. +* In Settings > OpenStack Services +* Enable "Install Ceilometer and Aodh" +* In Settings > Other +* Enable "Deploy Collectd Ceilometer Plugin" +* Enable the barometer plugins you'd like to deploy using the checkboxes +* Continue with environment configuration and deployment as normal. + +Hardware configuration +---------------------- +There's no specific Hardware configuration required for this the barometer fuel plugin. + +Feature configuration +--------------------- +Describe the procedures to configure your feature on the platform in order +that it is ready to use according to the feature instructions in the platform +user guide. Where applicable you should add content in the postinstall.rst +to validate the feature is configured for use. +(checking components are installed correctly etc...) + +Upgrading the plugin +-------------------- + +From time to time new versions of the plugin may become available. + +The plugin cannot be upgraded if an active environment is using the plugin. + +In order to upgrade the plugin: + +* Copy the updated plugin file to the fuel-master. +* On the Fuel UI, reset the environment. +* On the Fuel CLI "fuel plugins --update <fuel-plugin-file>" +* On the Fuel UI, re-deploy the environment. + diff --git a/docs/release/configguide/index.rst b/docs/release/configguide/index.rst new file mode 100644 index 00000000..7f0e14a9 --- /dev/null +++ b/docs/release/configguide/index.rst @@ -0,0 +1,15 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright (c) 2017 Open Platform for NFV Project, Inc. and its contributors + +====================================== +OPNFV Barometer configuration Guide +====================================== + +.. toctree:: + :numbered: + :maxdepth: 3 + + featureconfig + postinstall + diff --git a/docs/release/configguide/postinstall.rst b/docs/release/configguide/postinstall.rst new file mode 100644 index 00000000..5ebdc031 --- /dev/null +++ b/docs/release/configguide/postinstall.rst @@ -0,0 +1,81 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +Barometer post installation procedures +====================================== +Add a brief introduction to the methods of validating the installation +according to this specific installer or feature. + +Automated post installation activities +-------------------------------------- +Describe specific post installation activities performed by the OPNFV +deployment pipeline including testing activities and reports. Refer to +the relevant testing guides, results, and release notes. + +note: this section should be singular and derived from the test projects +once we have one test suite to run for all deploy tools. This is not the +case yet so each deploy tool will need to provide (hopefully very simillar) +documentation of this. + +Barometer post configuration procedures +-------------------------------------- +The fuel plugin installs collectd and its plugins on compute nodes. +separate config files for each of the collectd plugins. These +configuration files can be found on the compute node @ +`/etc/collectd/collectd.conf.d/` directory. Each collectd plugin will +have its own configuration file with a default configuration for each +plugin. You can override any of the plugin configurations, by modifying +the configuration file and restarting the collectd service on the compute node. + +Platform components validation +--------------------------------- +1. SSH to a compute node and ensure that the collectd service is running. + +2. On the compute node, you need to inject a corrected memory error: + +.. code:: bash + + $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git + $ cd mce-inject + $ make + $ modprobe mce-inject + +Modify the test/corrected script to include the following: + +.. code:: bash + + CPU 0 BANK 0 + STATUS 0xcc00008000010090 + ADDR 0x0010FFFFFFF + +Inject the error: + +.. code:: bash + + $ ./mce-inject < test/corrected + +3. SSH to openstack controller node and query the ceilometer DB: + +.. code:: bash + + $ source openrc + $ ceilometer sample-list -m interface.if_packets + $ ceilometer sample-list -m hugepages.vmpage_number + $ ceilometer sample-list -m ovs_events.gauge + $ ceilometer sample-list -m mcelog.errors + +As you run each command above, you should see output similar to the examples below: + +.. code:: bash + | node-6.domain.tld-br-prv-link_status | ovs_events.gauge | gauge | 1.0 | None | 2017-01-20T18:18:40 | + | node-6.domain.tld-int-br-prv-link_status | ovs_events.gauge | gauge | 1.0 | None | 2017-01-20T18:18:39 | + | node-6.domain.tld-br-int-link_status | ovs_events.gauge | gauge | 0.0 | None | 2017-01-20T18:18:39 | + + | node-6.domain.tld-mm-2048Kb-free | hugepages.vmpage_number | gauge | 0.0 | None | 2017-01-20T18:17:12 | + | node-6.domain.tld-mm-2048Kb-used | hugepages.vmpage_number | gauge | 0.0 | None | 2017-01-20T18:17:12 | + +-------------------------------------+-------------------------+-------+--------+------+---------------------+ + + | bf05daca-df41-11e6-b097-5254006ed58e | node-6.domain.tld-SOCKET_0_CHANNEL_0_DIMM_any-uncorrected_memory_errors_in_24h | mcelog.errors | gauge | 0.0 | None | 2017-01-20T18:53:34 | + | bf05dacb-df41-11e6-b097-5254006ed58e | node-6.domain.tld-SOCKET_0_CHANNEL_any_DIMM_any-uncorrected_memory_errors_in_24h | mcelog.errors | gauge | 0.0 | None | 2017-01-20T18:53:34 | + | bdcb930d-df41-11e6-b097-5254006ed58e | node-6.domain.tld-SOCKET_0_CHANNEL_any_DIMM_any-uncorrected_memory_errors | mcelog.errors | gauge | 0.0 | None | 2017-01-20T18:53:33 | + diff --git a/docs/release/Features_to_date1.png b/docs/release/release-notes/Features_to_date1.png Binary files differindex 2469fe3a..2469fe3a 100644 --- a/docs/release/Features_to_date1.png +++ b/docs/release/release-notes/Features_to_date1.png diff --git a/docs/release/Features_to_date2.png b/docs/release/release-notes/Features_to_date2.png Binary files differindex edd2c074..edd2c074 100644 --- a/docs/release/Features_to_date2.png +++ b/docs/release/release-notes/Features_to_date2.png diff --git a/docs/release/index.rst b/docs/release/release-notes/index.rst index 30b2524c..44713cd3 100644 --- a/docs/release/index.rst +++ b/docs/release/release-notes/index.rst @@ -2,11 +2,12 @@ .. http://creativecommons.org/licenses/by/4.0 .. (c) OPNFV, Intel Corporation and others. -************************ -Barometer Release Notes -************************ +================================================== +OPNFV Barometer Release Notes +================================================== + .. toctree:: - :maxdepth: 3 - :numbered: + :maxdepth: 1 + + release-notes - 01-release.rst diff --git a/docs/release/release-notes/release-notes.rst b/docs/release/release-notes/release-notes.rst new file mode 100644 index 00000000..3837b1e7 --- /dev/null +++ b/docs/release/release-notes/release-notes.rst @@ -0,0 +1,245 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +====================================================================== +OPNFV Barometer Release Notes +====================================================================== + +This document provides the release notes for Danube Release of Barometer. + +.. contents:: + :depth: 3 + :local: + + +Version history +------------------ + ++--------------------+--------------------+--------------------+--------------------+ +| **Date** | **Ver.** | **Author** | **Comment** | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ +| 2017-02-16 | 0.1.0 | Maryam Tahhan | First draft | +| | | | | ++--------------------+--------------------+--------------------+--------------------+ + +Important notes +----------------- +None to date. + +Summary +------------ +The Barometer@OPNFV project adds a platform telemetry agent to compute nodes +that is capabable of retrieving platform statistics and events, and relay them +to Openstack ceilometer. The telemetry agent currently supported by Barometer +is collectd. Some additional collectd plugin were developed to add functionality +to retrieve statistics or events for: + +- Hugepages +- mcelog memory machine check exceptions +- Open vSwitch events +- Ceilometer + +Release Data +--------------- + ++--------------------------------------+--------------------------------------+ +| **Project** | Danube/barometer/barometer@opnfv | +| | | ++--------------------------------------+--------------------------------------+ +| **Repo/commit-ID** | barometer/ | +| | | ++--------------------------------------+--------------------------------------+ +| **Release designation** | Danube 1.0 | +| | | ++--------------------------------------+--------------------------------------+ +| **Release date** | | +| | | ++--------------------------------------+--------------------------------------+ +| **Purpose of the delivery** | Official OPNFV release | +| | | ++--------------------------------------+--------------------------------------+ + +Version change +^^^^^^^^^^^^^^^^ + +Module version changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- There have been no version changes. + +Document version changes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +- The Barometer@OPNFV installation guide version has changed from version 0.1 to to 0.2 + +Reason for version +^^^^^^^^^^^^^^^^^^^^ +Feature additions +~~~~~~~~~~~~~~~~~~~~~~~ + +**JIRA BACK-LOG:** + ++--------------------------------------+--------------------------------------+ +| **JIRA REFERENCE** | **SLOGAN** | +| | | ++--------------------------------------+--------------------------------------+ +| BAROMETER-38 | RAS Collectd Plugin | +| | | ++--------------------------------------+--------------------------------------+ +| BAROMETER-41 | OVS Collectd Plugin | +| | | ++--------------------------------------+--------------------------------------+ +| BAROMETER-43 | Fuel Plugin for D Release | +| | | ++--------------------------------------+--------------------------------------+ +| BAROMETER-48 | Hugepages Plugin for Collectd | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | ++--------------------------------------+--------------------------------------+ + +Bug corrections +~~~~~~~~~~~~~~~~~~~~~ + +**JIRA TICKETS:** + ++--------------------------------------+--------------------------------------+ +| **JIRA REFERENCE** | **SLOGAN** | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | ++--------------------------------------+--------------------------------------+ + +Deliverables +---------------- + +Software deliverables +^^^^^^^^^^^^^^^^^^^^^^^ + +Features to Date +~~~~~~~~~~~~~~~~ + +This section provides a summary of the features implemented to date and their +relevant upstream projects. + +.. Figure:: Features_to_date1.png + + Barometer features to date + +.. Figure:: Features_to_date2.png + + Barometer features to date cont. + +Please note the timeline denotes DPDK releases. + +Release B +~~~~~~~~~~ +The features implemented for OPNFV release B (as part of SFQM) in DPDK include: + +* Callback API to enable TX/RX timestamping to measure latency through DPDK. +* Extended NIC statistics API for 1GB, 10GB and 40GB NICs to expose detailed + statistics for DPDK interfaces in addition to the overall aggregate statistics. +* DPDK Keep Alive. + +Release C +~~~~~~~~~~ +The features implemented for OPNFV release C (as part of SFQM) include: + +* DPDK extended NIC stats API improvement; migrate from key value pairs to + using id value pairs. +* DPDK Keep Alive improvement, so that core status is exposed through a posix + shared memory object. +* collectd dpdkstat plugin that can retrieve DPDK interface statistics. +* collectd ceilometer plugin that can publish any statistics collected by + collectd to ceilometer. +* Fuel plugin support for the collectd ceilometer plugin for OPNFV. + +Documentation deliverables +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +- Configuration guide +- User guide +- Release notes +- Scenario documentation. + +Known Limitations, Issues and Workarounds +-------------------------------------------- + +System Limitations +^^^^^^^^^^^^^^^^^^^^ + +Barometer has the same limiations as the fuel project in general as regards + +- **Max number of blades* + +- **Min number of blades** + +- **Storage** + +- **Max number of networks** + +- **L3Agent** + +The only additional limitiation is the following: + +**Telemetry:** Ceilometer service needs to be configured for compute nodes. + +Known issues +^^^^^^^^^^^^^^^ + +No known issues to date. + +**JIRA TICKETS:** + ++--------------------------------------+--------------------------------------+ +| **JIRA REFERENCE** | **SLOGAN** | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ + +Workarounds +^^^^^^^^^^^^^^^^^ + +- None to date. + +Test Result +--------------- + +Barometer@OPNFV Danube RC1 has undergone QA test runs with the following results: + ++--------------------------------------+--------------------------------------+ +| **TEST-SUITE** | **Results:** | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ +| | | +| | | +| | | +| | | +| | | ++--------------------------------------+--------------------------------------+ + +References +------------ + +For more information on the OPNFV Danube release, please see: + +http://opnfv.org/danube + diff --git a/docs/release/scenarios/index.rst b/docs/release/scenarios/index.rst new file mode 100644 index 00000000..12ca9933 --- /dev/null +++ b/docs/release/scenarios/index.rst @@ -0,0 +1,16 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) 2017 Intel Corporation and Others + +============================= +OPNFV Barometer Scenarios +============================= +.. This document will be used to provide a description of the scenario for an end user. +.. You should explain the purpose of the scenario, the types of capabilities provided and +.. the unique components that make up the scenario including how they are used. + +.. toctree:: + :maxdepth: 1 + + ./os-nosdn-kvm_ovs_dpdk_bar-ha/scenario.description + diff --git a/docs/release/scenarios/os-nosdn-kvm_ovs_dpdk_bar-ha/scenario.description.rst b/docs/release/scenarios/os-nosdn-kvm_ovs_dpdk_bar-ha/scenario.description.rst new file mode 100644 index 00000000..f98a05ab --- /dev/null +++ b/docs/release/scenarios/os-nosdn-kvm_ovs_dpdk_bar-ha/scenario.description.rst @@ -0,0 +1,118 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) <optionally add copywriters name> + +=================================== +OPNFV os-nosdn-kvm_ovs_dpdk_bar-ha +=================================== + +This document provides scenario level details for Danube of Barometer. + +.. contents:: + :depth: 3 + :local: + +Introduction +--------------- +.. In this section explain the purpose of the scenario and the types of +.. capabilities provided +This scenario combines the features from the following three projects in a +single instantiation of OPNFV: + +- KVM4NFV +- OVS4NFV +- Barometer + +A distinguishing factor for this scenario vs other scenarios that integrate +Open vSwitch and KVM is that collectd (a telemetry agent) is installed on +compute nodes so that their statistics and events can be relayed to ceilometer. +These are the first steps in paving the way for Platform (NFVI) Monitoring in +OPNFV. + +For Fuel this scenario installs the latest DPDK-enabled Open vSwitch component, +KVM4NFV latest software packages for Linux Kernel and QEMU patches for +achieving low latency, and the collectd telemetry agent. + +Scenario components and composition +------------------------------------- +.. In this section describe the unique components that make up the scenario, +.. what each component provides and why it has been included in order +.. to communicate to the user the capabilities available in this scenario. + +This scenario deploys the High Availability OPNFV Cloud based on the +configurations provided in ha_nfv-kvm_ovs_bar_heat_ceilometer_scenario.yaml. +This yaml file contains following configurations and is passed as an +argument to deploy.py script + +* scenario.yaml:This configuration file defines translation between a + short deployment scenario name(os-nosdn-kvm_ovs_dpdk_bar-ha) and an actual + deployment scenario configuration file + (ha_nfv-kvm_nfv-ovs-dpdk_bar_heat_ceilometer_scenario.yaml) + +* deployment-scenario-metadata:Contains the configuration metadata like + title,version,created,comment. + +* stack-extensions:Stack extentions are opnfv added value features in form + of a fuel-plugin.Plugins listed in stack extensions are enabled and + configured. + +* dea-override-config: Used to configure the HA mode,network segmentation + types and role to node assignments. These configurations overrides + corresponding keys in the dea_base.yaml and dea_pod_override.yaml. + These keys are used to deploy multiple nodes(3 controllers,2 computes) + as mention below. + +* **Node 1**: This node has MongoDB and Controller roles. The controller + node runs the Identity service, Image Service, management portions of + Compute and Networking, Networking plug-in and the dashboard. The + Telemetry service which was designed to support billing systems for + OpenStack cloud resources uses a NoSQL database to store information. + The database typically runs on the controller node. + +* **Node 2**: This node has Controller and Ceph-osd roles. Ceph is a + massively scalable, open source, distributed storage system. It is + comprised of an object store, block store and a POSIX-compliant distributed + file system. Enabling Ceph, configures Nova to store ephemeral volumes in + RBD, configures Glance to use the Ceph RBD backend to store images, + configures Cinder to store volumes in Ceph RBD images and configures the + default number of object replicas in Ceph. + +* **Node 3**: This node has Controller role in order to achieve high + availability. + +* **Node 4**: This node has Compute role. The compute node runs the + hypervisor portion of Compute that operates tenant virtual machines + instances. By default, Compute uses KVM as the hypervisor. Collectd + will be installed on this node. + +* **Node 5**: This node has compute role. + +* dha-override-config:Provides information about the VM definition and + Network config for virtual deployment. These configurations overrides + the pod dha definition and points to the controller,compute and + fuel definition files. + +* os-nosdn-kvm_ovs_dpdk_bar-ha scenario is successful when all the 5 Nodes are + accessible, up and running. + +Scenario usage overview +---------------------------- +.. Provide a brief overview on how to use the scenario and the features available to the +.. user. This should be an "introduction" to the userguide document, and explicitly link to it, +.. where the specifics of the features are covered including examples and API's + +After installation use of the scenario traffic on the private network will +automatically be processed by the upgraded DPDK datapath. + +Limitations, Issues and Workarounds +--------------------------------------- +.. Explain scenario limitations here, this should be at a design level rather than discussing +.. faults or bugs. If the system design only provide some expected functionality then provide +.. some insight at this point. + +References +----------------- + +For more information on the OPNFV Danube release, please visit +http://www.opnfv.org/danube + diff --git a/docs/release/userguide/collectd.ves.userguide.rst b/docs/release/userguide/collectd.ves.userguide.rst new file mode 100644 index 00000000..3cf26004 --- /dev/null +++ b/docs/release/userguide/collectd.ves.userguide.rst @@ -0,0 +1,197 @@ +.. 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 User Guide +============================== +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/release/userguide/feature.userguide.rst b/docs/release/userguide/feature.userguide.rst new file mode 100644 index 00000000..2be44d33 --- /dev/null +++ b/docs/release/userguide/feature.userguide.rst @@ -0,0 +1,855 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) <optionally add copywriters name> + +=================================== +OPNFV Barometer User Guide +=================================== + +.. contents:: + :depth: 3 + :local: + +Barometer collectd plugins description +--------------------------------------- +.. Describe the specific features and how it is realised in the scenario in a brief manner +.. to ensure the user understand the context for the user guide instructions to follow. + +collectd is a daemon which collects system performance statistics periodically +and provides a variety of mechanisms to publish the collected metrics. It +supports more than 90 different input and output plugins. Input plugins +retrieve metrics and publish them to the collectd deamon, while output plugins +publish the data they receive to an end point. collectd also has infrastructure +to support thresholding and notification. + +Barometer has enabled the following collectd plugins: + +* *dpdkstat plugin*: A read plugin that retrieve stats from the DPDK extended + NIC stats API. + +* `ceilometer plugin`_: A write plugin that pushes the retrieved stats to + Ceilometer. It's capable of pushing any stats read through collectd to + Ceilometer, not just the DPDK stats. + +* *hugepages plugin*: A read plugin that retrieves the number of available + and free hugepages on a platform as well as what is available in terms of + hugepages per socket. + +* *RDT plugin*: A read plugin that provides the last level cache utilitzation and + memory bandwidth utilization + +* *Open vSwitch events Plugin*: A read plugin that retrieves events from OVS. + +* *mcelog plugin*: A read plugin that uses mcelog client protocol to check for + memory Machine Check Exceptions and sends the stats for reported exceptions + +All the plugins above are available on the collectd master, except for the +plugin as it's a python based plugin and only C plugins are accepted +by the collectd community. The ceilometer plugin lives in the OpenStack +repositories. + +Other plugins under development or existing as a pull request into collectd master: + +* *dpdkevents*: A read plugin that retrieves DPDK link status and DPDK + forwarding cores liveliness status (DPDK Keep Alive). + +* *Open vSwitch stats Plugin*: A read plugin that retrieve flow and interface + stats from OVS. + +* *SNMP Agent*: A write plugin that will act as a AgentX subagent that receives + and handles queries from SNMP master agent and returns the data collected + by read plugins. The SNMP Agent plugin handles requests only for OIDs + specified in configuration file. To handle SNMP queries the plugin gets data + from collectd and translates requested values from collectd's internal format + to SNMP format. Supports SNMP: get, getnext and walk requests. + +* *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 + +**Plugins included in the Danube release:** + +* Hugepages +* Open vSwitch Events +* Ceilometer +* Mcelog + +collectd capabilities and usage +------------------------------------ +.. Describe the specific capabilities and usage for <XYZ> feature. +.. Provide enough information that a user will be able to operate the feature on a deployed scenario. + +**NOTE** Plugins included in the OPNFV D release will be built-in to the fuel +plugin and available in the /opt/opnfv directory on the fuel master. You don't +need to clone the barometer/collectd repos to use these, but you can configure +them as shown in the examples below. Please note, the collectd plugins in OPNFV +are configured with reasonable defaults, but can be overriden. + +Building all Barometer upstreamed plugins from scratch +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +The plugins that have been merged to the collectd master branch can all be +built and configured through the barometer repository. + +**NOTE: sudo permissions are required to install collectd.** + +**NOTE: These are instructions for Ubuntu 16.04.** + +To build and install these dependencies, clone the barometer repo: + +.. code:: c + + $ git clone https://gerrit.opnfv.org/gerrit/barometer + +Install the build dependencies + +.. code:: bash + + $ ./src/install_build_deps.sh + +To install collectd as a service and install all it's dependencies: + +.. code:: bash + + $ cd barometer/src && sudo make && sudo make install + +This will install collectd as a service and the base install directory +is /opt/collectd. + +Sample configuration files can be found in '/opt/collectd/etc/collectd.conf.d' + +**Note**: Exec plugin requires non-root user to execute scripts. By default, +`collectd_exec` user is used. Barometer scripts do *not* create this user. It +needs to be manually added or exec plugin configuration has to be changed to use +other, existing user before starting collectd service. + +Please note if you are using any Open vSwitch plugins you need to run: + + +.. code:: bash + + $ sudo ovs-vsctl set-manager ptcp:6640 + +DPDK statistics plugin +^^^^^^^^^^^^^^^^^^^^^^ +Repo: https://github.com/collectd/collectd + +Branch: master + +Dependencies: DPDK (http://dpdk.org/) + +To build and install DPDK to /usr please see: +https://github.com/collectd/collectd/blob/master/docs/BUILD.dpdkstat.md + +Building and installing collectd: + +.. code:: bash + + $ git clone https://github.com/collectd/collectd.git + $ cd collectd + $ ./build.sh + $ ./configure --enable-syslog --enable-logfile --enable-debug + $ make + $ sudo make install + + +This will install collectd to /opt/collectd +The collectd configuration file can be found at /opt/collectd/etc +To configure the hugepages plugin you need to modify the configuration file to +include: + +.. code:: bash + + LoadPlugin dpdkstat + <Plugin dpdkstat> + Coremask "0xf" + ProcessType "secondary" + FilePrefix "rte" + EnabledPortMask 0xffff + </Plugin> + +For more information on the plugin parameters, please see: +https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod + +Please note if you are configuring collectd with the **static DPDK library** +you must compile the DPDK library with the -fPIC flag: + +.. code:: bash + + $ make EXTRA_CFLAGS=-fPIC + +You must also modify the configuration step when building collectd: + +.. code:: bash + + $ ./configure CFLAGS=" -lpthread -Wl,--whole-archive -Wl,-ldpdk -Wl,-lm -Wl,-lrt -Wl,-lpcap -Wl,-ldl -Wl,--no-whole-archive" + +Please also note that if you are not building and installing DPDK system-wide +you will need to specify the specific paths to the header files and libraries +using LIBDPDK_CPPFLAGS and LIBDPDK_LDFLAGS. You will also need to add the DPDK +library symbols to the shared library path using ldconfig. Note that this +update to the shared library path is not persistant (i.e. it will not survive a +reboot). Pending a merge of https://github.com/collectd/collectd/pull/2073. + +.. code:: bash + + $ ./configure LIBDPDK_CPPFLAGS="path to DPDK header files" LIBDPDK_LDFLAGS="path to DPDK libraries" + +Hugepages Plugin +^^^^^^^^^^^^^^^^^ +Repo: https://github.com/collectd/collectd + +Branch: master + +Dependencies: None, but assumes hugepages are configured. + +To configure some hugepages: + +.. code:: bash + + sudo mkdir -p /mnt/huge + sudo mount -t hugetlbfs nodev /mnt/huge + sudo echo 14336 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages + +Building and installing collectd: + +.. code:: bash + + $ git clone https://github.com/collectd/collectd.git + $ cd collectd + $ ./build.sh + $ ./configure --enable-syslog --enable-logfile --enable-hugepages --enable-debug + $ make + $ sudo make install + +This will install collectd to /opt/collectd +The collectd configuration file can be found at /opt/collectd/etc +To configure the hugepages plugin you need to modify the configuration file to +include: + +.. code:: bash + + LoadPlugin hugepages + <Plugin hugepages> + ReportPerNodeHP true + ReportRootHP true + ValuesPages true + ValuesBytes false + ValuesPercentage false + </Plugin> + +For more information on the plugin parameters, please see: +https://github.com/collectd/collectd/blob/master/src/collectd.conf.pod + +Intel RDT Plugin +^^^^^^^^^^^^^^^^ +Repo: https://github.com/collectd/collectd + +Branch: master + +Dependencies: + + * PQoS/Intel RDT library https://github.com/01org/intel-cmt-cat.git + * msr kernel module + +Building and installing PQoS/Intel RDT library: + +.. code:: bash + + $ git clone https://github.com/01org/intel-cmt-cat.git + $ cd intel-cmt-cat + $ make + $ make install PREFIX=/usr + +You will need to insert the msr kernel module: + +.. code:: bash + + $ modprobe msr + +Building and installing collectd: + +.. code:: bash + + $ git clone https://github.com/collectd/collectd.git + $ cd collectd + $ ./build.sh + $ ./configure --enable-syslog --enable-logfile --with-libpqos=/usr/ --enable-debug + $ make + $ sudo make install + +This will install collectd to /opt/collectd +The collectd configuration file can be found at /opt/collectd/etc +To configure the RDT plugin you need to modify the configuration file to +include: + +.. code:: bash + + <LoadPlugin intel_rdt> + Interval 1 + </LoadPlugin> + <Plugin "intel_rdt"> + Cores "" + </Plugin> + +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 additional 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 + +Branch: master + +Dependencies: mcelog + +Start by installing mcelog. Note: The kernel has to have CONFIG_X86_MCE +enabled. For 32bit kernels you need at least a 2.6,30 kernel. + +On ubuntu: + +.. code:: bash + + $ apt-get update && apt-get install mcelog + +Or build from source + +.. code:: bash + + $ git clone git://git.kernel.org/pub/scm/utils/cpu/mce/mcelog.git + $ cd mcelog + $ make + ... become root ... + $ make install + $ cp mcelog.service /etc/systemd/system/ + $ systemctl enable mcelog.service + $ systemctl start mcelog.service + + +Verify you got a /dev/mcelog. You can verify the daemon is running completely +by running: + +.. code:: bash + + $ mcelog --client + +This should query the information in the running daemon. If it prints nothing +that is fine (no errors logged yet). More info @ +http://www.mcelog.org/installation.html + +Modify the mcelog configuration file "/etc/mcelog/mcelog.conf" to include or +enable: + +.. code:: bash + + socket-path = /var/run/mcelog-client + +Clone and install the collectd mcelog plugin: + +.. code:: bash + + $ git clone https://github.com/maryamtahhan/collectd + $ cd collectd + $ git checkout feat_ras + $ ./build.sh + $ ./configure --enable-syslog --enable-logfile --enable-debug + $ make + $ sudo make install + +This will install collectd to /opt/collectd +The collectd configuration file can be found at /opt/collectd/etc +To configure the mcelog plugin you need to modify the configuration file to +include: + +.. code:: bash + + <LoadPlugin mcelog> + Interval 1 + </LoadPlugin> + <Plugin "mcelog"> + McelogClientSocket "/var/run/mcelog-client" + </Plugin> + +For more information on the plugin parameters, please see: +https://github.com/maryamtahhan/collectd/blob/feat_ras/src/collectd.conf.pod + +Simulating a Machine Check Exception can be done in one of 3 ways: + +* Running $make test in the mcelog cloned directory - mcelog test suite +* using mce-inject +* using mce-test + +**mcelog test suite:** + +It is always a good idea to test an error handling mechanism before it is +really needed. mcelog includes a test suite. The test suite relies on +mce-inject which needs to be installed and in $PATH. + +You also need the mce-inject kernel module configured (with +CONFIG_X86_MCE_INJECT=y), compiled, installed and loaded: + +.. code:: bash + + $ modprobe mce-inject + +Then you can run the mcelog test suite with + +.. code:: bash + + $ make test + +This will inject different classes of errors and check that the mcelog triggers +runs. There will be some kernel messages about page offlining attempts. The +test will also lose a few pages of memory in your system (not significant) +**Note this test will kill any running mcelog, which needs to be restarted +manually afterwards**. +**mce-inject:** + +A utility to inject corrected, uncorrected and fatal machine check exceptions + +.. code:: bash + + $ git clone https://git.kernel.org/pub/scm/utils/cpu/mce/mce-inject.git + $ cd mce-inject + $ make + $ modprobe mce-inject + +Modify the test/corrected script to include the following: + +.. code:: bash + + CPU 0 BANK 0 + STATUS 0xcc00008000010090 + ADDR 0x0010FFFFFFF + +Inject the error: +.. code:: bash + + $ ./mce-inject < test/corrected + +**Note: the uncorrected and fatal scripts under test will cause a platform reset. +Only the fatal script generates the memory errors**. In order to quickly +emulate uncorrected memory errors and avoid host reboot following test errors +from mce-test suite can be injected: + +.. code:: bash + + $ mce-inject mce-test/cases/coverage/soft-inj/recoverable_ucr/data/srao_mem_scrub + +**mce-test:** + +In addition an more in-depth test of the Linux kernel machine check facilities +can be done with the mce-test test suite. mce-test supports testing uncorrected +error handling, real error injection, handling of different soft offlining +cases, and other tests. + +**Corrected memory error injection:** + +To inject corrected memory errors: + +* Remove sb_edac and edac_core kernel modules: rmmod sb_edac rmmod edac_core +* Insert einj module: modprobe einj param_extension=1 +* Inject an error by specifying details (last command should be repeated at least two times): + +.. code:: bash + + $ APEI_IF=/sys/kernel/debug/apei/einj + $ echo 0x8 > $APEI_IF/error_type + $ echo 0x01f5591000 > $APEI_IF/param1 + $ echo 0xfffffffffffff000 > $APEI_IF/param2 + $ echo 1 > $APEI_IF/notrigger + $ echo 1 > $APEI_IF/error_inject + +* Check the MCE statistic: mcelog --client. Check the mcelog log for injected error details: less /var/log/mcelog. + +Open vSwitch Plugins +^^^^^^^^^^^^^^^^^^^^^ +OvS Events Repo: https://github.com/collectd/collectd + +OvS Stats Repo: https://github.com/maryamtahhan/collectd + +OvS Events Branch: master + +OvS Stats Branch:feat_ovs_stats + +Dependencies: Open vSwitch, libyajl + +On Ubuntu, install the dependencies: + +.. code:: bash + + $ sudo apt-get install libyajl-dev openvswitch-switch + +Start the Open vSwitch service: + +.. code:: bash + + $ sudo service openvswitch-switch start + +configure the ovsdb-server manager: + +.. code:: bash + + $ sudo ovs-vsctl set-manager ptcp:6640 + +Clone and install the collectd ovs plugin: + +.. code:: bash + + $ git clone $REPO + $ cd collectd + $ git checkout $BRANCH + $ ./build.sh + $ ./configure --enable-syslog --enable-logfile --enable-debug + $ make + $ sudo make install + +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 events plugin you +need to modify the configuration file to include: + +.. code:: bash + + <LoadPlugin ovs_events> + Interval 1 + </LoadPlugin> + <Plugin "ovs_events"> + Port 6640 + Socket "/var/run/openvswitch/db.sock" + Interfaces "br0" "veth0" + 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 +https://github.com/maryamtahhan/collectd/blob/feat_ovs_stats/src/collectd.conf.pod + +SNMP Agent Plugin +^^^^^^^^^^^^^^^^^ +Repo: https://github.com/maryamtahhan/collectd/ + +Branch: feat_snmp + +Dependencies: NET-SNMP library + +Start by installing net-snmp and dependencies. + +On ubuntu: + +.. code:: bash + + $ apt-get install snmp snmp-mibs-downloader snmpd libsnmp-dev + $ systemctl start snmpd.service + +Or build from source + +Become root to install net-snmp dependencies + +.. code:: bash + + $ apt-get install libperl-dev + +Clone and build net-snmp + +.. code:: bash + + $ git clone https://github.com/haad/net-snmp.git + $ cd net-snmp + $ ./configure --with-persistent-directory="/var/net-snmp" --with-systemd --enable-shared --prefix=/usr + $ make + +Become root + +.. code:: bash + + $ make install + +Copy default configuration to persistent folder + +.. code:: bash + + $ cp EXAMPLE.conf /usr/share/snmp/snmpd.conf + +Set library path and default MIB configuration + +.. code:: bash + + $ cd ~/ + $ echo export LD_LIBRARY_PATH=/usr/lib >> .bashrc + $ net-snmp-config --default-mibdirs + $ net-snmp-config --snmpconfpath + +Configure snmpd as a service + +.. code:: bash + + $ cd net-snmp + $ cp ./dist/snmpd.service /etc/systemd/system/ + $ systemctl enable snmpd.service + $ systemctl start snmpd.service + +Add the following line to snmpd.conf configuration file +"/usr/share/snmp/snmpd.conf" to make all OID tree visible for SNMP clients: + +.. code:: bash + + view systemonly included .1 + +To verify that SNMP is working you can get IF-MIB table using SNMP client +to view the list of Linux interfaces: + +.. code:: bash + + $ snmpwalk -v 2c -c public localhost IF-MIB::interfaces + +Clone and install the collectd snmp_agent plugin: + +.. code:: bash + + $ git clone https://github.com/maryamtahhan/collectd + $ cd collectd + $ git checkout feat_snmp + $ ./build.sh + $ ./configure --enable-syslog --enable-logfile --enable-debug --enable-snmp --with-libnetsnmp + $ make + $ sudo make install + +This will install collectd to /opt/collectd +The collectd configuration file can be found at /opt/collectd/etc +**SNMP Agent plugin is a generic plugin and cannot work without configuration**. +To configure the snmp_agent plugin you need to modify the configuration file to +include OIDs mapped to collectd types. The following example maps scalar +memAvailReal OID to value represented as free memory type of memory plugin: + +.. code:: bash + + LoadPlugin snmp_agent + <Plugin "snmp_agent"> + <Data "memAvailReal"> + Plugin "memory" + Type "memory" + TypeInstance "free" + OIDs "1.3.6.1.4.1.2021.4.6.0" + </Data> + </Plugin> + +For more information on the plugin parameters, please see: +https://github.com/maryamtahhan/collectd/blob/feat_snmp/src/collectd.conf.pod + +For more details on AgentX subagent, please see: +http://www.net-snmp.org/tutorial/tutorial-5/toolkit/demon/ + +Installing collectd as a service +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**NOTE**: In an OPNFV installation, collectd is installed and configured as a +service. + +Collectd service scripts are available in the collectd/contrib directory. +To install collectd as a service: + +.. code:: bash + + $ sudo cp contrib/systemd.collectd.service /etc/systemd/system/ + $ cd /etc/systemd/system/ + $ sudo mv systemd.collectd.service collectd.service + $ sudo chmod +x collectd.service + +Modify collectd.service + +.. code:: bash + + [Service] + ExecStart=/opt/collectd/sbin/collectd + EnvironmentFile=-/opt/collectd/etc/ + EnvironmentFile=-/opt/collectd/etc/ + CapabilityBoundingSet=CAP_SETUID CAP_SETGID + +Reload + +.. code:: bash + + $ sudo systemctl daemon-reload + $ sudo systemctl start collectd.service + $ sudo systemctl status collectd.service should show success + +Additional useful plugins +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Exec Plugin** : Can be used to show you when notifications are being + generated by calling a bash script that dumps notifications to file. (handy + for debug). Modify /opt/collectd/etc/collectd.conf: + +.. code:: bash + + LoadPlugin exec + <Plugin exec> + # Exec "user:group" "/path/to/exec" + NotificationExec "user" "<path to barometer>/barometer/src/collectd/collectd_sample_configs/write_notification.sh" + </Plugin> + +write_notification.sh (just writes the notification passed from exec through +STDIN to a file (/tmp/notifications)): + +.. code:: bash + + #!/bin/bash + rm -f /tmp/notifications + while read x y + do + echo $x$y >> /tmp/notifications + done + +output to /tmp/notifications should look like: + +.. code:: bash + + Severity:WARNING + Time:1479991318.806 + Host:localhost + Plugin:ovs_events + PluginInstance:br-ex + Type:gauge + TypeInstance:link_status + uuid:f2aafeec-fa98-4e76-aec5-18ae9fc74589 + + linkstate of "br-ex" interface has been changed to "DOWN" + +* **logfile plugin**: Can be used to log collectd activity. Modify + /opt/collectd/etc/collectd.conf to include: + +.. code:: bash + + LoadPlugin logfile + <Plugin logfile> + LogLevel info + File "/var/log/collectd.log" + Timestamp true + PrintSeverity false + </Plugin> + + +Monitoring Interfaces and Openstack Support +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +.. Figure:: monitoring_interfaces.png + + Monitoring Interfaces and Openstack Support + +The figure above shows the DPDK L2 forwarding application running on a compute +node, sending and receiving traffic. collectd is also running on this compute +node retrieving the stats periodically from DPDK through the dpdkstat plugin +and publishing the retrieved stats to Ceilometer through the ceilometer plugin. + +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 + +.. _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/release/userguide/index.rst b/docs/release/userguide/index.rst new file mode 100644 index 00000000..287b16be --- /dev/null +++ b/docs/release/userguide/index.rst @@ -0,0 +1,23 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) Intel and OPNFV + +=========================== +OPNFV Barometer User Guide +=========================== + +.. The feature user guide should provide an OPNFV user with enough information to +.. use the features provided by the feature project in the supported scenarios. +.. This guide should walk a user through the usage of the features once a scenario +.. has been deployed and is active according to the installation guide provided +.. by the installer project. + +.. toctree:: + :maxdepth: 1 + + feature.userguide + collectd.ves.userguide.rst +.. The feature.userguide.rst file should contain the text for this document +.. additional documents can be added to this directory and added in the right order +.. to this file as a list below. + diff --git a/docs/release/userguide/monitoring_interfaces.png b/docs/release/userguide/monitoring_interfaces.png Binary files differnew file mode 100644 index 00000000..e57c4aa1 --- /dev/null +++ b/docs/release/userguide/monitoring_interfaces.png |
