x
/
fuel-plugin-lma-collector
Code Issues Proposed changes

[docs] Edits the plugin guide structure 

Edits the table of contents and overall structure
of the StackLight Collector plugin for Fuel documentation.

Change-Id: I5059b20eb1fcce19ae6775acc841d33ebb7248ed
This commit is contained in:
Maria Zlatkova 2016-07-12 15:39:22 +03:00
parent 8dfefb5f33
commit 8950baf07d
15 changed files with 186 additions and 162 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/user/source/appendix_c.rst → doc/user/source/appendix_alarms.rst
View File

@ -1,7 +1,7 @@
.. _alarm_list:
.. _alarms:
Appendix C: List of built-in alarms
===================================
List of built-in alarms
-----------------------
Here is a list of all the alarms that are built-in in StackLight::

34
doc/user/source/appendix_b.rst → doc/user/source/appendix_metrics.rst
View File

@ -1,81 +1,81 @@
.. _metric_list:
.. _metrics:
Appendix B: List of metrics
===========================
List of metrics
---------------
Here is a list of metrics that are emitted by the StackLight Collector.
They are listed by category then by metric name.
System
------
++++++
.. include:: metrics/system.rst
Apache
------
++++++
.. include:: metrics/apache.rst
MySQL
-----
+++++
.. include:: metrics/mysql.rst
RabbitMQ
--------
++++++++
.. include:: metrics/rabbitmq.rst
HAProxy
-------
+++++++
.. include:: metrics/haproxy.rst
Memcached
---------
+++++++++
.. include:: metrics/memcached.rst
Libvirt
-------
+++++++
.. include:: metrics/libvirt.rst
OpenStack
---------
+++++++++
.. include:: metrics/openstack.rst
Ceph
----
++++
.. include:: metrics/ceph.rst
Pacemaker
---------
+++++++++
.. include:: metrics/pacemaker.rst
Clusters
--------
++++++++
.. include:: metrics/clusters.rst
Self Monitoring
---------------
+++++++++++++++
.. include:: metrics/lma.rst
Elasticsearch
-------------
+++++++++++++
.. include:: metrics/elasticsearch.rst
InfluxDB
--------
++++++++
.. include:: metrics/influxdb.rst

2
doc/user/source/conf.py
View File

@ -44,7 +44,7 @@ master_doc = 'index'
# General information about the project.
project = u'The StackLight Collector Plugin for Fuel'
copyright = u'2015, Mirantis Inc.'
copyright = u'2016, Mirantis Inc.'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the

39
doc/user/source/alarms.rst → doc/user/source/configure_alarms.rst
View File

