Fix docs to suit merged compute/central agents concept

DocImpact: Fix agents-related docs to describe polling agent
Related-Blueprint: merge-compute-central-agents

Change-Id: If377ac49bf75c0698f4af6be021e8354240f4e42

doc/source/architecture.rst

@@ -94,8 +94,7 @@ Each of Ceilometer's services are designed to scale horizontally. Additional
 workers and nodes can added depending on the expected load. Ceilometer offers
 five core services:
 
-1. polling agents - compute and central agent daemons designed to poll
+1. polling agent - daemon designed to poll OpenStack services.
-   OpenStack services.
 2. notification agent - daemon designed to listen to message queue.
 3. collector - daemon designed to gather and record event and metering data
    created by notification and polling agents.
@@ -133,14 +132,17 @@ methods to collect data:
    prefer this compared to a polling agent method as resilience (high
    availability) will not be a problem with this method.
 3. :term:`Polling agents` which is the least preferred method, that will poll
-   some API or other tool to collect information at a regular interval. 
+   some API or other tool to collect information at a regular interval.
    This method is least preferred due to the inherent difficulty in making such
    a component resilient.
 
 The first method is supported by the ceilometer-notification agent, which
 monitors the message queues for notifications and for metering data coming
-from the "push" agents. Methods 2 and 3 rely on the ceilometer-compute-agent
+from the "push" agents. Methods 2 and 3 rely on the ceilometer-polling agent,
-and ceilometer-central-agent respectively.
+which behaves differently depending on the resources it's collecting data
+about. Polling agent can be configured either to poll local hypervisor or
+remote APIs (public REST APIs exposed by services and/or host-level SNMP
+daemons).
 
 How to access collected data?
 -----------------------------
@@ -366,16 +368,15 @@ Polling
 
 Metering data comes from two sources: through notifications built into
 the existing OpenStack components and by polling the infrastructure
-(such as via libvirt). Polling for compute resources is handled by an
+(such as via libvirt). Polling for compute resources is handled by a
-agent running on the compute node (where communication with the
+polling agent running on the compute node (where communication with the
-hypervisor is more efficient).  The compute agent daemon is configured
+hypervisor is more efficient). Polling for resources not tied
-to run one or more *pollster* plugins using the
+to the compute node is handled by the agent running on the cloud
-``ceilometer.poll.compute`` namespace.  Polling for resources not tied
+controller node via services APIs. The polling agent daemon is configured
-to the compute node is handled by the central agent.  The central
+to run one or more *pollster* plugins using either the
-agent daemon is configured to run one or more *pollster* plugins using
+``ceilometer.poll.compute`` and/or ``ceilometer.poll.central`` namespaces.
-the ``ceilometer.poll.central`` namespace.
 
-The agents periodically asks each pollster for instances of
+The agents periodically ask each pollster for instances of
 ``Sample`` objects. The agent framework then publishes the Samples using
 the publishers defined in the pipeline configuration. For example,
 the ``notifier`` publisher converts the Sample to metering messages, which it

doc/source/contributing/plugins.rst

@@ -24,34 +24,41 @@ has not yet been covered by an existing plugin.
 Agents
 ======
 
-The compute agent runs on each compute node to poll for resource
+Polling agent might be run either on central cloud management nodes or on the
+compute nodes (where direct hypervisor polling is quite logical).
+
+The agent running on each compute node polls for compute resources
 usage. Each metric collected is tagged with the resource ID (such as
 an instance) and the owner, including tenant and user IDs. The metrics
 are then reported to the collector via the message bus. More detailed
 information follows.
 
-The compute agent is implemented in ``ceilometer/compute/manager.py``. As
+The agent running on the cloud central management node polls other types of
-you will see in the manager, the computeagent loads all plugins defined in
+resources from a management server (usually using OpenStack services API to
-the namespace ``ceilometer.poll.compute``, then periodically calls their
+collect this data).
-:func:`get_samples` method.
 
-The central agent polls other types of resources from a management server.
+The polling agent is implemented in ``ceilometer/agent/manager.py``. As
-The central agent is defined in ``ceilometer/central/manager.py``. It loads
+you will see in the manager, the agent loads all plugins defined in
-plugins from the ``ceilometer.poll.central`` namespace and polls them by
+the namespace ``ceilometer.poll.agent``, then periodically calls their
-calling their :func:`get_samples` method.
+:func:`get_samples` method.
 
 Plugins
 =======
 
-An agent can support multiple plugins to retrieve different
+A polling agent can support multiple plugins to retrieve different
 information and send them to the collector. As stated above, an agent
