Merge "User/developer doc for event dispatchers"
This commit is contained in:
commit
0ede0e10c1
126
doc/source/developer/event_dispatcher.rst
Normal file
126
doc/source/developer/event_dispatcher.rst
Normal file
@ -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
|
||||
|
@ -26,3 +26,4 @@ describe how to develop and plug your own profile types and/or policy types.
|
||||
|
||||
policy_type
|
||||
profile_type
|
||||
event_dispatcher
|
||||
|
@ -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
|
||||
|
@ -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
|
||||
~~~~~~~~~~~~~~
|
||||
|
Loading…
Reference in New Issue
Block a user