@ -1,9 +1,4 @@
.. _alarm_guide:
Alarms Configuration Guide
============================
.. _alarm_overview:
.. _configure_alarms:
Overview
--------
@ -65,7 +60,7 @@ The StackLight stream processing pipeline workflow is shown in the figure below:
:alt: Message flow for the AFD and GSE metrics
:align: center
The AFD and GSE Plugins
The AFD and GSE plugins
-----------------------
In the current version of StackLight, there are three types of GSE plugins:
@ -93,7 +88,7 @@ The health status exposed in the GSE metrics is as follow:
health status of the cluster.
* *Okay*: None of the above was found to be true.
The AFD and GSE Persisters
The AFD and GSE persisters
--------------------------
The AFD and GSE metrics are also consumed by other types
@ -117,7 +112,7 @@ AFD and GSE metrics.
.. _alarm_configuration:
Alarms Configuration
Alarms configuration
--------------------
StackLight comes with a predefined set of alarm rules.
@ -136,8 +131,8 @@ of that file.
.. _alarm_structure:
Alarm Structure
~~~~~~~~~~~~~~~
Alarm structure
+++++++++++++++
An alarm rule is defined declaratively using the YAML syntax
as shown in the example below::
@ -283,8 +278,8 @@ as shown in the example below::
| The threshold of the alarm rule
How to modify or create an alarm?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Modify or create an alarm
+++++++++++++++++++++++++
To modify (or create) an alarm, you need to edit the
``/etc/hiera/override/alarming.yaml`` file.
@ -435,7 +430,7 @@ This file has four sections:
.. _aggreg_correl_config:
Aggregation and Correlation Configuration
Aggregation and correlation configuration
-----------------------------------------
StackLight comes with a predefined set of aggregation rules and
@ -481,7 +476,7 @@ This file has four sections:
.. _gse_policies:
Health status policies
~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++
The correlation logic implemented by the GSE plugins is policy-based.
The policies define how the GSE plugins infer the health status of a
@ -602,7 +597,7 @@ The policy definition reads as:
.. _gse_cluster_service:
Service cluster aggregation rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++
The service cluster aggregation rules are used to designate
the members of a service cluster along with
@ -676,7 +671,7 @@ Where
.. _service_cluster:
Service cluster definition
~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++
The service clusters are defined as shown in the example below::
@ -731,7 +726,7 @@ status across all members.
.. _gse_cluster_node:
Node cluster aggregation rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++++
The node cluster aggregation rules are used to designate
the members of a node cluster along with
@ -807,7 +802,7 @@ Where
.. _node_cluster:
Node cluster definition
~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++
The node clusters are defined as shown in the example below::
@ -862,7 +857,7 @@ status across all members.
.. _gse_cluster_global:
Top-level cluster aggregation rules
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++++
The top-level agggregation rules aggregate GSE metrics from the
Service Cluster GSE Plugin and the Node Cluster GSE Plugin.
@ -957,7 +952,7 @@ Where
.. _global_cluster:
Top-level cluster definition
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
++++++++++++++++++++++++++++
The top-level clusters are defined as shown in the example below::
@ -1014,7 +1009,7 @@ Where
.. _puppet_apply:
Apply your Configuration Changes
Apply your configuration changes
--------------------------------
Once you have edited and saved your changes in

56
doc/user/source/configuration.rst → doc/user/source/configure_plugin.rst
View File

