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

[docs] Edits the StackLight Collector plugin guide 

Edits the following sections of the StackLight Collector
plugin 0.10.0 documentation:

* Installing
* Configuring

Change-Id: I9478bc3adbccf711b082cf63451fa8f336dec06f
This commit is contained in:
Maria Zlatkova 2016-07-15 18:04:07 +03:00 committed by Simon Pasquier
parent 988b67ed30
commit 5c0d43aaec
2 changed files with 197 additions and 154 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

236
doc/user/source/configure_plugin.rst
View File

@ -3,96 +3,107 @@
Plugin configuration
--------------------
To configure your plugin, you need to follow these steps:
**To configure the StackLight Collector plugin:**
1. Create a new environment following the `instructions
<http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/create-environment/start-create-env.html>`__
of the Fuel User Guide.
#. Create a new environment as described in `Create a new OpenStack environment
<http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/create-environment/start-create-env.html>`__.
2. Click on the *Settings* tab of the Fuel web UI and select the *Other* category.
#. In the Fuel web UI, click the :guilabel:`Settings` tab and select the
:guilabel:`Other` category.
3. Scroll down through the settings until you find the StackLight Collector
Plugin section. You should see a page like this.
#. 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
4. Tick the StackLight Collector Plugin box and
fill-in the required fields as indicated below.
#. Select :guilabel:`The Logging, Monitoring and Alerting (LMA) Collector
Plugin` 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. Optional. Provide an :guilabel:`Environment Label` of your choice to tag
your data.
#. In the :guilabel:`Events Analytics` section, select
:guilabel:`Local node` if you plan to use the Elasticsearch-Kibana
Plugin in the environment. Otherwise, select :guilabel:`Remote server`
and specify the fully qualified name or the IP address of an external
Elasticsearch server.
#. In the :guilabel:`Metrics Analytics` section, select
:guilabel:`Local node` if you plan to use the InfluxDB-Grafana Plugin in
the environment. Otherwise, select :guilabel:`Remote server` and specify
the fully qualified name or the 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.
#. In the :guilabel:`Alerting` section, select
:guilabel:`Alerts sent by email` if you want to receive alerts sent by
email from the Collector. Otherwise, select
:guilabel:`Alerts sent to a local cluster` if you plan to use the
Infrastructure Alerting Plugin (Nagios) in the environment.
Alternatively, select :guilabel:`Alerts sent to a remote Nagios server`.
#. For :guilabel:`Alerts sent by email`, 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 to have the
permissions to send emails.
#. 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>`__
of the Fuel User Guide.
#. Configure your environment as described in `Configure your Environment
<http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/configure-environment.html>`__.
.. note:: By default, StackLight is configured to use the *management network*,
of the so called *default node network group* created by Fuel.
While this default setup may be appropriate for small deployments or
evaluation purposes, it is recommended not to use the default *management network*
for StackLight but instead create a dedicated network when configuring your environement.
This will improve the performance of both OpenStack and StackLight overall and facilitate
the access to the Kibana and Grafana analytics.
.. note:: By default, StackLight is configured to use the *management
network*, of the so-called *default node network group* created by Fuel.
While this default setup may be appropriate for small deployments or
evaluation purposes, it is recommended that you not use the default
*management network* for StackLight. Instead, create a dedicated network
when configuring your environment. This will improve the overall
performance of both OpenStack and StackLight and facilitate the access
to the Kibana and Grafana analytics.
6. Deploy your environment following the `instructions
<http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/deploy-environment.html>`__
of the Fuel User Guide.
#. Deploy your environment as described in `Deploy an OpenStack environment
<http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/deploy-environment.html>`__.
.. note:: The StackLight Collector Plugin is a *hot-pluggable* plugin which means
that it is possible to install and deploy the *collector* in an
environment that is already deployed. After the installation of the StackLight
Collector Plugin, you will need to define the settings of the plugin and then
run the command shown below from the *Fuel master node* for every node of
your deployment. You need to start with *the controller node(s)*::
.. note:: The StackLight Collector Plugin is a *hot-pluggable* plugin.
Therefore, it is possible to install and deploy the *collector* in an
environment that is already deployed. After the installation of the
StackLight Collector Plugin, you will need to define the settings of the
plugin and then run the command shown below from the *Fuel master node*
for every node of your deployment. You need to start with
*the controller node(s)*:
[root@nailgun ~]# fuel nodes --env <env_id> --node <node_id> --start \
post_deployment_start --tasks hiera
.. code-block:: console
[root@nailgun ~]# fuel nodes --env <env_id> --node <node_id> --start \
post_deployment_start --tasks hiera
.. _plugin_verification:
Plugin verification
-------------------
Once the OpenStack environment is ready, you should check that both
the *collectd* and *hekad* processes are running on the OpenStack nodes::
Once the OpenStack environment is ready, verify that both the *collectd* and
*hekad* processes are running on the OpenStack nodes:
[root@node-1 ~]# pidof hekad
5568
5569
[root@node-1 ~]# pidof collectd
5684
.. code-block:: console
.. note:: Starting with StackLight version 0.10, there is not one but two *hekad* processes
running. One is used to collect and process the logs and the notifications, the
other one is used to process the metrics.
[root@node-1 ~]# pidof hekad
5568
5569
[root@node-1 ~]# pidof collectd
5684
.. note:: Starting with StackLight version 0.10, there are two *hekad*
processes running instead of one. One is used to collect and process the
logs and the notifications, the other one is used to process the metrics.
.. _troubleshooting:
Troubleshooting
---------------
If you see no data in the Kibana and/or Grafana dashboards,
use the instructions below to troubleshoot the problem:
If you see no data in the Kibana and/or Grafana dashboards, follow the
instructions below to troubleshoot the issue:
1. Check that the *collector* services are up and running::
#. Verify that the *collector* services are up and running::
# On the controller node(s)
[root@node-1 ~]# crm resource status metric_collector
@ -102,7 +113,7 @@ use the instructions below to troubleshoot the problem:
[root@node-2 ~]# status log_collector
[root@node-2 ~]# status metric_collector
2. If a *collector* is down, restart it::
#. If a *collector* is down, restart it::
# On the controller node(s)
[root@node-1 ~]# crm resource start log_collector
@ -112,73 +123,80 @@ use the instructions below to troubleshoot the problem:
[root@node-2 ~]# start log_collector
[root@node-2 ~]# start metric_collector
3. Look for errors in the log file of the *collectors*
(located at /var/log/log_collector.log and /var/log/metric_collector.log).
#. Look for errors in the log file of the *collectors* located at
``/var/log/log_collector.log`` and ``/var/log/metric_collector.log``.
4. Look for errors in the log file of *collectd* (located at /var/log/collectd.log).
#. Look for errors in the log file of *collectd* located at
``/var/log/collectd.log``.
5. Check if the nodes are able to connect to the Elasticsearch server on port 9200.
6. Check if the nodes are able to connect to the InfluxDB server on port 8086.
#. Verify that the nodes are able to connect to the Elasticsearch server on port
9200.
#. Verify that the nodes are able to connect to the InfluxDB server on port 8086.
.. _diagnostic:
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 are ready in your OpenStack environment::
The StackLight Collector Plugin installs a **global diagnostic tool** on the
Fuel Master node. The global diagnostic tool checks that StackLight is
configured and running properly across the entire 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)
The diagnostic archive is here: /var/lma_diagnostics.2016-06-10_11-23-1465557820.tgz
.. code-block:: console
Note that a global diagnostic can take several minutes.
[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)
The diagnostic archive is here: /var/lma_diagnostics.2016-06-10_11-23-1465557820.tgz
All the results are consolidated in an archive file with the
name ``/var/lma_diagnostics.[date +%Y-%m-%d_%H-%M-%s].tgz``.
.. note:: A global diagnostic can take several minutes.
All the results are consolidated in the
``/var/lma_diagnostics.[date +%Y-%m-%d_%H-%M-%s].tgz`` archive.
Instead of running a global diagnostic, you may want to run the diagnostic
on individual nodes. The tool will figure out what checks should be executed
based on the role of the node as shown below::
on individual nodes. Based on the role of the node, the tool determines what
checks should be executed. For example:
root@node-3:~# hiera roles
["controller"]
.. code-block:: console
root@node-3:~# lma_diagnostics
root@node-3:~# hiera roles
["controller"]
2016-06-10-11-08-04 INFO node-3.test.domain.local role ["controller"]
2016-06-10-11-08-04 INFO ** LMA Collector
2016-06-10-11-08-04 INFO 2 process(es) 'hekad -config' found
2016-06-10-11-08-04 INFO 1 process(es) hekad is/are listening on port 4352
2016-06-10-11-08-04 INFO 1 process(es) hekad is/are listening on port 8325
2016-06-10-11-08-05 INFO 1 process(es) hekad is/are listening on port 5567
2016-06-10-11-08-05 INFO 1 process(es) hekad is/are listening on port 4353
[...]
root@node-3:~# lma_diagnostics
In the example above, the diagnostic tool reports that two *hekad*
processes are runing on *node-3* which is the expected outcome.
In the case where one *hekad* process is not be running, the
diagnostic tool would report an error as shown below::
2016-06-10-11-08-04 INFO node-3.test.domain.local role ["controller"]
2016-06-10-11-08-04 INFO ** LMA Collector
2016-06-10-11-08-04 INFO 2 process(es) 'hekad -config' found
2016-06-10-11-08-04 INFO 1 process(es) hekad is/are listening on port 4352
2016-06-10-11-08-04 INFO 1 process(es) hekad is/are listening on port 8325
2016-06-10-11-08-05 INFO 1 process(es) hekad is/are listening on port 5567
2016-06-10-11-08-05 INFO 1 process(es) hekad is/are listening on port 4353
[...]
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
[...]
In the example above, the diagnostic tool reports that two *hekad* processes
are running on *node-3*, which is the expected outcome. In the case when one
*hekad* process is not running, the diagnostic tool reports an error. For
example:
Here, two errors are reported:
.. code-block:: console
1. There is only one *hekad* process running instead of two.
2. No *hekad* process is listening on port 4352.
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
[...]
This is one example of the type of checks performed by the
diagnostic tool but there are many others.
On the OpenStack nodes, the diagnostic's results are stored
in ``/var/lma_diagnostics/diagnostics.log``.
In the example above, the diagnostic tool reported two errors:
**A successful LMA toolchain diagnostic should be free of errors**.
#. There is only one *hekad* process running instead of two.
#. No *hekad* process is listening on port 4352.
These examples describe only one type of checks performed by the diagnostic
tool, but there are many others.
On the OpenStack nodes, the diagnostic results are stored in ``/var/lma_diagnostics/diagnostics.log``.
.. note:: A successful LMA toolchain diagnostic should be free of errors.

115
doc/user/source/install.rst
View File

@ -1,80 +1,105 @@
.. _user_installation:
Install 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:
**To install the StackLight Collector Fuel plugin using the RPM file of the Fuel
plugins catalog:**
1. Select, using the *MONITORING* category and Mirantis OpenStack version you are using, the RPM file
you want to download from the
`Fuel Plugins Catalog <https://www.mirantis.com/validated-solution-integrations/fuel-plugins/>`_
#. Go to the `Fuel plugins catalog <https://www.mirantis.com/validated-solution-integrations/fuel-plugins/>`_.
#. From the :guilabel:`Filter` drop-down menu, select the Mirantis OpenStack
version you are using and the :guilabel:`Monitoring` category.
#. Download the RPM file.
2. Copy the RPM file to the Fuel Master node::
#. Copy the RPM file to the Fuel Master node:
[root@home ~]# scp lma_collector-0.10-0.10.0-1.noarch.rpm \
root@<Fuel Master node IP address>:
.. code-block:: console
3. Install the plugin using the
`Fuel Plugins CLI <http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/cli/cli_plugins.html>`_::
[root@home ~]# scp lma_collector-0.10-0.10.0-1.noarch.rpm \
root@<Fuel Master node IP address>:
[root@fuel ~]# fuel plugins --install lma_collector-0.10-0.10.0-1.noarch.rpm
#. Install the plugin using the
`Fuel Plugins CLI <http://docs.openstack.org/developer/fuel-docs/userdocs/fuel-user-guide/cli/cli_plugins.html>`_:
4. Verify that the plugin is installed correctly::
.. code-block:: console
[root@fuel ~]# fuel plugins --list
id | name | version | package_version
---|----------------------|----------|----------------
1 | lma_collector | 0.10.0 | 4.0.0
[root@fuel ~]# fuel plugins --install lma_collector-0.10-0.10.0-1.noarch.rpm
#. Verify that the plugin is installed correctly:
.. code-block:: console
[root@fuel ~]# fuel plugins --list
id | name | version | package_version
---|----------------------|----------|----------------
1 | lma_collector | 0.10.0 | 4.0.0
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
or customize the plugin.
Alternatively, you may want to build the plugin RPM file from source if, for
example, you want to test the latest features of the master branch or
customize the plugin.
.. note:: Be aware that running a Fuel plugin that you built yourself
is at your own risk and will not be supported.
.. note:: Running a Fuel plugin that you built yourself is at your own risk
and will not be supported.
To install the StackLight Collector Plugin from source, you first need to prepare an
environement to build the RPM file.
To install the StackLight Collector Plugin from source, you first need to
prepare an environement to build the RPM file.
The recommended approach is to build the RPM file directly onto the Fuel Master
node so that you won't have to copy that file later on.
node so that you will not have to copy that file later on.
**Prepare an environment to build the plugin on the Fuel Master Node**
**To prepare an environment:**
1. Install the standard Linux development tools::
#. Install the standard Linux development tools:
[root@home ~] yum install createrepo rpm rpm-build dpkg-devel
.. code-block:: console
2. Install the Fuel Plugin Builder. To do that, you should first get pip::
[root@home ~] yum install createrepo rpm rpm-build dpkg-devel
[root@home ~] easy_install pip
#. Install the Fuel Plugin Builder. To do that, you should first get pip:
3. Then install the Fuel Plugin Builder (the `fpb` command line) with `pip`::
.. code-block:: console
[root@home ~] pip install fuel-plugin-builder
[root@home ~] easy_install pip
.. note:: You may also need to build the Fuel Plugin Builder if the package version of the
plugin is higher than the package version supported by the Fuel Plugin Builder you get from `pypi`.
In this case, please refer to the section "Preparing an environment for plugin development"
of the `Fuel Plugins wiki <https://wiki.openstack.org/wiki/Fuel/Plugins>`_
if you need further instructions about how to build the Fuel Plugin Builder.
#. Then install the Fuel Plugin Builder (the `fpb` command line) with `pip`:
4. Clone the plugin git repository::
.. code-block:: console
[root@home ~] git clone https://github.com/openstack/fuel-plugin-lma-collector.git
[root@home ~] pip install fuel-plugin-builder
5. Check that the plugin is valid::
.. note:: You may also need to build the Fuel Plugin Builder if the package
version of the plugin is higher than the package version supported by the
Fuel Plugin Builder you get from ``pypi``. For instructions on how to
build the Fuel Plugin Builder, see the *Preparing an environment for
plugin development* section of the
`Fuel plugins Wiki <https://wiki.openstack.org/wiki/Fuel/Plugins>`_.
[root@home ~] fpb --check ./fuel-plugin-lma-collector
#. Clone the plugin repository:
6. And finally, build the plugin::
.. code-block:: console
[root@home ~] fpb --build ./fuel-plugin-lma-collector
[root@home ~] git clone https://github.com/openstack/fuel-plugin-lma-collector.git
7. Now that you have created the RPM file, you can install the plugin using the `fuel plugins --install` command::
#. Verify that the plugin is valid:
[root@fuel ~] fuel plugins --install ./fuel-plugin-lma-collector/*.noarch.rpm
.. code-block:: console
[root@home ~] fpb --check ./fuel-plugin-lma-collector
#. Build the plugin:
.. code-block:: console
[root@home ~] fpb --build ./fuel-plugin-lma-collector
**To install the plugin:**
Now that you have created the RPM file, install the plugin using the
:command:`fuel plugins --install` command:
.. code-block:: console
[root@fuel ~] fuel plugins --install ./fuel-plugin-lma-collector/*.noarch.rpm