x/collectd-openstack-plugins
Code Issues Proposed changes

Fixed documentation formatting

Browse Source 
Fixed rendering, typos and alignment

Change-Id: Ib9425fe1b94634287e45b4a225cf8d74cb8745e2
Closes-bug: #1684121
This commit is contained in:
Helena McGough 2017-04-21 08:37:34 +00:00 committed by Emma Foley
parent 88a83e59ef
commit 8d711aabf6
7 changed files with 267 additions and 167 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

141
doc/source/GSG.rst
View File

@ -32,7 +32,7 @@ Pre-requisites
--------------
- Access to the internet
- A working Openstack environment
- A working OpenStack environment
- Keystone and Ceilometer services enabled
Collectd Set-up
@ -41,54 +41,73 @@ Collectd Set-up
Ensure that the binary packages for your Linux distribution are installed
and up-to-date.
| sudo apt-get install build-essential
::
Install the libraries that allow the plugins to collect the actual values.
$ sudo apt-get install build-essential
| sudo apt-get install flex bison automake pkg-config libtool python-dev
Install the libraries that allow the plugins to collect the actual values:
Clone the source code from the repo.
::
| git clone http://github.com/collectd/collectd
$ sudo apt-get install flex bison automake pkg-config libtool python-dev
Clone the source code from the repo:
::
$ git clone http://github.com/collectd/collectd
Currently there are two major versions of collectd; Version 4 and version 5.
Version 4 is outdated, so version 5 should be used for this setup.
Checkout the version 5.6 branch.
Checkout the version 5.6 branch:
| cd collectd
| git checkout collectd-5.6
::
Then build this version:
$ cd collectd
$ git checkout collectd-5.6
| sudo ./build.sh
Build this version:
Once built, configure collectd.
::
| sudo ./configure --enable-syslog --enable-plugin --enable-logfile --enable-debug --prefix=/usr
$ sudo ./build.sh
Now, install collectd.
Configure collectd:
| sudo make -j
| sudo make install
::
Set and Configure Collectd as a Service
---------------------------------------
$ sudo ./configure --enable-syslog --enable-plugin --enable-logfile --enable-debug --prefix=/usr
Install collectd:
::
$ sudo make -j
$ sudo make install
Configure Collectd as a Service
-------------------------------
To enable collectd as a service on your system copy the .service onto your
system. This file is located in the "/collectd/contrib/" directory of the repo.
| sudo cp contrib/systemd.collectd.service /lib/systemd/system
::
Start collectd as a service.
$ sudo cp contrib/systemd.collectd.service /lib/systemd/system
| sudo service systemd.collectd start
Start collectd as a service:
Check the status of collectd.
::
| sudo service systemd.collectd status
$ sudo service systemd.collectd start
Check the status of collectd:
::
$ sudo service systemd.collectd status
For further information on enabling collectd as a service:
https://collectd.org/wiki/index.php/First_steps#Starting_the_daemon
Installation and Configuration of collectd-ceilometer-plugin
@ -96,7 +115,9 @@ Installation and Configuration of collectd-ceilometer-plugin
Clone the collectd-ceilometer-plugin code.
| git clone https://github.com/openstack/collectd-ceilometer-plugin
::
$ git clone https://github.com/openstack/collectd-ceilometer-plugin
By default, the collectd.conf file is located in "/etc/collectd.conf",
but because you specified "--prefix=/usr" during configuration it is now
@ -106,9 +127,12 @@ Configurations for the plugin itself are specified in its own .conf file,
collectd-ceilometer-plugin.conf.
Copy collectd-celiometer-plugin/etc/collectd.conf.d/collectd-ceilometer-plugin.conf
onto your machine. Include the filepath to this file in your collectd.conf file.
onto your machine. Include the filepath to this file in your collectd.conf file:
| Include /path/to/collectd-ceilometer-plugin.conf
::
Include /path/to/collectd-ceilometer-plugin.conf
In the collectd-ceilometer-plugin.conf file a few variables have to be changed
to suit your environment:
@ -117,50 +141,59 @@ to suit your environment:
directory.
* You must specify the service endpoint address, "OS_AUTH_URL". In an openstack
setup you can use the openstack client to identify this.
setup you can use the openstack client to identify this. Look for the keystone
internalURL to and use it as your "OS_AUTH_URL".
| openstack catalog list
::
Look for the keystone internalURL to and use it as your "OS_AUTH_URL".
| OS_AUTH_URL "<OS_AUTH_URL>"
$ openstack catalog list
* Finally, set the type of URL used for the ceilometer service to
"internalURL".
| CEILOMETER_URL_TYPE "internalURL"
::
CEILOMETER_URL_TYPE "internalURL"
* If you would like to enable any additional features please follow the
instructions provided in the "Additional Features" section below before
moving on to the next step.
Now, you can restart the collectd service and the plugin for ceilometer should
be working with collectd.
Restart the collectd service:
| sudo service systemd.collectd restart
::
Verification of ceilometer
--------------------------
$ sudo service systemd.collectd restart
Verification
------------
To verify that ceilometer is working with collectd use the ceilometer client.
* Source the credentials required to use your openstack client.
| source openrc
::
$ source openrc
* To verify that the stats are going through to ceilometer, view the ceilometer
meter list.
| ceilometer meter-list
::
$ ceilometer meter-list
Specifically, one of the default meters that is enabled by collectd is
"cpu.cpu". Check that this meter is enabled.
| ceilometer sample-list --meter cpu.cpu
::
$ ceilometer sample-list --meter cpu.cpu
Additional Features
-------------------
Customized Units
~~~~~~~~~~~~~~~~
@ -171,28 +204,32 @@ doesn't provide its own unit mappings, this feature can be used to add in the
new units for this meter.
To utilize this feature you must enable it before restarting the service.
Follow the instructions below to implement it:
Follow the instructions below:
- In your collectd-ceilometer-plugin.conf file add in the following lines
* In your collectd-ceilometer-plugin.conf file add in the following lines
at the end of the <Module> section. Edit the line to include the name of
of your chosen meter and its new units.
::
<UNITS>
UNIT <meter_name> <units>
</UNITS>
Additional lines of a similar nature can be added to change the units of
* Additional lines of a similar nature can be added to change the units of
multiple meters.
- Now you can restart the collectd service and your customized units will
* Restart the collectd service and your customized units will
have been updated.
To verify that the units have been changed, observe the ceilometer meter-list
or the sample-list and check the units of the meter that you changed.
| ceilometer meter-list | grep <meter_name>
| ceilometer sample-list | grep <meter_name>
::
$ ceilometer meter-list | grep <meter_name>
$ ceilometer sample-list | grep <meter_name>
Troubleshooting
---------------
@ -200,14 +237,18 @@ Troubleshooting
If you are unable to verify that ceilometer is working with collectd, try
restarting the service, then check the meter list again.
| systemctl restart systemd.collectd.service
::
$ systemctl restart systemd.collectd.service
Then you can also check the status of the service again or for further details
you can use the following command.
| sudo journalctl -xe
::
This will allow you to examine any errors that are occuring.
$ sudo journalctl -xe
This will allow you to examine any errors that are occurring.
If the plugin still doesn't appear to be working and the collectd service is
running correctly without any errors, try enabling the csv plugin. This will