@ -1,8 +1,3 @@
.. _config_guide:
Configuration Guide
===================
.. _plugin_configuration:
Plugin configuration
@ -19,32 +14,31 @@ To configure your plugin, you need to follow these steps:
3. Scroll down through the settings until you find the StackLight Collector
Plugin section. You should see a page like this.
.. image:: ../../images/collector_settings.png
:width: 350pt
:alt: The StackLight Collector Plugin settings
:align: center
.. image:: ../../images/collector_settings.png
:width: 350pt
:alt: The StackLight Collector Plugin settings
4. Tick the StackLight Collector Plugin box and
fill-in the required fields as indicated below.
a. Provide an *Environment Label* of your choice to tag your data (optional).
b. For the *Events Analytics* destination, select *Local node* if you plan to use the
Elasticsearch-Kibana Plugin in the environment. Otherwise, select *Remote server*
and specify the fully qualified name or IP address of an external Elasticsearch server.
c. For the *Metrics Analytics* destination, select *Local node* if you plan to use the
InfluxDB-Grafana Plugin in the environment. Otherwise, select *Remote server* and specify
the fully qualified name or IP address of an external InfluxDB server. Then, specify the
InfluxDB database name you want to use, a username and password that have read and write
access permissions.
d. For *Alerting*, select *Alerts sent by email* if you want to receive alerts sent by email
from the Collector. Otherwise, select *Alerts sent to a local cluster* if you plan to
use the Infrastructure Alerting Plugin (Nagios) in the environment.
Alternatively, you can select *Alerts sent to a remote Nagios server*.
e. For *Alerts sent by email*, you can specify the SMTP authentication method you want to use. Then,
specify the SMTP server fully qualified name or IP address, the SMTP username and password who
have the permissions to send emails.
f. Finally, specify the Nagios server URL, username and password if you have chosen to send
alerts to an external Nagios server.
a. Provide an *Environment Label* of your choice to tag your data (optional).
b. For the *Events Analytics* destination, select *Local node* if you plan to use the
Elasticsearch-Kibana Plugin in the environment. Otherwise, select *Remote server*
and specify the fully qualified name or IP address of an external Elasticsearch server.
c. For the *Metrics Analytics* destination, select *Local node* if you plan to use the
InfluxDB-Grafana Plugin in the environment. Otherwise, select *Remote server* and specify
the fully qualified name or IP address of an external InfluxDB server. Then, specify the
InfluxDB database name you want to use, a username and password that have read and write
access permissions.
d. For *Alerting*, select *Alerts sent by email* if you want to receive alerts sent by email
from the Collector. Otherwise, select *Alerts sent to a local cluster* if you plan to
use the Infrastructure Alerting Plugin (Nagios) in the environment.
Alternatively, you can select *Alerts sent to a remote Nagios server*.
e. For *Alerts sent by email*, you can specify the SMTP authentication method you want to use. Then,
specify the SMTP server fully qualified name or IP address, the SMTP username and password who
have the permissions to send emails.
f. Finally, specify the Nagios server URL, username and password if you have chosen to send
alerts to an external Nagios server.
5. Configure your environment following the `instructions
<http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/configure-environment.html>`__
@ -130,13 +124,13 @@ use the instructions below to troubleshoot the problem:
.. _diagnostic:
Diagnostic Tool
Diagnostic tool
---------------
A **global diagnostic tool** is installed on the Fuel Master node
by the StackLight Collector Plugin. The global diagnostic tool checks
that StackLight is configured and running properly across the entire
LMA toolchain for all the nodes that ready in your OpenStack environment::
LMA toolchain for all the nodes that are ready in your OpenStack environment::
[root@nailgun ~]# /var/www/nailgun/plugins/lma_collector-<version>/contrib/tools/diagnostic.sh
Running lma_diagnostic tool on all available nodes (this can take several minutes)
@ -173,8 +167,8 @@ diagnostic tool would report an error as shown below::
root@node-3:~# lma_diagnostics
2016-06-10-11-11-48 INFO node-3.test.domain.local role ["controller"]
2016-06-10-11-11-48 INFO ** LMA Collector
2016-06-10-11-11-48 **ERROR 1 'hekad -config' processes found, 2 expected!**
2016-06-10-11-11-48 **ERROR 'hekad' process does not LISTEN on port: 4352**
2016-06-10-11-11-48 ERROR 1 'hekad -config' processes found, 2 expected!
2016-06-10-11-11-48 ERROR 'hekad' process does not LISTEN on port: 4352
[...]
Here, two errors are reported:

59
doc/user/source/index.rst
View File

@ -1,21 +1,50 @@
==================================================
Welcome to the StackLight Collector Documentation!
==================================================
======================================================
The StackLight Collector plugin for Fuel documentation
======================================================
Overview
~~~~~~~~
.. toctree::
:maxdepth: 2
:maxdepth: 1
overview
releases
installation
configuration
alarms
intro
requirements
prerequisites
limitations
release_notes
licenses
appendix_a
appendix_b
appendix_c
references
Indices and Tables
==================
Installing StackLight Collector plugin for Fuel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* :ref:`search`
.. toctree::
:maxdepth: 1
install
Configuring StackLight Collector plugin for Fuel
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
configure_plugin
Configuring alarms
~~~~~~~~~~~~~~~~~~
.. toctree::
:maxdepth: 1
configure_alarms
Appendix
~~~~~~~~
.. toctree::
:maxdepth: 1
appendix_metrics
appendix_alarms

32
doc/user/source/installation.rst → doc/user/source/install.rst
View File

