Merge "[docs] Edits the plugin guide structure"

This commit is contained in:
Jenkins 2016-07-13 17:31:39 +00:00 committed by Gerrit Code Review
commit 4dd6096ce2
15 changed files with 186 additions and 162 deletions

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:: Here is a list of all the alarms that are built-in in StackLight::

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. Here is a list of metrics that are emitted by the StackLight Collector.
They are listed by category then by metric name. They are listed by category then by metric name.
System System
------ ++++++
.. include:: metrics/system.rst .. include:: metrics/system.rst
Apache Apache
------ ++++++
.. include:: metrics/apache.rst .. include:: metrics/apache.rst
MySQL MySQL
----- +++++
.. include:: metrics/mysql.rst .. include:: metrics/mysql.rst
RabbitMQ RabbitMQ
-------- ++++++++
.. include:: metrics/rabbitmq.rst .. include:: metrics/rabbitmq.rst
HAProxy HAProxy
------- +++++++
.. include:: metrics/haproxy.rst .. include:: metrics/haproxy.rst
Memcached Memcached
--------- +++++++++
.. include:: metrics/memcached.rst .. include:: metrics/memcached.rst
Libvirt Libvirt
------- +++++++
.. include:: metrics/libvirt.rst .. include:: metrics/libvirt.rst
OpenStack OpenStack
--------- +++++++++
.. include:: metrics/openstack.rst .. include:: metrics/openstack.rst
Ceph Ceph
---- ++++
.. include:: metrics/ceph.rst .. include:: metrics/ceph.rst
Pacemaker Pacemaker
--------- +++++++++
.. include:: metrics/pacemaker.rst .. include:: metrics/pacemaker.rst
Clusters Clusters
-------- ++++++++
.. include:: metrics/clusters.rst .. include:: metrics/clusters.rst
Self Monitoring Self Monitoring
--------------- +++++++++++++++
.. include:: metrics/lma.rst .. include:: metrics/lma.rst
Elasticsearch Elasticsearch
------------- +++++++++++++
.. include:: metrics/elasticsearch.rst .. include:: metrics/elasticsearch.rst
InfluxDB InfluxDB
-------- ++++++++
.. include:: metrics/influxdb.rst .. include:: metrics/influxdb.rst

View File

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

View File

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

View File

@ -1,8 +1,3 @@
.. _config_guide:
Configuration Guide
===================
.. _plugin_configuration: .. _plugin_configuration:
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 3. Scroll down through the settings until you find the StackLight Collector
Plugin section. You should see a page like this. Plugin section. You should see a page like this.
.. image:: ../../images/collector_settings.png .. image:: ../../images/collector_settings.png
:width: 350pt :width: 350pt
:alt: The StackLight Collector Plugin settings :alt: The StackLight Collector Plugin settings
:align: center
4. Tick the StackLight Collector Plugin box and 4. Tick the StackLight Collector Plugin box and
fill-in the required fields as indicated below. fill-in the required fields as indicated below.
a. Provide an *Environment Label* of your choice to tag your data (optional). 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 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* Elasticsearch-Kibana Plugin in the environment. Otherwise, select *Remote server*
and specify the fully qualified name or IP address of an external Elasticsearch 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 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 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 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 InfluxDB database name you want to use, a username and password that have read and write
access permissions. access permissions.
d. For *Alerting*, select *Alerts sent by email* if you want to receive alerts sent by email 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 from the Collector. Otherwise, select *Alerts sent to a local cluster* if you plan to
use the Infrastructure Alerting Plugin (Nagios) in the environment. use the Infrastructure Alerting Plugin (Nagios) in the environment.
Alternatively, you can select *Alerts sent to a remote Nagios server*. 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, 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 specify the SMTP server fully qualified name or IP address, the SMTP username and password who
have the permissions to send emails. have the permissions to send emails.
f. Finally, specify the Nagios server URL, username and password if you have chosen to send f. Finally, specify the Nagios server URL, username and password if you have chosen to send
alerts to an external Nagios server. alerts to an external Nagios server.
5. Configure your environment following the `instructions 5. Configure your environment following the `instructions
<http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/configure-environment.html>`__ <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:
Diagnostic Tool Diagnostic tool
--------------- ---------------
A **global diagnostic tool** is installed on the Fuel Master node A **global diagnostic tool** is installed on the Fuel Master node
by the StackLight Collector Plugin. The global diagnostic tool checks by the StackLight Collector Plugin. The global diagnostic tool checks
that StackLight is configured and running properly across the entire 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 [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) 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 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 node-3.test.domain.local role ["controller"]
2016-06-10-11-11-48 INFO ** LMA Collector 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 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 'hekad' process does not LISTEN on port: 4352
[...] [...]
Here, two errors are reported: Here, two errors are reported:

View File

@ -1,21 +1,50 @@
================================================== ======================================================
Welcome to the StackLight Collector Documentation! The StackLight Collector plugin for Fuel documentation
================================================== ======================================================
Overview
~~~~~~~~
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 1
overview intro
releases requirements
installation prerequisites
configuration limitations
alarms release_notes
licenses licenses
appendix_a references
appendix_b
appendix_c
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

View File

@ -1,31 +1,7 @@
.. _user_installation: .. _user_installation:
Installation Install using the RPM file of the Fuel Plugins Catalog
============ ------------------------------------------------------
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
--------------------------------------------------------------------------------------------
To install the StackLight Collector Fuel Plugin using the RPM file of the Fuel Plugins To install the StackLight Collector Fuel Plugin using the RPM file of the Fuel Plugins
Catalog, follow these steps: Catalog, follow these steps:
@ -52,8 +28,8 @@ Catalog, follow these steps:
1 | lma_collector | 0.10.0 | 4.0.0 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 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 if, for example, you want to test the latest features of the master branch

View File

@ -1,7 +1,7 @@
.. _user_overview: .. _user_intro:
Overview Introduction
======== ------------
The **StackLight Collector Plugin** is used to install and configure The **StackLight Collector Plugin** is used to install and configure
several software components that are used to collect and process all the 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 .. image:: ../../images/toolchain_map.png
:align: center :align: center
:width: 90%
The Collector is installed on every node of your OpenStack The Collector is installed on every node of your OpenStack
environment. Each Collector is individually responsible for supporting 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. anomalies and faults that have been detected by the Collector.
They basicaly contain the same information as the *passive checks* They basicaly contain the same information as the *passive checks*
sent to Nagios. In addition, they may contain 'hints' about what sent to Nagios. In addition, they may contain 'hints' about what
the Collector think could be the root cause of a problem. 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.

View File

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

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.

View File

@ -1,6 +1,7 @@
.. _cluster_metrics: .. _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. * ``cluster_node_status``, the status of the node cluster.
The metric contains a ``cluster_name`` field that identifies the node cluster. The metric contains a ``cluster_name`` field that identifies the node cluster.

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>`.

View File

@ -1,7 +1,11 @@
.. _references: .. _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 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. * The `StackLight Elasticsearch-Kibana plugin <https://github.com/openstack/fuel-plugin-elasticsearch-kibana>`_ project at GitHub.

View File

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

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 |
+-------------------------------------------------------+-------------------------------------------------------------------+