diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index 0cc4926bc8..b5b9de6d85 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -30,6 +30,71 @@ The sample configuration file for Ceilometer, named control after the Icehouse release. You can generate this sample configuration file by running ``tox -e genconfig``. + +Polling +~~~~~~~ + +Polling rules are defined by the `polling.yaml` file. It defines the pollsters +to enable and the interval they should be polled. See :doc:`plugins` for +details on how to write and plug in your plugins. + +Each source configuration encapsulates meter name matching which matches +against the entry point of pollster. It also includes: polling +interval determination, optional resource enumeration or discovery. + +All samples generated by polling are placed on the queue to be handled by +the pipeline configuration loaded in the notification agent. + +The polling definition may look like the following:: + + --- + sources: + - name: 'source name' + interval: 'how often the samples should be generated' + meters: + - 'meter filter' + resources: + - 'list of resource URLs' + discovery: + - 'list of discoverers' + +The *interval* parameter in the sources section should be defined in seconds. +It determines the cadence of sample generation. + +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. It functions the same as Pipelines_ +filtering + +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 +:file:`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. + + .. _Pipeline-Configuration: Pipelines @@ -38,13 +103,8 @@ Pipelines Pipelines describe a coupling between sources of samples and the corresponding sinks for transformation and publication of the samples. -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:`plugins` 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, -and mapping to one or more sinks for publication. +A source is a set of samples that should be passed to specified sinks. These +samples may come from polling agents or service notificaitons. A sink on the other hand is a consumer of samples, providing logic for the transformation and publication of samples emitted from related sources. @@ -77,13 +137,6 @@ The chain definition looks like the following:: --- sources: - name: 'source name' - interval: 'how often should the samples be injected into the pipeline' - meters: - - 'meter filter' - resources: - - 'list of resource URLs' - discovery: - - 'list of discoverers' sinks - 'sink name' sinks: @@ -96,11 +149,6 @@ 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 to incoming notifications. - There are several ways to define the list of meters for a pipeline source. The list of valid meters can be found in the :ref:`measurements` section. There is a possibility to define all the meters, or just included or excluded meters, @@ -127,38 +175,6 @@ 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 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 -:file:`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 :file:`setup.cfg`. For a more