@ -1,31 +1,7 @@
.. _user_installation:
Installation
============
Prior to installing the StackLight Collector Plugin,
you may want to install the backend services the *collector* uses
to store the data. These backend services include:
* Elasticsearch
* InfluxDB
* Nagios
There are two installation options:
1. Install the backend services automatically within a Fuel environment using the Fuel Plugins listed below.
* `StackLight Elasticsearch-Kibana Fuel Plugin Installation Guide <http://fuel-plugin-elasticsearch-kibana.readthedocs.io/en/latest/installation.html#installation-guide>`_.
* `StackLight InfluxDB-Grafana Fuel Plugin Installation Guide <http://fuel-plugin-influxdb-grafana.readthedocs.io/en/latest/installation.html#installation-guide>`_.
* `StackLight Infrastructure Alerting Fuel Plugin Installation Guide <http://fuel-plugin-lma-infrastructure-alerting.readthedocs.io/en/latest/installation.html#installation-guide>`_.
2. Install the backend services on your own outside of a Fuel environment.
Note that in this case, the installation must comply with the StackLight Collector
Plugin's :ref:`requirements <plugin_requirements>`.
StackLight Collector Fuel Plugin installation using the RPM file of the Fuel Plugins Catalog
--------------------------------------------------------------------------------------------
Install using the RPM file of the Fuel Plugins Catalog
------------------------------------------------------
To install the StackLight Collector Fuel Plugin using the RPM file of the Fuel Plugins
Catalog, follow these steps:
@ -52,8 +28,8 @@ Catalog, follow these steps:
1 | lma_collector | 0.10.0 | 4.0.0
StackLight Collector Fuel Plugin installation from source
---------------------------------------------------------
Install from source
-------------------
Alternatively, you may want to build the RPM file of the plugin from source
if, for example, you want to test the latest features of the master branch

36
doc/user/source/overview.rst → doc/user/source/intro.rst
View File

@ -1,7 +1,7 @@
.. _user_overview:
.. _user_intro:
Overview
========
Introduction
------------
The **StackLight Collector Plugin** is used to install and configure
several software components that are used to collect and process all the
@ -19,6 +19,7 @@ The Collecor is a key component of the so-called
.. image:: ../../images/toolchain_map.png
:align: center
:width: 90%
The Collector is installed on every node of your OpenStack
environment. Each Collector is individually responsible for supporting
@ -80,31 +81,4 @@ to the backend servers:
anomalies and faults that have been detected by the Collector.
They basicaly contain the same information as the *passive checks*
sent to Nagios. In addition, they may contain 'hints' about what
the Collector think could be the root cause of a problem.
.. _plugin_requirements:
Requirements
------------
+-------------------------------------------------------+-------------------------------------------------------------------+
| Requirement | Version/Comment |
+=======================================================+===================================================================+
| Mirantis OpenStack | 8.0 or 9.0 |
+-------------------------------------------------------+-------------------------------------------------------------------+
| A running Elasticsearch server (for log analytics) | 1.7.4 or higher, the RESTful API must be enabled over port 9200 |
+-------------------------------------------------------+-------------------------------------------------------------------+
| A running InfluxDB server (for metric analytics) | 0.10.0 or higher, the RESTful API must be enabled over port 8086 |
+-------------------------------------------------------+-------------------------------------------------------------------+
| A running Nagios server (for infrastructure alerting) | 3.5 or higher, the command CGI must be enabled |
+-------------------------------------------------------+-------------------------------------------------------------------+
Limitations
-----------
* The plugin is not compatible with an OpenStack environment deployed with nova-network.
* When you re-execute tasks on deployed nodes using the Fuel CLI, the *hekad* and
*collectd* processes will be restarted on these nodes during the post-deployment
phase. See `bug #1570850
<https://bugs.launchpad.net/lma-toolchain/+bug/1570850>`_ for details.
the Collector think could be the root cause of a problem.

8
doc/user/source/licenses.rst
View File

@ -1,10 +1,10 @@
.. _licenses:
Licenses
========
--------
Third Party Components
----------------------
Third-party components
++++++++++++++++++++++
+----------------------------+------------------------------------------+------------------------+
| Name | Project Web Site | License |
@ -51,7 +51,7 @@ Third Party Components
+----------------------------+------------------------------------------+------------------------+
Puppet modules
--------------
++++++++++++++
+-----------------------+-----------------------------------------------------+-----------+
| Name | Project Web Site | License |

11
doc/user/source/limitations.rst Normal file
View File

@ -0,0 +1,11 @@
.. _plugin_limitations:
Limitations
-----------
* The plugin is not compatible with an OpenStack environment deployed with nova-network.
* When you re-execute tasks on deployed nodes using the Fuel CLI, the *collectd*
processes will be restarted on these nodes during the post-deployment
phase. See `bug #1570850
<https://bugs.launchpad.net/lma-toolchain/+bug/1570850>`_ for details.

