Merge "User/developer doc for event dispatchers"

doc/source/developer/event_dispatcher.rst

@@ -0,0 +1,126 @@
+..
+  Licensed under the Apache License, Version 2.0 (the "License"); you may
+  not use this file except in compliance with the License. You may obtain
+  a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+  WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+  License for the specific language governing permissions and limitations
+  under the License.
+
+
+=================
+Event Dispatchers
+=================
+
+An event :term:`dispatcher` is a processor that converts a given action in
+Senlin engine into certain format and then persists it into some storage or
+sends it to downsteam processing software.
+
+Since version 3.0.0, Senlin comes with some built-in dispatchers that can
+dump event records into database and/or send event notifications via the
+default message queue. The former is referred to as the ``database`` dispatcher
+which is enabled by default; the latter is referred to as the ``message``
+dispatcher which has to be manually enabled by adding the following line to
+the ``senlin.conf`` file::
+
+  dispatchers = message
+
+However, the distributors or the users can always add their own event
+dispatchers easily when needed.
+
+Event dispatchers are managed as Senlin plugins. Once a new event dispatcher
+is implemented, a deployer can enable it by first adding a new item to the
+``senlin.dispatchers`` entries in the ``entry_points`` section of the
+``setup.cfg`` file, followed by a reinstall of the Senlin service, i.e.
+``sudo pip install`` command.
+
+
+The Base Class ``EventBackend``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+All event dispatchers are expected to subclass the base class ``EventBackend``
+in the ``senlin.events.base`` module. The only requirement for a dispatcher
+subclass is to override the ``dump()`` method that implments the processing
+logic.
+
+
+Providing New Dispatchers
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Developing A New Event Dispatcher
+---------------------------------
+
+The first step for adding a new dispatcher is to create a new file containing
+a subclass of ``EventBackend``. In this new class, say ``JsonDispatcher``,
+you will need to implement the ``dump()`` class method as examplified below::
+
+.. code:: python
+
+  class JsonDispatcher(base.EventBackend):
+      """Dispatcher for dumping events to a JSON file."""
+
+      @classmethod
+      def dump(cls, level, action, **kwargs):
+          # Your logic goes here
+          ...
+
+The ``level`` parameter for the method is identical to that defined by the
+``logging`` module of Python. It is an integer representing the criticality
+of an event. The ``action`` parameter is an instance of Senlin action class,
+which is defined in the ``senlin.engine.actions.base`` module. There is
+virtually no constraints on which properties you will pick and how you want to
+process them.
+
+Finally, the ``**kwargs`` parameter may provide some useful fields for you
+to use::
+
+* ``timestamp``: A datetime value that indicates when the event was generated.
+* ``phase``: A string value indicating the phase an action is in. Most of the
+  time this can be safely ignored.
+* ``reason``: There are some rare cases where an event comes with a textual
+  description. Most of the time, this is empty.
+* ``extra``: There are even rarer cases where an event comes with some
+  additional fields for attention. This can be safely ignored most of the
+  time.
+
+
+Registering the New Dispatcher
+------------------------------
+
+For Senlin service to be aware of and thus to make use of the new dispatcher,
+you will register it to the Senlin engine service. This is done by editing the
+``setup.cfg`` file in the root directory of the code base, for example:
+
+::
+
+  [entry_points]
+  senlin.dispatchers =
+      database = senlin.events.database:DBEvent
+      message = senlin.events.message:MessageEvent
+      jsonfile = <path to the dispatcher module>:<dispatch class name>
+
+Finally, save that file and do a reinstall of the Senlin service, followed
+by a restart of the ``senlin-engine`` process.
+
+::
+
+  $ sudo pip install -e .
+
+
+Dynamically Enabling/Disabling a Dispatcher
+-------------------------------------------
+
+All dispatchers are loaded when the Senlin engine is started, however, they
+can be dynamically enabled or disabled by editing the ``senlin.conf`` file.
+The option ``dispatchers`` in the ``[DEFAULT]`` section is a multi-string
+value option for this purpose. To enable your dispatcher (i.e. ``jsonfile``),
+you will need to add the following line to the ``senlin.conf`` file:
+
+::
+
+  dispatchers = jsonfile
+

doc/source/developer/plugin_guide.rst

@@ -26,3 +26,4 @@ describe how to develop and plug your own profile types and/or policy types.
 
    policy_type
    profile_type
+   event_dispatcher

doc/source/glossary.rst

@@ -43,6 +43,11 @@ This section contains the glossary for the Senlin service.
      The :term:`Action` objects are stored into database for execution. These
      actions may have dependencies among them.
 
+   Dispatcher
+     A dispatcher is a processor that takes a Senlin :term:`Action` as input
+     and then converts it into a desired format for storage or further
+     processing.
+
    Driver
      A driver is a Senlin internal module that enables Senlin :term:`Engine` to
      interact with other :term:`OpenStack` services. The interactions here are

doc/source/user/events.rst

@@ -42,6 +42,29 @@ level value of the event:
   serious problems encountered by the engine. The engine service may have
   run into some bugs. User intervention is required to do a recovery.
 
+Senlin provides an open architecture for event dispatching. Two of the
+built-in dispatchers are ``database`` and ``message``. The ``database``
+dispatcher dumps the events into database tables and it is enabled by default.
+The ``message`` dispatcher converts the event objects into versioned event
+notifications and published on the global message queue. This dispatcher is
+by default disabled. To enable it, you can add the following line to the
+Senlin configuration file and then restart the senlin engine::
+
+ dispatchers = message
+
+Note that unprocessed event notifications which are not associated with a
+TTL (time to live) value by default will remain queued at the message bus,
+please make sure the Senlin event notifications will be subscribed and
+processed by some services before enabling the ``message`` dispatcher.
+
+Since the event dispatchers are designed as plug-ins, you can develop your own
+event dispatchers and have senlin engine load them on startup. For more
+details on developing and plugging in your own event dispatchers, please refer
+to the :doc:`../developer/plugin_guide` document.
+
+The following sections are about examining events when using the ``database``
+dispatcher which creates database records when events happen.
+
 
 Listing Events
 ~~~~~~~~~~~~~~