152 lines
6.2 KiB
ReStructuredText
152 lines
6.2 KiB
ReStructuredText
================================
|
|
Versioned notifications in Mogan
|
|
================================
|
|
|
|
The Mogan notifications are events related with changes of resources, and can
|
|
be consumed by internal system. Notifications are sent to these services over a
|
|
message bus by oslo.messaging's Notifier class [1]_. The notifications
|
|
consumer could be a messaging bus listener service, e.g. Ceilometer
|
|
notification agent or Searchlight Listener.
|
|
|
|
Generally, a notification message performed by a json string, which includes
|
|
two parts: a set of common info and a notification payload which is a
|
|
dictionary that including the information we want to send out. The format as
|
|
the following::
|
|
|
|
{
|
|
"priority": <string, selected from a predefined list by the sender>,
|
|
"event_type": <string, defined by the sender>,
|
|
"timestamp": <string, the isotime of when the notification emitted>,
|
|
"publisher_id": <string, defined by the sender>,
|
|
"message_id": <uuid, generated by oslo>,
|
|
"payload": <json serialized dict, defined by the sender>
|
|
}
|
|
|
|
The versioned notification is a concept that defines a base frame for general
|
|
notifications class definition. The payload is not a free form dictionary but a
|
|
serialized oslo versionedobject [2]_.
|
|
|
|
Configure to enable notification in Mogan
|
|
=========================================
|
|
|
|
To enable notification in Mogan, you need to configure the ``transport_url``
|
|
option under the ``[oslo_messaging_notifications]`` section in Mogan's
|
|
configuration file. The ``transport_url`` is the message bus connection url,
|
|
for example::
|
|
|
|
rabbit://stackrabbit:password@127.0.0.1:5672/
|
|
|
|
By default, the notifications message will be sent to the message queue named
|
|
``versioned_notification.PRIORITY``, the *PRIORITY* depends on the priority
|
|
in the notification message.
|
|
|
|
Add a new notification to Mogan
|
|
===============================
|
|
The every versioned notification in Mogan is modeled with oslo
|
|
versionedobjects. Every versioned notification class inherits from the
|
|
`mogan.notifications.objects.base.NotificationBase` which
|
|
already defines three mandatory fields of the notification `event_type`,
|
|
`publisher_id` and `priority`. The new notification class shall add a new field
|
|
`payload` with an appropriate payload type. The payload object of the
|
|
notification shall inherit from the
|
|
`mogan.notifications.objects.base.NotificationPayloadBase` class and shall
|
|
define the fields of the payload as versionedobject fields.
|
|
|
|
Please note that the notification objects shall not be registered to the
|
|
MoganObjectRegistry in order to avoid mixing Mogan internal objects with the
|
|
notification objects. Instead of that using the register_notification
|
|
decorator on every concrete notification object.
|
|
|
|
The following code example defines the necessary model classes for a new
|
|
notification `myobject.update`::
|
|
|
|
@mogan_base.MoganObjectRegistry.register_notification
|
|
class MyObjectNotification(notification.NotificationBase):
|
|
# Version 1.0: Initial version
|
|
VERSION = '1.0'
|
|
|
|
fields = {
|
|
'payload': fields.ObjectField('MyObjectUpdatePayload')
|
|
}
|
|
|
|
|
|
@mogan_base.MoganObjectRegistry.register_notification
|
|
class MyObjectUpdatePayload(notification.NotificationPayloadBase):
|
|
# Version 1.0: Initial version
|
|
VERSION = '1.0'
|
|
fields = {
|
|
'some_data': fields.StringField(),
|
|
'another_data': fields.StringField(),
|
|
}
|
|
|
|
|
|
After that the notification can be populated and emitted with the following
|
|
code::
|
|
|
|
payload = MyObjectUpdatePayload(some_data="foo", another_data="bar")
|
|
MyObjectNotification(
|
|
publisher=notification.NotificationPublisher.from_service_obj(
|
|
<movan.objects.server.Server instance that emits the notification>),
|
|
event_type=notification.EventType(
|
|
object='myobject',
|
|
action=fields.NotificationAction.UPDATE),
|
|
priority=fields.NotificationPriority.INFO,
|
|
payload=payload).emit(context)
|
|
|
|
The above code will generate the following notification on the wire::
|
|
|
|
{
|
|
"priority":"INFO",
|
|
"payload":{
|
|
"mogan_object.namespace":"mogan",
|
|
"mogan_object.name":"MyObjectUpdatePayload",
|
|
"mogan_object.version":"1.0",
|
|
"mogan_object.data":{
|
|
"some_data":"foo",
|
|
"another_data":"bar",
|
|
}
|
|
},
|
|
"event_type":"myobject.update",
|
|
"publisher_id":"<the name of the service>:<the host where the service runs>"
|
|
}
|
|
|
|
|
|
What should be in the notification payload
|
|
==========================================
|
|
This is just a guideline. You should always consider the actual use case that
|
|
requires the notification.
|
|
|
|
* Always include the identifier (e.g. uuid) of the entity that can be used to
|
|
query the whole entity over the REST API so that the consumer can get more
|
|
information about the entity.
|
|
* You should consider including those fields that are related to the event
|
|
you are sending the notification about. For example if a change of a field of
|
|
the entity triggers an update notification then you should include the field
|
|
to the payload.
|
|
* An update notification should contain information about which part of the
|
|
entity is changed. Either by filling the object changes part of the
|
|
payload (note that it is not supported by the notification framework
|
|
currently) or sending both the old state and the new state of the entity in
|
|
the payload.
|
|
* You should never include an internal object in the payload. Create a new
|
|
object and use the SCHEMA field to map the internal object to the
|
|
notification payload. In this way the evolution of the internal object model
|
|
can be decoupled from the evolution of the notification payload.
|
|
* The delete notification should contain the same information as the create or
|
|
update notifications. This makes it possible for the consumer to listen only
|
|
to the delete notifications but still filter on some fields of the entity
|
|
(e.g. project_id).
|
|
|
|
Existing versioned notifications
|
|
================================
|
|
|
|
.. This is a reference anchor used in the main index page.
|
|
.. _versioned_notification_samples:
|
|
|
|
.. versioned_notifications::
|
|
|
|
|
|
|
|
.. [1] https://docs.openstack.org/oslo.messaging/latest/reference/notifier.html
|
|
.. [2] https://docs.openstack.org/oslo.versionedobjects/latest/
|