-will automatically activate all plugins of a given class. For example,
+will automatically activate all possible plugins if no additional information
-the compute agent will load all plugins of class
+about what to poll was passed. Previously we had separated compute and
-``ceilometer.poll.compute``.  This will load, among others, the
+central agents with different namespaces with plugins (pollsters) defined
-:class:`ceilometer.compute.pollsters.CPUPollster`, which is defined in
+within. Currently we keep separated namespaces - ``ceilometer.poll.compute``
-the file ``ceilometer/compute/pollsters.py`` as well as the
+and ``ceilometer.poll.central`` for quick separation of what to poll depending
-:class:`ceilometer.compute.notifications.InstanceNotifications` plugin
+on where is polling agent running.  This will load, among others, the
-which is defined in the file ``ceilometer/compute/notifications.py``
+:class:`ceilometer.compute.pollsters.cpu.CPUPollster`, which is defined in
+the folder ``ceilometer/compute/pollsters``.
+
+Notifications mechanism uses plugins as well, for instance
+:class:`ceilometer.compute.notifications.instance.InstanceNotifications` plugin
+which is defined in the ``ceilometer/compute/notifications`` folder.
 
 We are using these two existing plugins as examples as the first one provides
 an example of how to interact when you need to retrieve information from an
@@ -62,24 +69,45 @@ Pollster
 --------
 
 Compute plugins are defined as subclasses of the
-:class:`ceilometer.compute.plugin.ComputePollster` class as defined in
+:class:`ceilometer.compute.BaseComputePollster` class as defined in
-the ``ceilometer/compute/plugin.py`` file. Pollsters must implement one
+the ``ceilometer/compute/__init__.py`` file. Pollsters must implement one
 method: ``get_samples(self, manager, context)``, which returns a
 sequence of ``Sample`` objects as defined in the
 ``ceilometer/sample.py`` file.
 
-In the ``CPUPollster`` plugin, the ``get_samples`` method is implemented as a loop
+In the ``CPUPollster`` plugin, the ``get_samples`` method is implemented as a
-which, for each instances running on the local host, retrieves the cpu_time
+loop which, for each instances running on the local host, retrieves the
-from the hypervisor and sends back two ``Sample`` objects.  The first one, named
+cpu_time from the hypervisor and sends back two ``Sample`` objects.  The first
-"cpu", is of type "cumulative", meaning that between two polls, its value is
+one, named "cpu", is of type "cumulative", meaning that between two polls, its
-not reset, or in other word that the cpu value is always provided as a duration
+value is not reset while the instance remains active, or in other words that
-that continuously increases since the creation of the instance. The second one,
+the CPU value is always provided as a duration that continuously increases
-named "cpu_util", is of type "gauge", meaning that its value is the percentage
+since the creation of the instance. The second one, named "cpu_util", is of
-of cpu utilization.
+type "gauge", meaning that its value is the percentage of cpu utilization.
 
 Note that the ``LOG`` method is only used as a debugging tool and does not
 participate in the actual metering activity.
 
+There is the way to specify either namespace(s) with pollsters or just
+list of concrete pollsters to use, or even both of these parameters on the
+polling agent start via CLI parameter:
+
+    ceilometer-polling --polling-namespaces central compute
+
+This command will basically make polling agent to load all plugins from the
+central and compute namespaces and poll everything it can. If you need to load
+only some of the pollsters, you can use ``pollster-list`` option:
+
+    ceilometer-polling --pollster-list image image.size storage.*
+
+If both of these options are passed, the polling agent will load only those
+pollsters specified in the pollster list, that can be loaded from the selected
+namespaces.
+
+.. note::
+
+   Agents coordination cannot be used in case of pollster-list option usage.
+   This allows to avoid both samples duplication and their lost.
+
 Notifications
 -------------
 

doc/source/glossary.rst

@@ -45,10 +45,10 @@
        A ceilometer is a device that uses a laser or other light
        source to determine the height of a cloud base.
 
-   central agent
+   polling agent
-     Software service running on a central management node within the
+     Software service running either on a central management node within the
-     OpenStack infrastructure measuring usage and sending the results
+     OpenStack infrastructure or compute node measuring usage and sending the
-     to the :term:`collector`.
+     results to the :term:`collector`.
 
    collector
      Software service running on the OpenStack infrastructure
@@ -56,11 +56,6 @@
      samples from the ceilometer agent and recording the results
      in the database.
 
-   compute agent
-     Software service running on a compute node within the OpenStack
-     infrastructure measuring usage and sending the results to the
-     :term:`collector`.
-
    notification agent
      The different OpenStack services emit several notifications about the
      various types of events. The notification agent consumes them from

doc/source/install/development.rst

@@ -18,13 +18,22 @@
  Installing and Running the Development Version
 ================================================
 
-Ceilometer has several daemons. The basic are: :term:`compute agent` runs on
+Ceilometer has several daemons. The basic are: :term:`polling agent` running
-the Nova compute node(s) while the :term:`central agent`, :term:`collector`
+either on the Nova compute node(s) or :term:`polling agent` running on the
-and :term:`notification agent` run on the cloud's management node(s).
+central management node(s), :term:`collector`
+and :term:`notification agent` running on the cloud's management node(s).
 In a development environment created by devstack_, these services are
 typically running on the same server. They do not have to be, though, so some
 of the instructions below are duplicated. Skip the steps you have already done.
 
+.. note::
+
+   In fact, previously Ceilometer had separated compute and central agents, and
+   their support is implemented in devstack_ right now, not one agent variant.
+   For now we do have deprecated cmd sripts emulating old compute/central
+   behaviour using namespaces option passed to polling agent, which will be
+   maintained for a transitional period.
+
 .. _devstack: http://www.devstack.org/
 
 Configuring Devstack