Merge "re-org existing manually install notes"

doc/source/install/custom.rst

@@ -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.

doc/source/install/dbreco.rst

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

doc/source/install/index.rst

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