diff --git a/doc/source/GSG.rst b/doc/source/GSG.rst index 16aeadf..0b2becb 100644 --- a/doc/source/GSG.rst +++ b/doc/source/GSG.rst @@ -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 "" + $ 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 - at the end of the section. Edit the line to include the name of - of your chosen meter and its new units. +* In your collectd-ceilometer-plugin.conf file add in the following lines + at the end of the section. Edit the line to include the name of + of your chosen meter and its new units. -:: - + :: + + UNIT - + - Additional lines of a similar nature can be added to change the units of - multiple meters. +* 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 - have been updated. +* 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 -| ceilometer sample-list | grep + :: + + $ ceilometer meter-list | grep + $ ceilometer sample-list | grep + 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 diff --git a/doc/source/devstackGSG.rst b/doc/source/devstackGSG.rst index 0a8a84a..0a285e4 100644 --- a/doc/source/devstackGSG.rst +++ b/doc/source/devstackGSG.rst @@ -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,30 +102,36 @@ 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=" " + :: - If you would like to add more than one new unit include them in the same line + COLLECTD_CUSTOM_UNITS=" " + +* 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=" , " + :: + + COLLECTD_CUSTOM_UNITS=" , " 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 + :: - COLLECTD_INSTALL=True + enable_plugin collectd-ceilometer-plugin http://github.com/openstack/collectd-ceilometer-plugin - # GNOCCHI - enable_plugin gnocchi https://github.com/openstack/gnocchi master - enable_service gnocchi-api,gnocchi-metricd,gnocchi-statsd - GNOCCHI_USE_KEYSTONE=True - COLLECTD_GNOCCHI_ENABLED=True + COLLECTD_INSTALL=True + + # GNOCCHI + enable_plugin gnocchi https://github.com/openstack/gnocchi master + enable_service gnocchi-api,gnocchi-metricd,gnocchi-statsd + GNOCCHI_USE_KEYSTONE=True + 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 + # AODH + enable_plugin aodh https://git.openstack.org/openstack/aodh + + 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:`` Finally an alarm can also be created in a heat template. The instructions for -this are provided in: -See :doc:`` +this are provided in :doc:`` + This enables you to scale a resource that you define based on the triggering of an alarm. diff --git a/doc/source/index.rst b/doc/source/index.rst index 7e057e7..255798e 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -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 ------------------ diff --git a/doc/source/troubleshooting.rst b/doc/source/troubleshooting.rst index e599b91..bc06dc3 100644 --- a/doc/source/troubleshooting.rst +++ b/doc/source/troubleshooting.rst @@ -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 + + :: + + $ 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" + + :: + + Include "/etc/collectd/collectd.conf.d/*.conf" + OR - :: - - Filter "*.conf" - + + :: + + + Filter "*.conf" + - 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. diff --git a/doc/source/vagrant.rst b/doc/source/vagrant.rst index 667ac08..957a516 100644 --- a/doc/source/vagrant.rst +++ b/doc/source/vagrant.rst @@ -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,20 +74,24 @@ 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://:/ - export https_proxy=$https_proxy - export no_proxy=localhost,$(hostname) + :: + + export http_proxy=http://:/ + export https_proxy=$https_proxy + export no_proxy=localhost,$(hostname) Create and use the appliance @@ -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 + :: - # 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 + # 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 + + # 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 -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' diff --git a/kolla/installation.rst b/kolla/installation.rst index fa041fc..c11c0e6 100644 --- a/kolla/installation.rst +++ b/kolla/installation.rst @@ -32,7 +32,7 @@ Pre-requisites -------------- - Access to the internet -- Keystaone and Ceilometer enabled +- Keystone and Ceilometer enabled Installation of Kolla --------------------- @@ -53,62 +53,62 @@ following settings: * Enable collectd so that its container is created. Additionally, enable ceilometer and mongodb to ensure the ceilometer service is installed. -:: + :: - enable_collectd: "yes" - enable_ceilometer: "yes" - enable_mongodb: "yes" + enable_collectd: "yes" + enable_ceilometer: "yes" + enable_mongodb: "yes" * Edit the network settings to suit your environment by changing the following: -:: + :: - kolla_internal_vip_address: - network_interface: - neutron_external_interface: + kolla_internal_vip_address: + network_interface: + neutron_external_interface: * To customize the images that are built with kolla change: -:: + :: - kolla_base_distro: - kolla_install_type: + kolla_base_distro: + kolla_install_type: In the kolla-build.conf file uncomment/paste the following lines into the plugins section. -:: + :: - [collectd-plugin-collectd-ceilometer-plugin] - type = git - location = https://github.com/openstack/collectd-ceilometer-plugin.git - reference = master + [collectd-plugin-collectd-ceilometer-plugin] + type = git + location = https://github.com/openstack/collectd-ceilometer-plugin.git + reference = master To build the collectd container with the collectd-ceilometer-plugin repository, copy the ``template-override.json`` file to a local directory. Run the following command to build the container. -:: + :: - kolla-build --template-override + $ kolla-build --template-override Verification of Collectd ------------------------ 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 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. @@ -125,26 +125,32 @@ The other entries you need to edit in this file are outlined below: * Include the "ModulePath" to the collectd-ceilometer-plugin directory. -:: + :: - ModulePath "/path/to/module" + ModulePath "/path/to/module" * Specify your endpoint address, OS_AUTH_URL "". To determine this 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 + :: - 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 meter-list -| ceilometer sample-list --meter cpu.cpu +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 diff --git a/releasenotes/notes/bug-1684121-8cc5c8a83729d992.yaml b/releasenotes/notes/bug-1684121-8cc5c8a83729d992.yaml new file mode 100644 index 0000000..6363a43 --- /dev/null +++ b/releasenotes/notes/bug-1684121-8cc5c8a83729d992.yaml @@ -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.