Merge "Docs: Add description of pipeline discovery section"

2 files changed, 30 insertions, 5 deletions

diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst
index f666251a..aaa9f094 100644
--- a/doc/source/architecture.rst
+++ b/doc/source/architecture.rst
@@ -349,9 +349,10 @@ agent daemon is configured to run one or more *pollster* plugins using
 the ``ceilometer.poll.central`` namespace.
 
 The agents periodically asks each pollster for instances of
-``Counter`` objects. The agent framework converts the Counters to
-metering messages, which it then signs and transmits on the metering
-message bus.
+``Sample`` objects. The agent framework then publishes the Samples using
+the publishers defined in the pipeline configuration. For example,
+the ``rpc`` publisher converts the Sample to metering messages, which it
+then signs and transmits on the metering message bus.
 
 The pollster plugins do not communicate with the message bus directly,
 unless it is necessary to do so in order to collect the information
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index 736adb1f..bdcef7b9 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -391,6 +391,8 @@ The chain definition looks like the following::
           - 'meter filter'
         resources:
           - 'list of resource URLs'
+        discovery:
+          - 'list of discoverers'
         sinks
           - 'sink name'
     sinks:
@@ -439,11 +441,33 @@ whose *meters* parameter matches the plugin's meter name.  That is,
 the matching source sections are combined by union, not intersection,
 of the prescribed time series.
 
-The optional *resources* section of a pipeline source allows a static
-list of resource URLs to be to be configured. An amalgamated list of all
+The optional *resources* section of a pipeline source allows a list of
+static resource URLs to be configured. An amalgamated list of all
 statically configured resources for a set of pipeline sources with a
 common interval is passed to individual pollsters matching those pipelines.
 
+The optional *discovery* section of a pipeline source contains the list of
+discoverers. These discoverers can be used to dynamically discover the
+resources to be polled by the pollsters defined in this pipeline. The name
+of the discoverers should be the same as the related names of plugins in
+setup.cfg.
+
+If *resources* or *discovery* section is not set, the default value would
+be an empty list. If both *resources* and *discovery* are set, the final
+resources passed to the pollsters will be the combination of the dynamic
+resources returned by the discoverers and the static resources defined
+in the *resources* section. If there are some duplications between the
+resources returned by the discoverers and those defined in the *resources*
+section, the duplication will be removed before passing those resources
+to the pollsters.
+
+There are three ways a pollster can get a list of resources to poll, as the
+following in descending order of precedence:
+
+    1. From the per-pipeline configured discovery and/or static resources.
+    2. From the per-pollster default discovery.
+    3. From the per-agent default discovery.
+
 The *transformers* section of a pipeline sink provides the possibility to add a
 list of transformer definitions. The names of the transformers should be the same
 as the names of the related extensions in setup.cfg. For a more detailed