openstack/ceilometer
Code Issues Proposed changes

re-org existing manually install notes

Browse Source 
- move enabling service notifications into own section
- clean up copy/paste install instructions
- add note to inform performance boast by disabling message signing
- add note to inform API is not required if Gnocchi is used.
- clean up oslo.messaging items
- remove verbose notes
    - zmq not ready
    - how to use PasteDeploy
- move customisation possibilites into it's own page

Change-Id: Ia42ceec7d2b6c054d065f905b8c0bce1685119aa
This commit is contained in:
gordon chung 2016-04-04 12:56:59 -04:00
parent 6a0f84dcbb
commit 182b4bd42e
4 changed files with 319 additions and 370 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

152
doc/source/install/custom.rst Normal file
View File

@ -0,0 +1,152 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
.. _customizing_deployment:
===================================
Customizing Ceilometer Deployment
===================================
Notifications queues
====================
.. index::
double: customizing deployment; notifications queues; multiple topics
By default, Ceilometer consumes notifications on the messaging bus sent to
**topics** by using a queue/pool name that is identical to the
topic name. You shouldn't have different applications consuming messages from
this queue. If you want to also consume the topic notifications with a system
other than Ceilometer, you should configure a separate queue that listens for
the same messages.
Ceilometer allows multiple topics to be configured so that the polling agent can
send the same messages of notifications to other queues. Notification agents
also use **topics** to configure which queue to listen for. If
you use multiple topics, you should configure notification agent and polling
agent separately, otherwise Ceilometer collects duplicate samples.
By default, the ceilometer.conf file is as follows::
[oslo_messaging_notifications]
topics = notifications
To use multiple topics, you should give ceilometer-agent-notification and
ceilometer-polling services different ceilometer.conf files. The Ceilometer
configuration file ceilometer.conf is normally locate in the /etc/ceilometer
directory. Make changes according to your requirements which may look like
the following::
For notification agent using ceilometer-notification.conf, settings like::
[oslo_messaging_notifications]
topics = notifications,xxx
For polling agent using ceilometer-polling.conf, settings like::
[oslo_messaging_notifications]
topics = notifications,foo
.. note::
notification_topics in ceilometer-notification.conf should only have one same
topic in ceilometer-polling.conf
Doing this, it's easy to listen/receive data from multiple internal and external services.
Using multiple dispatchers
==========================
.. index::
double: customizing deployment; multiple dispatchers
The Ceilometer collector allows multiple dispatchers to be configured so that
data can be easily sent to multiple internal and external systems. Dispatchers
are divided between ``event_dispatchers`` and ``meter_dispatchers`` which can
each be provided with their own set of receiving systems.
.. note::
In Liberty and prior, the configuration option for all data was
``dispatcher`` but this was changed for the Mitaka release to break out
separate destination systems by type of data.
By default, Ceilometer only saves event and meter data in a database. If you
want Ceilometer to send data to other systems, instead of or in addition to
the Ceilometer database, multiple dispatchers can be enabled by modifying the
Ceilometer configuration file.
Ceilometer ships multiple dispatchers currently. They are ``database``,
``file``, ``http`` and ``gnocchi`` dispatcher. As the names imply, database
dispatcher sends metering data to a database, file dispatcher logs meters into
a file, http dispatcher posts the meters onto a http target, gnocchi
dispatcher posts the meters onto Gnocchi_ backend. Each dispatcher can have
its own configuration parameters. Please see available configuration
parameters at the beginning of each dispatcher file.
.. _Gnocchi: http://gnocchi.readthedocs.org/en/latest/basic.html
To check if any of the dispatchers is available in your system, you can
inspect the Ceilometer egg entry_points.txt file, you should normally see text
like the following::
[ceilometer.dispatcher]
database = ceilometer.dispatcher.database:DatabaseDispatcher
file = ceilometer.dispatcher.file:FileDispatcher
http = ceilometer.dispatcher.http:HttpDispatcher
gnocchi = ceilometer.dispatcher.gnocchi:GnocchiDispatcher
To configure one or multiple dispatchers for Ceilometer, find the Ceilometer
configuration file ceilometer.conf which is normally located at /etc/ceilometer
directory and make changes accordingly. Your configuration file can be in a
different directory.
To use multiple dispatchers on a Ceilometer collector service, add multiple
dispatcher lines in ceilometer.conf file like the following::
[DEFAULT]
meter_dispatchers=database
meter_dispatchers=file
If there is no dispatcher present, database dispatcher is used as the
default. If in some cases such as traffic tests, no dispatcher is needed,
one can configure the line without a dispatcher, like the following::
event_dispatchers=
With the above configuration, no event dispatcher is used by the Ceilometer
collector service, all event data received by Ceilometer collector will be
dropped.
For Gnocchi dispatcher, the following configuration settings should be added::
[DEFAULT]
meter_dispatchers = gnocchi
[dispatcher_gnocchi]
archive_policy = low
The value specified for ``archive_policy`` should correspond to the name of an
``archive_policy`` configured within Gnocchi.
For Gnocchi dispatcher backed by Swift storage, the following additional
configuration settings should be added::
[dispatcher_gnocchi]
filter_project = gnocchi_swift
filter_service_activity = True
.. note::
If gnocchi dispatcher is enabled, Ceilometer api calls will return a 410 with
an empty result. The Gnocchi Api should be used instead to access the data.