81
doc/source/devstackGSG.rst
View File

@ -22,71 +22,79 @@
Avoid deeper levels because they do not render well.
===================================================
Installing Collectd-ceilometer-plugin with Devstack
Installing collectd-ceilometer-plugin with DevStack
===================================================
This guide outlines how to install the collectd-ceilometer-plugin using a
devstack deployment.
This guide outlines how to install the collectd-ceilometer-plugin using
DevStack.
Pre-requisites
--------------
- Access to the internet
Installation of Devstack
Installation of DevStack
------------------------
Follow the instructions provided in the following document to set up your own
Devstack deployment.
Follow the instructions provided in the following documentation to set up your
own DevStack.
http://docs.openstack.org/developer/devstack/guides/single-machine.html
Once Devstack is ready to be deployed, follow the configuration steps in the
Once DevStack is ready to be deployed, follow the configuration steps in the
next section to allow the installation of the plugin during deployment.
Configuration of Devstack
Configuration of DevStack
-------------------------
These configuration instructions only allow for the minimal installation of
collectd, ceilometer and the plugin. The sample local.conf provided must be
edited to enable additional services.
To configure Devstack for to install the plugin, download the sample local.conf
from the collectd-ceilometer-plugin repo into your devstack directory.
To configure DevStack for to install the plugin, download the sample local.conf
from the collectd-ceilometer-plugin repo into your DevStack directory.
| cd devstack
| wget https://github.com/openstack/collectd-ceilometer-plugin/blob/master/collectd_ceilometer/doc/source/examples/local.conf.minimal
::
$ cd devstack
$ wget https://github.com/openstack/collectd-ceilometer-plugin/blob/master/doc/source/examples/local.conf.minimal
Edit the "HOST_IP" varible to appropriately match your environment.
Also include your chosen "CEILOMETER_BACKEND", as there is no default backend for
Include your chosen "CEILOMETER_BACKEND", as there is no default backend for
ceilometer. The options for this backend include mysql,es,postgresql or mongodb.
If you wish to enable any extra features please follow the instructions in the
"Additional Features" section below before moving on to the next step.
Finally, build your devstack environment.
Create your DevStack environment:
| ./stack.sh
::
Verfication of Collectd-ceilometer-plugin
$ ./stack.sh
Verfication of collectd-ceilometer-plugin
-----------------------------------------
Confirm that the collectd service is up and running.
Confirm that the collectd service is up and running:
| sudo systemctl status collectd.service
::
By default collectd enables the "cpu.cpu" meter. Check that the statistics for
$ sudo systemctl status collectd.service
By default, collectd enables the "cpu.cpu" meter. Check that the statistics for
this meter are being sent to ceilometer, thus confirming that collectd is
working with ceilometer.
| ceilometer sample-list --meter cpu.cpu
::
Addtional Features
------------------
$ ceilometer sample-list --meter cpu.cpu
Custom Units Feature
~~~~~~~~~~~~~~~~~~~~
Additional Features
-------------------
Custom Units
~~~~~~~~~~~~
This feature enables users to define new units for existing meter values.
To enable this feature execute the following instructions:
@ -94,17 +102,23 @@ To enable this feature execute the following instructions:
* To include your new units, add the following line with your chosen units to
your local.conf file.
| COLLECTD_CUSTOM_UNITS="<meter> <unit>"
::
If you would like to add more than one new unit include them in the same line
COLLECTD_CUSTOM_UNITS="<meter> <unit>"
* If you would like to add more than one new unit include them in the same line
and seperate each meter and its unit with a comma, as shown below.
| COLLECTD_CUSTOM_UNITS="<meter> <unit>,<meter> <unit>"
::
COLLECTD_CUSTOM_UNITS="<meter> <unit>,<meter> <unit>"
Gnocchi
-------
To deploy with gnocchi using devstack, add the following to you local.conf:
To deploy with gnocchi using DevStack, add the following to you local.conf:
::
enable_plugin collectd-ceilometer-plugin http://github.com/openstack/collectd-ceilometer-plugin
@ -117,7 +131,7 @@ To deploy with gnocchi using devstack, add the following to you local.conf:
COLLECTD_GNOCCHI_ENABLED=True
Aodh
====
----
Aodh is an alarming service that allows an alarm to be created and/or updated
if there is something unusual happening with the system. When this service is
@ -126,19 +140,20 @@ created/updated for all notifications sent from collectd. All notifications
sent from collectd are configured as event alarms in Aodh.
To enable aodh with collectd, add the following to your local.conf:
::
# AODH
enable_plugin aodh https://git.openstack.org/openstack/aodh
enable_plugin collectd-ceilometer-plugin http://github.com/openstack/collectd-ceilometer-plugin
COLLECTD_AODH_ENABLED=True
In addition to this, alarms can be created manually via the Aodh command line
based on the metrics generated by the gnocchi plugin and meters from the
ceilometer plugin. For more information on this please read
doc/source/alarms_guide.rst.
:doc:`<alarms_guide.rst>`
Finally an alarm can also be created in a heat template. The instructions for
this are provided in:
See :doc:`<heat_scaling_guide.rst>`
this are provided in :doc:`<heat_scaling_guide.rst>`
This enables you to scale a resource that you define based on the triggering of
an alarm.