3
doc/user/source/metrics/clusters.rst
View File

@ -1,6 +1,7 @@
.. _cluster_metrics:
The cluster metrics are emitted by the GSE plugins (See the :ref:`alarm_guide` for details).
The cluster metrics are emitted by the GSE plugins. For details, see
:ref:`Configuring alarms <configure_alarms>`.
* ``cluster_node_status``, the status of the node cluster.
The metric contains a ``cluster_name`` field that identifies the node cluster.

24
doc/user/source/prerequisites.rst Normal file
View File

@ -0,0 +1,24 @@
.. _plugin_prerequisites:
Prerequisites
-------------
Prior to installing the StackLight Collector Plugin,
you may want to install the backend services the *collector* uses
to store the data. These backend services include:
* Elasticsearch
* InfluxDB
* Nagios
There are two installation options:
1. Install the backend services automatically within a Fuel environment using the Fuel Plugins listed below.
* `StackLight Elasticsearch-Kibana Fuel Plugin Installation Guide <http://fuel-plugin-elasticsearch-kibana.readthedocs.io/en/latest/installation.html#installation-guide>`_.
* `StackLight InfluxDB-Grafana Fuel Plugin Installation Guide <http://fuel-plugin-influxdb-grafana.readthedocs.io/en/latest/installation.html#installation-guide>`_.
* `StackLight Infrastructure Alerting Fuel Plugin Installation Guide <http://fuel-plugin-lma-infrastructure-alerting.readthedocs.io/en/latest/installation.html#installation-guide>`_.
2. Install the backend services on your own outside of a Fuel environment.
Note that in this case, the installation must comply with the StackLight Collector
Plugin's :ref:`requirements <plugin_requirements>`.

8
doc/user/source/appendix_a.rst → doc/user/source/references.rst
View File

@ -1,7 +1,11 @@
.. _references:
Appendix A: References
======================
.. raw:: latex
\pagebreak
References
----------
* The `StackLight Collector plugin <https://github.com/openstack/fuel-plugin-lma-collector>`_ project at GitHub.
* The `StackLight Elasticsearch-Kibana plugin <https://github.com/openstack/fuel-plugin-elasticsearch-kibana>`_ project at GitHub.

14
doc/user/source/releases.rst → doc/user/source/release_notes.rst
View File

@ -1,10 +1,10 @@
.. _releases:
.. _release_notes:
Release Notes
=============
Release notes
-------------
Version 0.10.0
--------------
++++++++++++++
* Changes
@ -49,7 +49,7 @@ Version 0.10.0
* Bug fixes
Version 0.9.0
-------------
+++++++++++++
* Changes
@ -94,7 +94,7 @@ Version 0.9.0
<https://bugs.launchpad.net/lma-toolchain/+bug/1561603>`_).
Version 0.8.0
-------------
+++++++++++++
* Support for alerting in two different modes:
@ -114,6 +114,6 @@ Version 0.8.0
Version 0.7.0
-------------
+++++++++++++
* Initial release of the plugin. This is a beta version.

16
doc/user/source/requirements.rst Normal file
View File

@ -0,0 +1,16 @@
.. _plugin_requirements:
Requirements
------------
+-------------------------------------------------------+-------------------------------------------------------------------+
| Requirement | Version/Comment |
+=======================================================+===================================================================+
| Mirantis OpenStack | 8.0 or 9.0 |
+-------------------------------------------------------+-------------------------------------------------------------------+
| A running Elasticsearch server (for log analytics) | 1.7.4 or higher, the RESTful API must be enabled over port 9200 |
+-------------------------------------------------------+-------------------------------------------------------------------+
| A running InfluxDB server (for metric analytics) | 0.10.0 or higher, the RESTful API must be enabled over port 8086 |
+-------------------------------------------------------+-------------------------------------------------------------------+
| A running Nagios server (for infrastructure alerting) | 3.5 or higher, the command CGI must be enabled |
+-------------------------------------------------------+-------------------------------------------------------------------+