From 7a40bf4d58431f08968bf185b9a76ccc3aca763e Mon Sep 17 00:00:00 2001
From: gord chung <gord@live.ca>
Date: Fri, 2 Sep 2016 17:21:20 +0000
Subject: [PATCH] add note regarding pipeline_processing_queues option

Change-Id: I81fde04a671a39f73a315f3c600e288aa25885d9
---
 ceilometer/notification.py   |  3 ++-
 doc/source/configuration.rst | 25 +++++++++++++++++++++++++
 2 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/ceilometer/notification.py b/ceilometer/notification.py
index 960bca7f..0bc42a11 100644
--- a/ceilometer/notification.py
+++ b/ceilometer/notification.py
@@ -42,7 +42,8 @@ OPTS = [
                min=1,
                help='Number of queues to parallelize workload across. This '
                     'value should be larger than the number of active '
-                    'notification agents for optimal results.'),
+                    'notification agents for optimal results. WARNING: '
+                    'Once set, lowering this value may result in lost data.'),
     cfg.BoolOpt('ack_on_event_error',
                 default=True,
                 deprecated_group='collector',
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index 64774835..dd73d613 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -176,6 +176,31 @@ The default configuration can be found in `pipeline.yaml`_.
 
 .. _pipeline.yaml: https://git.openstack.org/cgit/openstack/ceilometer/tree/etc/ceilometer/pipeline.yaml
 
+Pipeline Processing
+-------------------
+
+On large workloads, multiple notification agents can be deployed to handle the
+flood of incoming messages from monitored services. If transformations are
+enabled in the pipeline, the notification agents must be coordinated to ensure
+related messages are routed to the same agent. To enable coordination, set the
+``workload_partitioning`` value in ``notification`` section.
+
+To distribute messages across agents, ``pipeline_processing_queues`` option
+should be set. This value defines how many pipeline queues to create which will
+then be distributed to the active notification agents. It is recommended that
+the number of processing queues, at the very least, match the number of agents.
+
+.. note::
+
+   Increasing the number of processing queues will improve the distribution
+   of messages across the agents.
+
+.. warning::
+
+   Decreasing the number of processing queues may result in lost data as any
+   previously created queues may no longer be assigned to active agents. It
+   is only recommended that you **increase** processing queues.
+
 Publishers
 ++++++++++