7
doc/source/index.rst
View File

@ -27,13 +27,16 @@ Welcome to collectd-ceilometer-plugin's documentation!
Contents:
.. toctree::
:maxdepth: 2
.. [TOC]:
readme
installation
usage
contributing
devstackGSG
GSG
vagrant
troubleshooting
Indices and tables
------------------

12
doc/source/troubleshooting.rst
View File

@ -49,21 +49,31 @@ the information below can help diagnose the problem:
you that.
- Is the correct OS_AUTH_URL is used?
::
$ openstack catalog show keystone
$ grep "OS_AUTH_URL" /path/to/collectd.conf.d/collectd-ceilometer-plugin.conf
- Is collectd-ceilometer-plugin.conf being parsed?
- Does the collectd.conf have an Include block/directive?
::
Include "/etc/collectd/collectd.conf.d/*.conf"
OR
::
<Include /etc/collectd/collectd.conf.d/>
Filter "*.conf"
</Include>
- Enable the logfile plugin in collectd for better information (sample
configuration at `../etc/collectd.conf.d/logging.conf`_)
configuration at `../etc/collectd.conf.d/logging.conf`_).
- Make sure to set the LogLevel to “debug” for maximum information
- Use "VERBOSE True" in collectd-ceilometer-plugin.conf, in order to elevate
debug messages to LogLevel info.

