diff --git a/doc/user/source/appendix_c.rst b/doc/user/source/appendix_alarms.rst similarity index 99% rename from doc/user/source/appendix_c.rst rename to doc/user/source/appendix_alarms.rst index 5ac49bf95..17ddcb66d 100644 --- a/doc/user/source/appendix_c.rst +++ b/doc/user/source/appendix_alarms.rst @@ -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:: diff --git a/doc/user/source/appendix_b.rst b/doc/user/source/appendix_metrics.rst similarity index 80% rename from doc/user/source/appendix_b.rst rename to doc/user/source/appendix_metrics.rst index 4f82ceddc..aa3f03abf 100644 --- a/doc/user/source/appendix_b.rst +++ b/doc/user/source/appendix_metrics.rst @@ -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 diff --git a/doc/user/source/conf.py b/doc/user/source/conf.py index 33a947792..a833fd08b 100644 --- a/doc/user/source/conf.py +++ b/doc/user/source/conf.py @@ -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 diff --git a/doc/user/source/alarms.rst b/doc/user/source/configure_alarms.rst similarity index 98% rename from doc/user/source/alarms.rst rename to doc/user/source/configure_alarms.rst index dee20c3f1..9472dcac1 100644 --- a/doc/user/source/alarms.rst +++ b/doc/user/source/configure_alarms.rst @@ -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 diff --git a/doc/user/source/configuration.rst b/doc/user/source/configure_plugin.rst similarity index 76% rename from doc/user/source/configuration.rst rename to doc/user/source/configure_plugin.rst index a6b450cb6..a6836d69d 100644 --- a/doc/user/source/configuration.rst +++ b/doc/user/source/configure_plugin.rst @@ -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 `__ @@ -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-/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: diff --git a/doc/user/source/index.rst b/doc/user/source/index.rst index dc6d9401f..e16742788 100644 --- a/doc/user/source/index.rst +++ b/doc/user/source/index.rst @@ -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 \ No newline at end of file diff --git a/doc/user/source/installation.rst b/doc/user/source/install.rst similarity index 67% rename from doc/user/source/installation.rst rename to doc/user/source/install.rst index 569521540..94336b8b7 100644 --- a/doc/user/source/installation.rst +++ b/doc/user/source/install.rst @@ -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 `_. - * `StackLight InfluxDB-Grafana Fuel Plugin Installation Guide `_. - * `StackLight Infrastructure Alerting Fuel Plugin 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 `. - - -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 diff --git a/doc/user/source/overview.rst b/doc/user/source/intro.rst similarity index 67% rename from doc/user/source/overview.rst rename to doc/user/source/intro.rst index ed3f4bb1e..8f7fd6d06 100644 --- a/doc/user/source/overview.rst +++ b/doc/user/source/intro.rst @@ -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 - `_ for details. + the Collector think could be the root cause of a problem. \ No newline at end of file diff --git a/doc/user/source/licenses.rst b/doc/user/source/licenses.rst index fdb22047d..2b944005c 100644 --- a/doc/user/source/licenses.rst +++ b/doc/user/source/licenses.rst @@ -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 | diff --git a/doc/user/source/limitations.rst b/doc/user/source/limitations.rst new file mode 100644 index 000000000..f620fee21 --- /dev/null +++ b/doc/user/source/limitations.rst @@ -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 + `_ for details. \ No newline at end of file diff --git a/doc/user/source/metrics/clusters.rst b/doc/user/source/metrics/clusters.rst index 8547fa3e8..de49abf18 100644 --- a/doc/user/source/metrics/clusters.rst +++ b/doc/user/source/metrics/clusters.rst @@ -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 `. * ``cluster_node_status``, the status of the node cluster. The metric contains a ``cluster_name`` field that identifies the node cluster. diff --git a/doc/user/source/prerequisites.rst b/doc/user/source/prerequisites.rst new file mode 100644 index 000000000..615e318fe --- /dev/null +++ b/doc/user/source/prerequisites.rst @@ -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 `_. + * `StackLight InfluxDB-Grafana Fuel Plugin Installation Guide `_. + * `StackLight Infrastructure Alerting Fuel Plugin 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 `. \ No newline at end of file diff --git a/doc/user/source/appendix_a.rst b/doc/user/source/references.rst similarity index 94% rename from doc/user/source/appendix_a.rst rename to doc/user/source/references.rst index 013a8f0f5..bc3950ada 100644 --- a/doc/user/source/appendix_a.rst +++ b/doc/user/source/references.rst @@ -1,7 +1,11 @@ .. _references: -Appendix A: References -====================== +.. raw:: latex + + \pagebreak + +References +---------- * The `StackLight Collector plugin `_ project at GitHub. * The `StackLight Elasticsearch-Kibana plugin `_ project at GitHub. diff --git a/doc/user/source/releases.rst b/doc/user/source/release_notes.rst similarity index 97% rename from doc/user/source/releases.rst rename to doc/user/source/release_notes.rst index bf7ae2b3c..5b1481fb1 100644 --- a/doc/user/source/releases.rst +++ b/doc/user/source/release_notes.rst @@ -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 `_). 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. diff --git a/doc/user/source/requirements.rst b/doc/user/source/requirements.rst new file mode 100644 index 000000000..f9acc35e9 --- /dev/null +++ b/doc/user/source/requirements.rst @@ -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 | ++-------------------------------------------------------+-------------------------------------------------------------------+ \ No newline at end of file