From 92c151ba6b8510703c2605cd657da996bc8af814 Mon Sep 17 00:00:00 2001 From: Mike Spreitzer Date: Tue, 5 Aug 2014 00:36:00 -0400 Subject: [PATCH] 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 | 12 +++++++++--- doc/source/configuration.rst | 13 +++++++++++++ 2 files changed, 22 insertions(+), 3 deletions(-) diff --git a/doc/source/architecture.rst b/doc/source/architecture.rst index 7e32679e1..f666251aa 100644 --- a/doc/source/architecture.rst +++ b/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 ---------------------- diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index d23fb6887..ab0a4c7c2 100644 --- a/doc/source/configuration.rst +++ b/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