42
doc/source/vagrant.rst
View File

@ -29,6 +29,7 @@ This project is distributed with a Vagrantfile intended to be used by
developers to run functional tests on a Linux virtual machine.
The software provided by the appliance are:
- Ubuntu Server 16.04 LTS appliance running inside Virtual Box
- The collectd provided by Ubuntu
- Python 2.7 and 3.4 provided by Ubuntu
@ -37,6 +38,7 @@ The software provided by the appliance are:
To use Vagrant to test this plugin you have to install following software
up to date software on your host machine:
- Vagrant
- VirtualBox 5
@ -44,13 +46,13 @@ up to date software on your host machine:
Vagrant
-------
Documentation to install Vagrant can be found on there website at
Documentation to install Vagrant can be found on there website at:
https://www.vagrantup.com/docs/installation/
A recent version of Vagrant is required to utilize the vagrant file provided by
this repo. If you have an older version already installed please upgrade by
following the documentation at
following the documentation at:
https://www.vagrantup.com/docs/installation/upgrading.html
@ -72,16 +74,20 @@ Proxy configuration
-------------------
If you are working beside a proxy server then you have to install
vagrant-proxyconf plugin::
vagrant-proxyconf plugin:
vagrant plugin install vagrant-proxyconf
::
$ vagrant plugin install vagrant-proxyconf
You can have more details about the plugin on below site:
https://github.com/tmatilai/vagrant-proxyconf
To use it, before creating target appliance, you have to configure standard
enviroment variable on your host machine like below::
enviroment variable on your host machine like below:
::
export http_proxy=http://<some_proxy_server>:<some_port>/
export https_proxy=$https_proxy
@ -93,27 +99,35 @@ Create and use the appliance
Once all required software is installed and configured you can create
and launch the appliance as follows (it can take several minutes) from
the project folder::
the project folder
vagrant up
::
Once the appliance is running connect to the running VM you can type following::
$ vagrant up
vagrant ssh
Once the appliance is running connect to the running VM you can type following
::
$ vagrant ssh
During the provisioning process collectd and ceilometer are going to be
installed and launched using devstack. To force updating the project and
restacking it again please use one of the following commands::
restacking it again please use one of the following commands
::
# when the machine is down and I want to take it up, update the software
# and start all services (including collectd and ceilometer)
vagrant up --provision
$ vagrant up --provision
# when the machine is running and I want to take reboot it, update the
# software and re-start all services (including collectd and ceilometer)
vagrant reload --provision
$ vagrant reload --provision
To launch unit tests inside the appliance you can type following::
To launch unit tests inside the appliance you can type following
vagrant ssh -c 'cd /vagrant && tox'
::
$ vagrant ssh -c 'cd /vagrant && tox'

