Documented Stevedore usage and source details

Updated architecture document to mention Stevedore
and make a correct statement about polling frequency.
Updated configuration document to reference the relevant
section of the architecture document.
Documented the name parameter of the source stanzas in pipeline.yaml.
Documented the behavior when multiple source stanzas match one plugin.

Change-Id: I0d09f2bd8943425cd250574df41e77a68bdcf55e

doc/source/architecture.rst

@@ -273,6 +273,8 @@ Detailed Description
    as their communication via the messaging bus. More work is needed
    before the data store and API server designs can be documented.
 
+.. _plugins-and-containers:
+
 Plugins
 -------
 
@@ -287,10 +289,14 @@ measure the resources their customers use. This means that Ceilometer
 needs to be easy to extend and configure so it can be tuned for each
 installation. A plugin system based on `setuptools entry points`_
 makes it easy to add new monitors in the collector or subagents for
-polling.
+polling.  In particular, Ceilometer now uses Stevedore_, and you
+should put your entry point definitions in the ``entry_points.txt``
+file of your Ceilometer egg.
 
 .. _setuptools entry points: http://pythonhosted.org/setuptools/setuptools.html#dynamic-discovery-of-services-and-plugins
 
+.. _Stevedore: http://stevedore.readthedocs.org
+
 Each daemon provides basic essential services in a framework to be
 shared by the plugins, and the plugins do the specialized work.  As a
 general rule, the plugins are asked to do as little work as
@@ -351,8 +357,8 @@ The pollster plugins do not communicate with the message bus directly,
 unless it is necessary to do so in order to collect the information
 for which they are polling.
 
-All polling happens with the same frequency, controlled by a global
-setting for the agent.
+The frequency of polling is controlled via the pipeline configuration.
+See :ref:`Pipeline-Configuration` for details.
 
 Handling Notifications
 ----------------------

doc/source/configuration.rst

@@ -280,6 +280,7 @@ configuration file by running ``tox -e genconfig``.
 
 .. _`backward compatibility issue`: https://bitbucket.org/hpk42/tox/issue/150/posargs-configerror
 
+.. _Pipeline-Configuration:
 
 Pipelines
 =========
@@ -290,6 +291,8 @@ data.
 
 A source is a producer of samples, in effect a set of pollsters and/or
 notification handlers emitting samples for a set of matching meters.
+See :doc:`contributing/plugins` and :ref:`plugins-and-containers` for
+details on how to write and plug in your plugins.
 
 Each source configuration encapsulates meter name matching, polling
 interval determination, optional resource enumeration or discovery,
@@ -311,6 +314,7 @@ to persist the data into storage through the message bus or to send it to one
 or more external consumers. One chain can contain multiple publishers, see the
 :ref:`multi-publisher` section.
 
+
 Pipeline configuration
 ----------------------
 
@@ -337,6 +341,10 @@ The chain definition looks like the following::
         publishers:
           - 'list of publishers'
 
+The *name* parameter of a source is unrelated to anything else;
+nothing references a source by name, and a source's name does not have
+to match anything.
+
 The *interval* parameter in the sources section should be defined in seconds. It
 determines the cadence of sample injection into the pipeline, where samples are
 produced under the direct control of an agent, i.e. via a polling cycle as opposed
@@ -368,6 +376,11 @@ The above definition methods can be used in the following combinations:
     pipeline. Wildcard and included meters cannot co-exist in the same
     pipeline definition section.
 
+A given polling plugin is invoked according to each source section
+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
 statically configured resources for a set of pipeline sources with a