2
doc/source/install/dbreco.rst
View File

@ -19,7 +19,7 @@
Choosing a database backend - Legacy Choosing a database backend - Legacy
===================================== =====================================
.. note: .. note::
Ceilometer's existing database capabilities is intended for post processing Ceilometer's existing database capabilities is intended for post processing
and auditing purposes where responsiveness is not a requirement. It and auditing purposes where responsiveness is not a requirement. It

1
doc/source/install/index.rst
View File

@ -25,5 +25,6 @@
dbreco dbreco
development development
manual manual
custom
upgrade upgrade
mod_wsgi mod_wsgi

534
doc/source/install/manual.rst
View File

@ -24,22 +24,15 @@
Storage Backend Installation Storage Backend Installation
============================ ============================
This step is a prerequisite for the collector, notification agent and API This step is a prerequisite for the collector and API services. You may use
services. You may use one of the listed database backends below to store one of the listed database backends below to store Ceilometer data.
Ceilometer data.
.. note::
Please notice, MongoDB requires pymongo_ to be installed on the system. The
required minimum version of pymongo is 2.4.
..
MongoDB MongoDB
------- -------
The recommended Ceilometer storage backend is `MongoDB`. Follow the Follow the instructions to install the MongoDB_ package for your operating
instructions to install the MongoDB_ package for your operating system, then system, then start the service. The required minimum version of MongoDB is
start the service. The required minimum version of MongoDB is 2.4. 2.4.x. You will also need to have pymongo_ 2.4 installed
To use MongoDB as the storage backend, change the 'database' section in To use MongoDB as the storage backend, change the 'database' section in
ceilometer.conf as follows:: ceilometer.conf as follows::
@ -50,13 +43,8 @@ MongoDB
SQLalchemy-supported DBs SQLalchemy-supported DBs
------------------------ ------------------------
You may alternatively use `MySQL` (or any other SQLAlchemy-supported DB You may alternatively use any SQLAlchemy-supported DB such as
like `PostgreSQL`). `PostgreSQL` or `MySQL`.
In case of SQL-based database backends, you need to create a `ceilometer`
database first and then initialise it by running::
ceilometer-dbsync
To use MySQL as the storage backend, change the 'database' section in To use MySQL as the storage backend, change the 'database' section in
ceilometer.conf as follows:: ceilometer.conf as follows::
@ -74,7 +62,7 @@ HBase
${HBASE_HOME}/bin/hbase thrift start ${HBASE_HOME}/bin/hbase thrift start
The implementation uses `HappyBase`_, which is a wrapper library used to The implementation uses `HappyBase`_, which is a wrapper library used to
interact with HBase via Thrift protocol. You can verify the thrift interact with HBase via Thrift protocol. You can verify the Thrift
connection by running a quick test from a client:: connection by running a quick test from a client::
import happybase import happybase
@ -86,11 +74,11 @@ HBase
print conn.tables() # this returns a list of HBase tables in your HBase server print conn.tables() # this returns a list of HBase tables in your HBase server
.. note:: .. note::
HappyBase version 0.5 or greater is required. Additionally, version 0.7 HappyBase version 0.5 or greater is required. Additionally, version 0.7
is not currently supported. is not currently supported.
..
In case of HBase, the needed database tables (`project`, `user`, `resource`, In the case of HBase, the required database tables (`project`, `user`, `resource`,
`meter`) should be created manually with `f` column family for each one. `meter`) should be created manually with `f` column family for each one.
To use HBase as the storage backend, change the 'database' section in To use HBase as the storage backend, change the 'database' section in
@ -115,124 +103,58 @@ HBase
.. _pymongo: https://pypi.python.org/pypi/pymongo/ .. _pymongo: https://pypi.python.org/pypi/pymongo/
Installing the notification agent Installing the notification agent
====================================== =================================
.. index:: .. index::
double: installing; agent-notification double: installing; agent-notification
1. If you want to be able to retrieve image samples, you need to instruct 1. Clone the ceilometer git repository to the management server::
Glance to send notifications to the bus by changing ``notifier_strategy``
to ``rabbit`` in ``glance-api.conf`` and restarting the
service.
2. If you want to be able to retrieve volume samples, you need to instruct
Cinder to send notifications to the bus by changing ``notification_driver``
to ``messagingv2`` and ``control_exchange`` to ``cinder``, before restarting
the service.
3. If you want to be able to retrieve instance samples, you need to instruct
Nova to send notifications to the bus by setting these values::
# nova-compute configuration for ceilometer
instance_usage_audit=True
instance_usage_audit_period=hour
notify_on_state_change=vm_and_task_state
notification_driver=messagingv2
4. In order to retrieve object store statistics, ceilometer needs
access to swift with ``ResellerAdmin`` role. You should give this
role to your ``os_username`` user for tenant ``os_tenant_name``:
::
$ keystone role-create --name=ResellerAdmin
+----------+----------------------------------+
| Property | Value |
+----------+----------------------------------+
| id | 462fa46c13fd4798a95a3bfbe27b5e54 |
| name | ResellerAdmin |
+----------+----------------------------------+
$ keystone user-role-add --tenant_id $SERVICE_TENANT \
--user_id $CEILOMETER_USER \
--role_id 462fa46c13fd4798a95a3bfbe27b5e54
You'll also need to add the Ceilometer middleware to Swift to account for
incoming and outgoing traffic, by adding these lines to
``/etc/swift/proxy-server.conf``::
[filter:ceilometer]
use = egg:ceilometer#swift
And adding ``ceilometer`` in the ``pipeline`` of that same file, right
before ``proxy-server``.
Additionally, if you want to store extra metadata from headers, you need
to set ``metadata_headers`` so it would look like::
[filter:ceilometer]
use = egg:ceilometer#swift
metadata_headers = X-FOO, X-BAR
.. note::
Please make sure that ceilometer's logging directory (if it's configured)
is read and write accessible for the user swift is started by.
5. Clone the ceilometer git repository to the management server::
$ cd /opt/stack $ cd /opt/stack
$ git clone https://git.openstack.org/openstack/ceilometer.git $ git clone https://git.openstack.org/openstack/ceilometer.git
6. As a user with ``root`` permissions or ``sudo`` privileges, run the 2. As a user with ``root`` permissions or ``sudo`` privileges, run the
ceilometer installer:: ceilometer installer::
$ cd ceilometer $ cd ceilometer
$ sudo python setup.py install $ sudo python setup.py install
7. Copy the sample configuration files from the source tree 3. Copy the sample configuration files from the source tree
to their final location. to their final location::
:: $ mkdir -p /etc/ceilometer
$ cp etc/ceilometer/*.json /etc/ceilometer
$ cp etc/ceilometer/*.yaml /etc/ceilometer
$ cp etc/ceilometer/ceilometer.conf.sample /etc/ceilometer/ceilometer.conf
$ mkdir -p /etc/ceilometer 4. Edit ``/etc/ceilometer/ceilometer.conf``
$ cp etc/ceilometer/*.json /etc/ceilometer
$ cp etc/ceilometer/*.yaml /etc/ceilometer
$ cp etc/ceilometer/ceilometer.conf.sample /etc/ceilometer/ceilometer.conf
8. Edit ``/etc/ceilometer/ceilometer.conf`` 1. Configure messaging::
1. Configure messaging [oslo_messaging_notifications]
topics = notifications
Set the messaging related options correctly so ceilometer's daemons can [oslo_messaging_rabbit]
communicate with each other and receive notifications from the other rabbit_userid = stackrabbit
projects. rabbit_password = openstack1
rabbit_hosts = 10.0.2.15
In particular, look for the ``*_control_exchange`` options and
make sure the names are correct. If you did not change the
``control_exchange`` settings for the other components, the
defaults should be correct.
.. note::
Ceilometer makes extensive use of the messaging bus, but has
not yet been tested with ZeroMQ. We recommend using Rabbit
for now.
2. Set the ``telemetry_secret`` value. 2. Set the ``telemetry_secret`` value.
Set the ``telemetry_secret`` value to a large, random, value. Use Set the ``telemetry_secret`` value to a large, random, value. Use
the same value in all ceilometer configuration files, on all the same value in all ceilometer configuration files, on all
nodes, so that messages passing between the nodes can be nodes, so that messages passing between the nodes can be
validated. validated. This value can be left empty to disable message signing.
.. note::
Disabling signing will improve message handling performance
Refer to :doc:`/configuration` for details about any other options Refer to :doc:`/configuration` for details about any other options
you might want to modify before starting the service. you might want to modify before starting the service.
9. Start the notification daemon. 5. Start the notification daemon::
::
$ ceilometer-agent-notification $ ceilometer-agent-notification
@ -264,47 +186,31 @@ Installing the collector
$ sudo python setup.py install $ sudo python setup.py install
3. Copy the sample configuration files from the source tree 3. Copy the sample configuration files from the source tree
to their final location. to their final location::
:: $ mkdir -p /etc/ceilometer
$ cp etc/ceilometer/*.json /etc/ceilometer
$ mkdir -p /etc/ceilometer $ cp etc/ceilometer/*.yaml /etc/ceilometer
$ cp etc/ceilometer/*.json /etc/ceilometer $ cp etc/ceilometer/ceilometer.conf.sample /etc/ceilometer/ceilometer.conf
$ cp etc/ceilometer/*.yaml /etc/ceilometer
$ cp etc/ceilometer/ceilometer.conf.sample /etc/ceilometer/ceilometer.conf
4. Edit ``/etc/ceilometer/ceilometer.conf`` 4. Edit ``/etc/ceilometer/ceilometer.conf``
1. Configure messaging 1. Configure messaging::
Set the messaging related options correctly so ceilometer's daemons can [oslo_messaging_notifications]
communicate with each other and receive notifications from the other topics = notifications
projects.
In particular, look for the ``*_control_exchange`` options and [oslo_messaging_rabbit]
make sure the names are correct. If you did not change the rabbit_userid = stackrabbit
``control_exchange`` settings for the other components, the rabbit_password = openstack1
defaults should be correct. rabbit_hosts = 10.0.2.15
.. note:: 2. Set the ``telemetry_secret`` value (if enabled for notification agent)
Ceilometer makes extensive use of the messaging bus, but has
not yet been tested with ZeroMQ. We recommend using Rabbit
for now.
2. Set the ``telemetry_secret`` value.
Set the ``telemetry_secret`` value to a large, random, value. Use
the same value in all ceilometer configuration files, on all
nodes, so that messages passing between the nodes can be
validated.
Refer to :doc:`/configuration` for details about any other options Refer to :doc:`/configuration` for details about any other options
you might want to modify before starting the service. you might want to modify before starting the service.
5. Start the collector. 5. Start the collector::
::
$ ceilometer-collector $ ceilometer-collector
@ -339,41 +245,46 @@ Installing the Polling Agent
$ sudo python setup.py install $ sudo python setup.py install
3. Copy the sample configuration files from the source tree 3. Copy the sample configuration files from the source tree
to their final location. to their final location::
$ mkdir -p /etc/ceilometer
$ cp etc/ceilometer/*.json /etc/ceilometer
$ cp etc/ceilometer/*.yaml /etc/ceilometer
$ cp etc/ceilometer/ceilometer.conf.sample /etc/ceilometer/ceilometer.conf
4. Configure messaging by editing ``/etc/ceilometer/ceilometer.conf``::
[oslo_messaging_notifications]
topics = notifications
[oslo_messaging_rabbit]
rabbit_userid = stackrabbit
rabbit_password = openstack1
rabbit_hosts = 10.0.2.15
5. In order to retrieve object store statistics, ceilometer needs
access to swift with ``ResellerAdmin`` role. You should give this
role to your ``os_username`` user for tenant ``os_tenant_name``:
:: ::
$ mkdir -p /etc/ceilometer $ keystone role-create --name=ResellerAdmin
$ cp etc/ceilometer/*.json /etc/ceilometer +----------+----------------------------------+
$ cp etc/ceilometer/*.yaml /etc/ceilometer | Property | Value |
$ cp etc/ceilometer/ceilometer.conf.sample /etc/ceilometer/ceilometer.conf +----------+----------------------------------+
| id | 462fa46c13fd4798a95a3bfbe27b5e54 |
| name | ResellerAdmin |
+----------+----------------------------------+
4. Edit ``/etc/ceilometer/ceilometer.conf`` $ keystone user-role-add --tenant_id $SERVICE_TENANT \
Set the messaging related options correctly so ceilometer's daemons can --user_id $CEILOMETER_USER \
communicate with each other and receive notifications from the other --role_id 462fa46c13fd4798a95a3bfbe27b5e54
projects.
In particular, look for the ``*_control_exchange`` options and 6. Start the agent::
make sure the names are correct. If you did not change the
``control_exchange`` settings for the other components, the
defaults should be correct.
.. note:: $ ceilometer-polling
Ceilometer makes extensive use of the messaging bus, but has 7. By default, the polling agent polls the `compute` and `central` namespaces.
not yet been tested with ZeroMQ. We recommend using Rabbit
for now.
Refer to :doc:`/configuration` for details about any other options
you might want to modify before starting the service.
5. Start the agent
::
$ ceilometer-polling
6. By default, the polling agent polls the `compute` and `central` namespaces.
You can specify which namespace to poll in the `ceilometer.conf` You can specify which namespace to poll in the `ceilometer.conf`
configuration file or on the command line:: configuration file or on the command line::
@ -387,8 +298,10 @@ Installing the API Server
double: installing; API double: installing; API
.. note:: .. note::
The API server needs to be able to talk to keystone and ceilometer's The API server needs to be able to talk to keystone and ceilometer's
database. database. It is only required if you choose to store data in legacy
database or if you inject new samples via REST API.
1. Clone the ceilometer git repository to the server:: 1. Clone the ceilometer git repository to the server::
@ -402,46 +315,46 @@ Installing the API Server
$ sudo python setup.py install $ sudo python setup.py install
3. Copy the sample configuration files from the source tree 3. Copy the sample configuration files from the source tree
to their final location. to their final location::
:: $ mkdir -p /etc/ceilometer
$ cp etc/ceilometer/api_paste.ini /etc/ceilometer
$ cp etc/ceilometer/*.json /etc/ceilometer
$ cp etc/ceilometer/*.yaml /etc/ceilometer
$ cp etc/ceilometer/ceilometer.conf.sample /etc/ceilometer/ceilometer.conf
$ mkdir -p /etc/ceilometer 4. Configure messaging by editing ``/etc/ceilometer/ceilometer.conf``::
$ cp etc/ceilometer/api_paste.ini /etc/ceilometer
$ cp etc/ceilometer/*.json /etc/ceilometer
$ cp etc/ceilometer/*.yaml /etc/ceilometer
$ cp etc/ceilometer/ceilometer.conf.sample /etc/ceilometer/ceilometer.conf
4. Edit ``/etc/ceilometer/ceilometer.conf`` [oslo_messaging_notifications]
topics = notifications
1. Configure messaging [oslo_messaging_rabbit]
rabbit_userid = stackrabbit
rabbit_password = openstack1
rabbit_hosts = 10.0.2.15
Set the messaging related options correctly so ceilometer's daemons can 5. Create a service for ceilometer in keystone::
communicate with each other and receive notifications from the other
projects.
In particular, look for the ``*_control_exchange`` options and $ keystone service-create --name=ceilometer \
make sure the names are correct. If you did not change the --type=metering \
``control_exchange`` settings for the other components, the --description="Ceilometer Service"
defaults should be correct.
.. note:: 6. Create an endpoint in keystone for ceilometer::
Ceilometer makes extensive use of the messaging bus, but has $ keystone endpoint-create --region RegionOne \
not yet been tested with ZeroMQ. We recommend using Rabbit --service_id $CEILOMETER_SERVICE \
for now. --publicurl "http://$SERVICE_HOST:8777/" \
--adminurl "http://$SERVICE_HOST:8777/" \
--internalurl "http://$SERVICE_HOST:8777/"
Refer to :doc:`/configuration` for details about any other options .. note::
you might want to modify before starting the service.
5. (Optional) As of the Juno release, Ceilometer utilises Paste Deploy to CEILOMETER_SERVICE is the id of the service created by the first command
manage WSGI applications. Ceilometer uses keystonemiddleware by default but and SERVICE_HOST is the host where the Ceilometer API is running. The
additional middleware and applications can be configured in api_paste.ini. default port value for ceilometer API is 8777. If the port value
For examples on how to use Paste Deploy, refer to this documentation_. has been customized, adjust accordingly.
.. _documentation: http://pythonpaste.org/deploy/ 7. Choose and start the API server.
6. Choose and start the API server.
Ceilometer includes the ``ceilometer-api`` command. This can be Ceilometer includes the ``ceilometer-api`` command. This can be
used to run the API server. For smaller or proof-of-concept used to run the API server. For smaller or proof-of-concept
@ -463,196 +376,79 @@ Installing the API Server
maintaining a long-running program in the background. maintaining a long-running program in the background.
Configuring keystone to work with API Enabling Service Notifications
===================================== ==============================
.. index:: Cinder
double: installing; configure keystone ------
.. note:: Edit ``cinder.conf`` to include::
The API server needs to be able to talk to keystone to authenticate.
1. Create a service for ceilometer in keystone [oslo_messaging_notifications]
driver = messagingv2
:: Glance
------
$ keystone service-create --name=ceilometer \ Edit ``glance.conf`` to include::
--type=metering \
--description="Ceilometer Service"
2. Create an endpoint in keystone for ceilometer [oslo_messaging_notifications]
driver = messagingv2
:: Heat
----
$ keystone endpoint-create --region RegionOne \ Configure the driver in ``heat.conf``::
--service_id $CEILOMETER_SERVICE \
--publicurl "http://$SERVICE_HOST:8777/" \
--adminurl "http://$SERVICE_HOST:8777/" \
--internalurl "http://$SERVICE_HOST:8777/"
.. note:: [oslo_messaging_notifications]
driver=messagingv2
CEILOMETER_SERVICE is the id of the service created by the first command Nova
and SERVICE_HOST is the host where the Ceilometer API is running. The ----
default port value for ceilometer API is 8777. If the port value
has been customized, adjust accordingly. Edit ``nova.conf`` to include::
[DEFAULT]
instance_usage_audit=True
instance_usage_audit_period=hour
notify_on_state_change=vm_and_task_state
[oslo_messaging_notifications]
driver=messagingv2
Configuring Heat to send notifications Sahara
====================================== ------
Configure the driver in ``heat.conf`` Configure the driver in ``sahara.conf``::
:: [DEFAULT]
enable_notifications=true
notification_driver=messagingv2 [oslo_messaging_notifications]
driver=messagingv2
Configuring Sahara to send notifications Swift
======================================== -----
Configure the driver in ``sahara.conf`` Edit ``proxy-server.conf`` to include::
:: [filter:ceilometer]
topic = notifications
driver = messaging
url = rabbit://stackrabbit:openstack1@10.0.2.15:5672/
control_exchange = swift
paste.filter_factory = ceilometermiddleware.swift:filter_factory
set log_level = WARN
enable_notifications=true and edit [pipeline:main] to include the ceilometer middleware before the application::
notification_driver=messagingv2
Also you need to configure messaging related options correctly as written above [pipeline:main]
pipeline = catch_errors ... ... ceilometer proxy-server
Also, you need to configure messaging related options correctly as written above
for other parts of installation guide. Refer to :doc:`/configuration` for for other parts of installation guide. Refer to :doc:`/configuration` for
details about any other options you might want to modify before starting the details about any other options you might want to modify before starting the
service. service.
Notifications queues
====================
.. index::
double: installing; notifications queues; multiple topics
By default, Ceilometer consumes notifications on the messaging bus sent to
**notification_topics** by using a queue/pool name that is identical to the
topic name. You shouldn't have different applications consuming messages from
this queue. If you want to also consume the topic notifications with a system
other than Ceilometer, you should configure a separate queue that listens for
the same messages.
Ceilometer allows multiple topics to be configured so that polling agent can
send the same messages of notifications to other queues. Notification agents
also use **notification_topics** to configure which queue to listen for. If
you use multiple topics, you should configure notification agent and polling
agent separately, otherwise Ceilometer collects duplicate samples.
By default, the ceilometer.conf file is as follows::
[DEFAULT]
notification_topics = notifications
To use multiple topics, you should give ceilometer-agent-notification and
ceilometer-polling services different ceilometer.conf files. The Ceilometer
configuration file ceilometer.conf is normally locate in the /etc/ceilometer
directory. Make changes according to your requirements which may look like
the following::
For notification agent using ceilometer-notification.conf, settings like::
[DEFAULT]
notification_topics = notifications,xxx
For polling agent using ceilometer-polling.conf, settings like::
[DEFAULT]
notification_topics = notifications,foo
.. note::
notification_topics in ceilometer-notification.conf should only have one same
topic in ceilometer-polling.conf
Doing this, it's easy to listen/receive data from multiple internal and external services.
Using multiple dispatchers
==========================
.. index::
double: installing; multiple dispatchers
The Ceilometer collector allows multiple dispatchers to be configured so that
data can be easily sent to multiple internal and external systems. Dispatchers
are divided between ``event_dispatchers`` and ``meter_dispatchers`` which can
each be provided with their own set of receiving systems.
.. note::
In Liberty and prior the configuration option for all data was
``dispatcher`` but this was changed for the Mitaka release to break out
separate destination systems by type of data.
By default, Ceilometer only saves event and meter data in a database. If you
want Ceilometer to send data to other systems, instead of or in addition to
the Ceilometer database, multiple dispatchers can be enabled by modifying the
Ceilometer configuration file.
Ceilometer ships multiple dispatchers currently. They are ``database``,
``file``, ``http`` and ``gnocchi`` dispatcher. As the names imply, database
dispatcher sends metering data to a database, file dispatcher logs meters into
a file, http dispatcher posts the meters onto a http target, gnocchi
dispatcher posts the meters onto Gnocchi_ backend. Each dispatcher can have
its own configuration parameters. Please see available configuration
parameters at the beginning of each dispatcher file.
.. _Gnocchi: http://gnocchi.readthedocs.org/en/latest/basic.html
To check if any of the dispatchers is available in your system, you can
inspect the Ceilometer egg entry_points.txt file, you should normally see text
like the following::
[ceilometer.dispatcher]
database = ceilometer.dispatcher.database:DatabaseDispatcher
file = ceilometer.dispatcher.file:FileDispatcher
http = ceilometer.dispatcher.http:HttpDispatcher
gnocchi = ceilometer.dispatcher.gnocchi:GnocchiDispatcher
To configure one or multiple dispatchers for Ceilometer, find the Ceilometer
configuration file ceilometer.conf which is normally located at /etc/ceilometer
directory and make changes accordingly. Your configuration file can be in a
different directory.
To use multiple dispatchers on a Ceilometer collector service, add multiple
dispatcher lines in ceilometer.conf file like the following::
[DEFAULT]
meter_dispatchers=database
meter_dispatchers=file
If there is no dispatcher present, database dispatcher is used as the
default. If in some cases such as traffic tests, no dispatcher is needed,
one can configure the line without a dispatcher, like the following::
event_dispatchers=
With the above configuration, no event dispatcher is used by the Ceilometer
collector service, all event data received by Ceilometer collector will be
dropped.
For Gnocchi dispatcher, the following configuration settings should be added::
[DEFAULT]
meter_dispatchers = gnocchi
[dispatcher_gnocchi]
archive_policy = low
The value specified for ``archive_policy`` should correspond to the name of an
``archive_policy`` configured within Gnocchi.
For Gnocchi dispatcher backed by Swift storage, the following additional
configuration settings should be added::
[dispatcher_gnocchi]
filter_project = gnocchi_swift
filter_service_activity = True
.. note::
If gnocchi dispatcher is enabled, Ceilometer api calls will return a 410 with
an empty result. The Gnocchi Api should be used instead to access the data.