33
kolla/installation.rst
View File

@ -32,7 +32,7 @@ Pre-requisites
--------------
- Access to the internet
- Keystaone and Ceilometer enabled
- Keystone and Ceilometer enabled
Installation of Kolla
---------------------
@ -91,7 +91,7 @@ Run the following command to build the container.
::
kolla-build --template-override <path_to_template_override_file>
$ kolla-build --template-override <path_to_template_override_file>
Verification of Collectd
------------------------
@ -100,7 +100,7 @@ To verify the successful build of the collectd image run the following command.
::
docker images | grep -i collectd
$ docker images | grep -i collectd
Follow the steps in the Kolla documentation to install OpenStack, which are
provided above. Run the following command to check if the collectd container
@ -108,7 +108,7 @@ is up and running.
::
docker ps |grep -i collectd
$ docker ps | grep -i collectd
The status of the collectd container should be "Up".
@ -116,7 +116,7 @@ Configure collectd-ceilometer-plugin
------------------------------------
Edit the ``/kolla/etc/collectd-ceilometer-plugin.conf`` file and replace the
varaiables with appropriate values. The passwords and endpoints will be
variables with appropriate values. The passwords and endpoints will be
provided by the operator. If these entries are not provided, run the
post-deploy script as mentioned in the Kolla guide to generate the passwords
and endpoints.
@ -133,18 +133,24 @@ The other entries you need to edit in this file are outlined below:
address, use your openstack client, run the following command and select the
keystone internalURL.
| openstack catalog list
::
$ openstack catalog list
* The CEILOMETER_URL_TYPE should be set for you, but if not set it to
"internalURL".
Copy this config file to ``/etc/kolla/collectd/collectd.conf.d`` folder.
| sudo cp collectd-ceilometer-plugin.conf /etc/kolla/collectd/collectd.conf.d
::
$ sudo cp collectd-ceilometer-plugin.conf /etc/kolla/collectd/collectd.conf.d
Restart the collectd container for the changes to take affect.
| docker restart collectd
::
$ docker restart collectd
Verify the container is up and running.
@ -155,16 +161,21 @@ To verify that the plugin is working, use the ceilometer client.
* Source the credentials provided by the kolla post-deploy script.
| source admin-openrc.sh
::
$ source admin-openrc.sh
* To verify that the stats are going through to ceilometer, view the meter
list created by ceilometer.
| ceilometer meter-list
::
$ ceilometer meter-list
Check this list for the default meters that are enabled by collectd. One of
these is "cpu.cpu". Check the ceilometer sample list for this meter, to
confirm it is enabled.
| ceilometer sample-list --meter cpu.cpu
::
$ ceilometer sample-list --meter cpu.cpu

6
releasenotes/notes/bug-1684121-8cc5c8a83729d992.yaml Normal file
View File

@ -0,0 +1,6 @@
---
fixes:
- |
Fixes 'bug 1684121 https://bugs.launchpad.net/collectd-ceilometer-plugin/+bug/1684121'.
Checked and fixed any rendering, typo or allignment errors in the
documentation.