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

Modified README and User Doc

Browse Source 
Change-Id: Icae2edfc70eedacb085ead763d11494d99fe10d6
This commit is contained in:
Patrick Petit
2015-10-20 16:11:28 +02:00
parent e2e2fb77a7
commit cc488cbea2
4 changed files with 111 additions and 213 deletions
Download Patch File Download Diff File Expand all files Collapse all files

225
README.md
View File

@@ -1,9 +1,6 @@
Logging, Monitoring and Alerting (LMA) Collector Plugin for Fuel
================================================================
Overview
--------
The Logging, Monitoring & Alerting (LMA) *Collector* is a kind of advanced
monitoring agent that should be installed on each of the OpenStack nodes
you want to monitor.
@@ -57,181 +54,6 @@ Please check the [LMA Collector Plugin for Fuel
](http://fuel-plugin-lma-collector.readthedocs.org/en/latest/index.html)
documentation for additional details.
Requirements
------------
| Requirement | Version/Comment |
| -------------------------------------------------------- | --------------------------------------------------------------- |
| Mirantis OpenStack compatility | 6.1 or higher |
| A running Elasticsearch server<br>(for log analytics) | 1.4 or higher, the RESTful API must be enabled over port 9200 |
| A running InfluxDB server<br>(for metric analytics) | 0.9.4 or higher, the RESTful API must be enabled over port 8086 |
| A running Nagios server<br>(for infrastructure alerting) | 3.5 or higher, the command CGI must be enabled |
Limitations
-----------
The plugin is only compatible with OpenStack environments deployed with Neutron
for networking.
Installation Guide
==================
Prior to installing the LMA Collector Plugin, you may want to install its
dependencies:
* Elasticsearch and Kibana for log analytics
* InfluxDB and Grafana for metrics analytics
* Nagios for alerting
To install them automatically using Fuel, you can refer to the
[Elasticsearch-Kibana Fuel Plugin
](https://github.com/openstack/fuel-plugin-elasticsearch-kibana)
, [InfluxDB-Grafana Fuel Plugin
](https://github.com/openstack/fuel-plugin-influxdb-grafana) and [LMA
Infrastructure Alerting Fuel Plugin
](https://github.com/openstack/fuel-plugin-lma-infrastructure-alerting).
You can install Elasticsearch/Kibana, InfluxDB/Grafana and Nagios outside of
Fuel as long as your installation meets the LMA Collector Plugin's requirements
defined above.
LMA collector plugin install from the RPM file
----------------------------------------------
To install the LMA Collector Plugin from the RPM file of the plugin, follow these steps:
1. Download the RPM file from the [Fuel Plugins
Catalog](https://software.mirantis.com/download-mirantis-openstack-fuel-plug-ins/).
2. Copy the RPM file to the Fuel Master node.
```
# scp lma_collector-0.8-0.8.0-0.noarch.rpm root@<Fuel Master node IP address>:
```
3. Install the RPM file using the `fuel` command line:
```
# fuel plugins --install lma_collector-0.8-0.8.0-0.noarch.rpm
```
4. Verify that the plugin is installed correctly:
```
# fuel plugins --list
```
LMA collector plugin install from source
----------------------------------------
To install the LMA Collector Plugin from source, you first need to prepare an
environement to build the RPM file of the plugin.
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.
**Prepare an environment for building the plugin on the Fuel Master Node**
1. Install the standard Linux development tools:
```
# yum install createrepo rpm rpm-build dpkg-devel
```
2. Install the Fuel Plugin Builder. To do that, you should first get pip:
```
# easy_install pip
```
3. Then install the Fuel Plugin Builder (the `fpb` command line) with `pip`:
```
# pip install fuel-plugin-builder
```
*Note: You may also have to build the Fuel Plugin Builder if the package version of the
plugin is higher than 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.*
4. Clone the LMA Collector Plugin git repository:
```
# git clone git@github.com:openstack/fuel-plugin-lma-collector.git
```
5. Check that the plugin is valid:
```
# fpb --check ./fuel-plugin-lma-collector
```
6. And finally, build the plugin:
```
# fpb --build ./fuel-plugin-lma-collector
```
6. Now you have created an RPM file that you can install using the steps described above:
```
# ls -l fuel-plugin-lma-collector/lma_collector-0.8-0.8.0-1.noarch.rpm
-rw-r--r-- 1 root root 27841564 16 sept. 16:18 fuel-plugin-lma-collector/lma_collector-0.8-0.8.0-1.noarch.rpm
```
User Guide
==========
**LMA collector plugin** configuration
--------------------------------------
1. Create a new environment with the Fuel UI wizard.
2. Click on the Settings tab of the Fuel web UI.
3. Scroll down the page, select the LMA collector plugin checkbox and fill-in
the required fields.
Exploring the data
------------------
Refer to the [Elasticsearch/Kibana
plugin](https://github.com/openstack/fuel-plugin-elasticsearch-kibana) for
exploring and visualizing the collected logs and notifications and refer to the
[InfluxDB-Grafana Fuel Plugin
](https://github.com/openstack/fuel-plugin-influxdb-grafana) for monitoring
your cloud.
Troubleshooting
---------------
If you see no data in the Elasticsearch and/or InfluxDB servers, check the
following:
1. The LMA collector service is running
```
# On controller node
crm resource status lma_collector
# On CentOS (other than a controller)
/etc/init.d/lma_collector status
# On Ubuntu (other than a controller)
status lma_collector
```
2. Look for errors in the LMA collector log file (located at
`/var/log/lma_collector.log`) on the different nodes.
3. Nodes are able to connect to the Elasticsearch server on port 9200.
4. Nodes are able to connect to the InfluxDB server on port 8086.
Known issues
------------
None
Release Notes
-------------
@@ -251,25 +73,44 @@ Release Notes
* Initial release of the plugin. This is a beta version.
Development
===========
Requirements
------------
The *OpenStack Development Mailing List* is the preferred way to communicate,
emails should be sent to `openstack-dev@lists.openstack.org` with the subject
prefixed by `[fuel][plugins][lma]`.
The plugin's requirements are defined in the [LMA Collector Plugin Documentation](
http://fuel-plugin-lma-collector.readthedocs.org/en/latest/user/overview.html#requirements)
Running tests
Known issues
------------
No known issues so far.
Limitations
-----------
The plugin is only compatible with OpenStack environments deployed with Neutron
for networking.
Installation Guide
------------------
Please follow the installation instructions of the [LMA Collector Plugin Documentation](
http://fuel-plugin-lma-collector.readthedocs.org/en/latest/user/installation.html#installation)
User Guide
----------
How to configure and use the plugin is detailed in the [The LMA Collector Plugin Documentation](
http://fuel-plugin-lma-collector.readthedocs.org/en/latest/user/guide.html#user-guide)
Communication
-------------
You need to have `tox` and `bundler` installed for running the tests.
The *OpenStack Development Mailing List* is the preferred way to communicate
with the members of the project.
Emails should be sent to `openstack-dev@lists.openstack.org` with the subject
prefixed by `[fuel][plugins][lma]`.
Quickstart for Ubuntu Trusty:
```
apt-get install tox ruby
gem install bundler
tox
```
Reporting Bugs
--------------

10
doc/source/user/guide.rst
View File

@@ -16,17 +16,19 @@ To configure your plugin, you need to follow the folling steps:
3. Select the LMA collector plugin in the left column. The LMA Collector settings screen appears.
.. image:: ../../images/collector_settings.png
.. image:: ../../images/collector_settings.png
:scale: 50 %
:alt: The LMA Collector settings
:alt: The LMA Collector settings
:align: center
4. Select the LMA collector plugin checkbox and fill-in the required fields.
a. Select "Local node" for Events analytics if you deploy the Elasticsearch-Kibana plugin on a dedicated node in the same environment.
b. Select "Remote server" for Events analytics if you have an Elasticsearch-Kibana server already deployed and running. In that case, you have to enter the IP address or the fully qualified name of the server.
b. Select "Remote server" for Events analytics if you have an Elasticsearch-Kibana server already deployed and running.
In that case, you have to enter the IP address or the fully qualified name of the server.
c. Select "Local node" for Metrics analytics if you deploy the InfluxDB-Grafana plugin on a dedicated node in the same environment.
d. Select "Remote server" for Metrics analytics if you have an InfluxDB-Grafana server already deployed and running. In that case, you have to enter the IP address or the fully qualified name of the server as well as the credentials and database to store the metrics.
d. Select "Remote server" for Metrics analytics if you have an InfluxDB-Grafana server already deployed and running.
In that case, you have to enter the IP address or the fully qualified name of the server as well as the credentials and database to store the metrics.
e. Select "Alerts sent by email" for Alerting if you wish to receive alerts by email.
f. Select "Alerts sent to a local node" for Alerting if you deploy the LMA Infrastructure Alerting plugin on a dedicated node in the same environment.
g. Select "Alerts sent to a remote Nagios server" for Alerting if you have a Nagios server already deployed and running.

87
doc/source/user/installation.rst
View File

@@ -10,31 +10,32 @@ dependencies:
* InfluxDB and Grafana for metrics analytics
* Nagios for alerting
To install them automatically using Fuel, you can refer to the
Elasticsearch-Kibana Fuel Plugin, InfluxDB-Grafana Fuel Plugin, and LMA
Infrastructure Alerting Fuel Plugin documentation in the `Fuel Plugins Catalog <https://software.mirantis.com/download-mirantis-openstack-fuel-plug-ins/>`_.
To install them automatically you can refer to the:
You can install Elasticsearch/Kibana, InfluxDB/Grafana and Nagios outside of
Fuel as long as your installation meets the LMA Collector plugin's :ref:`requirements <plugin_requirements>`.
1. `LMA Collector Fuel Plugin Installation Guide <http://fuel-plugin-lma_collector.readthedocs.org/en/latest/installation.html#installation-guide>`_.
2. `InfluxDB-Grafana Fuel Plugin Installation Guide <http://fuel-plugin-influxdb-grafana.readthedocs.org/en/latest/installation.html#installation-guide>`_.
3. `Infrastructure Alerting Fuel Plugin Installation Guide <http://fuel-plugin-lma-infrastructure-alerting.readthedocs.org/en/latest/installation.html#installation-guide>`_.
You can install Elasticsearch/Kibana, InfluxDB/Grafana and Nagios outside of the
Fuel Plugin framework as long as your installation meets the LMA Collector plugin's :ref:`requirements <plugin_requirements>`.
Install the plugin on the Fuel master node
------------------------------------------
LMA Collector Fuel Plugin install using the RPM file of the Fuel Plugins Catalog
--------------------------------------------------------------------------------
To install the LMA Collector plugin, follow these steps:
To install the LMA Collector Fuel Plugin using the RPM file of the Fuel Plugins
Catalog, you need to follow these steps:
1. Download the plugin from the `Fuel Plugins Catalog <https://software.mirantis.com/download-mirantis-openstack-fuel-plug-ins/>`_.
1. Download the RPM file from the `Fuel Plugins Catalog <https://software.mirantis.com/download-mirantis-openstack-fuel-plug-ins/>`_.
2. Copy the plugin file to the Fuel Master node::
2. Copy the RPM file to the Fuel Master node::
[root@home ~]# scp lma_collector-0.8-0.8.0-1.noarch.rpm root@<Fuel Master node IP address>:
3. Install the plugin using the `Fuel CLI <http://docs.mirantis.com/openstack/fuel/fuel-7.0/user-guide.html#using-fuel-cli>`_::
[root@fuel ~]# fuel plugins --install lma_collector-0.8-0.8.0-1.noarch.rpm
4. Verify that the plugin is installed correctly::
[root@fuel ~]# fuel plugins --list
@@ -43,7 +44,61 @@ To install the LMA Collector plugin, follow these steps:
1 | lma_collector | 0.8.0 | 2.0.0
Alternatively, you may want to build the rpm file of the plugin yourself if,
for example, you want to modify some configuration elements. But note that this
is at your own risk. Detailed instructions to build the LMA Collector plugin
are provided in the README.md file of the `project <https://github.com/openstack/fuel-plugin-lma-collector>`_.
LMA Collector Fuel Plugin install from source
---------------------------------------------
Alternatively, you may want to build the RPM file of the plugin from the
lastest stable release if, for example, you want to modify some built-in
configuration parameters. But note that this is at your own risk.
To install LMA 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.
**Prepare an environment for building the plugin on the Fuel Master Node**
1. Install the standard Linux development tools::
[root@home ~] yum install createrepo rpm rpm-build dpkg-devel
2. Install the Fuel Plugin Builder. To do that, you should first get pip::
[root@home ~] easy_install pip
3. Then install the Fuel Plugin Builder (the `fpb` command line) with `pip`::
[root@home ~] pip install fuel-plugin-builder
**Note**: You may also need to build the Fuel Plugin Builder if the package version of the
plugin is higher than 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.
4. Clone the plugin git repository::
[root@home ~] git clone git@github.com:openstack/fuel-plugin-lma_collector.git
5. Check that the plugin is valid::
[root@home ~] fpb --check ./fuel-plugin-lma_collector
6. And finally, build the plugin::
[root@home ~] fpb --build ./fuel-plugin-lma_collector
7. Now that you have created the RPM file, you can install the plugin using the `fuel plugins --install` command::
[root@fuel ~] fuel plugins --install ./fuel-plugin-lma_collector/lma_collector-0.8-0.8.0-1.noarch.rpm
Running tests
-------------
You need to have `tox` and `bundler` installed for running the tests.
Quickstart for Ubuntu Trusty::
apt-get install tox ruby
gem install bundler
tox

2
doc/source/user/overview.rst
View File

@@ -42,7 +42,7 @@ Requirements
+-------------------------------------------------------+-----------------------------------------------------------------+
| Requirement | Version/Comment |
+=======================================================+=================================================================+
| Fuel | 7.0 |
| Mirantis OpenStack | 7.0 |
+-------------------------------------------------------+-----------------------------------------------------------------+
| A running Elasticsearch server (for log analytics) | 1.4 or higher, the RESTful API must be enabled over port 9200 |
+-------------------------------------------------------+-----------------------------------------------------------------+