Merge "Revisons on notifications doc"
This commit is contained in:
commit
71b3e7c2b1
|
@ -47,10 +47,11 @@ Nova code uses the nova.rpc.get_notifier call to get a configured
|
||||||
oslo.messaging Notifier object and it uses the oslo provided functions on the
|
oslo.messaging Notifier object and it uses the oslo provided functions on the
|
||||||
Notifier object to emit notifications. The configuration of the returned
|
Notifier object to emit notifications. The configuration of the returned
|
||||||
Notifier object depends on the parameters of the get_notifier call and the
|
Notifier object depends on the parameters of the get_notifier call and the
|
||||||
value of the oslo.messaging configuration options `driver` and `topics`.
|
value of the oslo.messaging configuration options ``driver`` and ``topics``.
|
||||||
There are notification configuration options in Nova which are specific for
|
There are notification configuration options in Nova which are specific for
|
||||||
certain notification types like `notifications.notify_on_state_change`,
|
certain notification types like
|
||||||
`notifications.default_level`, etc.
|
:oslo.config:option:`notifications.notify_on_state_change`,
|
||||||
|
:oslo.config:option:`notifications.default_level`, etc.
|
||||||
|
|
||||||
The structure of the payload of the unversioned notifications is defined in the
|
The structure of the payload of the unversioned notifications is defined in the
|
||||||
code that emits the notification and no documentation or enforced backward
|
code that emits the notification and no documentation or enforced backward
|
||||||
|
@ -67,8 +68,8 @@ serialized :oslo.versionedobjects-doc:`oslo versionedobjects object <>`.
|
||||||
|
|
||||||
.. _service.update:
|
.. _service.update:
|
||||||
|
|
||||||
For example the wire format of the `service.update` notification looks like the
|
For example the wire format of the ``service.update`` notification looks like
|
||||||
following::
|
the following::
|
||||||
|
|
||||||
{
|
{
|
||||||
"priority":"INFO",
|
"priority":"INFO",
|
||||||
|
@ -97,9 +98,9 @@ the consumer so the consumer can detect if the structure of the payload is
|
||||||
changed. Nova provides the following contract regarding the versioned
|
changed. Nova provides the following contract regarding the versioned
|
||||||
notification payload:
|
notification payload:
|
||||||
|
|
||||||
* the payload version defined by the `the nova_object.version` field of the
|
* the payload version defined by the ``nova_object.version`` field of the
|
||||||
payload will be increased if and only if the syntax or the semantics of the
|
payload will be increased if and only if the syntax or the semantics of the
|
||||||
`nova_object.data` field of the payload is changed.
|
``nova_object.data`` field of the payload is changed.
|
||||||
* a minor version bump indicates a backward compatible change which means that
|
* a minor version bump indicates a backward compatible change which means that
|
||||||
only new fields are added to the payload so a well written consumer can still
|
only new fields are added to the payload so a well written consumer can still
|
||||||
consume the new payload without any change.
|
consume the new payload without any change.
|
||||||
|
@ -110,14 +111,16 @@ notification payload:
|
||||||
the nova internal representation of the payload type. Client code should not
|
the nova internal representation of the payload type. Client code should not
|
||||||
depend on this name.
|
depend on this name.
|
||||||
|
|
||||||
There is a Nova configuration parameter `notifications.notification_format`
|
There is a Nova configuration parameter
|
||||||
|
:oslo.config:option:`notifications.notification_format`
|
||||||
that can be used to specify which notifications are emitted by Nova. The
|
that can be used to specify which notifications are emitted by Nova. The
|
||||||
possible values are `unversioned`, `versioned`, `both` and the default value
|
possible values are ``unversioned``, ``versioned``, ``both`` and the default
|
||||||
is `both`.
|
value is ``both``.
|
||||||
|
|
||||||
The versioned notifications are emitted to a different topic than the legacy
|
The versioned notifications are emitted to a different topic than the legacy
|
||||||
notifications. By default they are emitted to 'versioned_notifications' but it
|
notifications. By default they are emitted to 'versioned_notifications' but it
|
||||||
is configurable in the nova.conf with the `versioned_notifications_topic`
|
is configurable in the nova.conf with the
|
||||||
|
:oslo.config:option:`notifications.versioned_notifications_topics`
|
||||||
config option.
|
config option.
|
||||||
|
|
||||||
How to add a new versioned notification
|
How to add a new versioned notification
|
||||||
|
@ -125,12 +128,12 @@ How to add a new versioned notification
|
||||||
|
|
||||||
To support the above contract from the Nova code every versioned notification
|
To support the above contract from the Nova code every versioned notification
|
||||||
is modeled with oslo versionedobjects. Every versioned notification class
|
is modeled with oslo versionedobjects. Every versioned notification class
|
||||||
shall inherit from the `nova.notifications.objects.base.NotificationBase` which
|
shall inherit from the ``nova.notifications.objects.base.NotificationBase``
|
||||||
already defines three mandatory fields of the notification `event_type`,
|
which already defines three mandatory fields of the notification
|
||||||
`publisher_id` and `priority`. The new notification class shall add a new field
|
``event_type``, ``publisher`` and ``priority``. The new notification class
|
||||||
`payload` with an appropriate payload type. The payload object of the
|
shall add a new field ``payload`` with an appropriate payload type. The payload
|
||||||
notifications shall inherit from the
|
object of the notifications shall inherit from the
|
||||||
`nova.objects.notifications.base.NotificationPayloadBase` class and shall
|
``nova.notifications.objects.base.NotificationPayloadBase`` class and shall
|
||||||
define the fields of the payload as versionedobject fields. The base classes
|
define the fields of the payload as versionedobject fields. The base classes
|
||||||
are described in the following section.
|
are described in the following section.
|
||||||
|
|
||||||
|
@ -147,7 +150,7 @@ objects. Instead of that use the register_notification decorator on every
|
||||||
concrete notification object.
|
concrete notification object.
|
||||||
|
|
||||||
The following code example defines the necessary model classes for a new
|
The following code example defines the necessary model classes for a new
|
||||||
notification `myobject.update`::
|
notification ``myobject.update``::
|
||||||
|
|
||||||
@notification.notification_sample('myobject-update.json')
|
@notification.notification_sample('myobject-update.json')
|
||||||
@object_base.NovaObjectRegistry.register.register_notification
|
@object_base.NovaObjectRegistry.register.register_notification
|
||||||
|
@ -202,10 +205,11 @@ The above code will generate the following notification on the wire::
|
||||||
|
|
||||||
|
|
||||||
There is a possibility to reuse an existing versionedobject as notification
|
There is a possibility to reuse an existing versionedobject as notification
|
||||||
payload by adding a `SCHEMA` field for the payload class that defines a mapping
|
payload by adding a ``SCHEMA`` field for the payload class that defines a
|
||||||
between the fields of existing objects and the fields of the new payload
|
mapping between the fields of existing objects and the fields of the new
|
||||||
object. For example the service.status notification reuses the existing
|
payload object. For example the service.status notification reuses the existing
|
||||||
`nova.objects.service.Service` object when defines the notification's payload::
|
``nova.objects.service.Service`` object when defines the notification's
|
||||||
|
payload::
|
||||||
|
|
||||||
@notification.notification_sample('service-update.json')
|
@notification.notification_sample('service-update.json')
|
||||||
@object_base.NovaObjectRegistry.register.register_notification
|
@object_base.NovaObjectRegistry.register.register_notification
|
||||||
|
@ -249,8 +253,8 @@ object. For example the service.status notification reuses the existing
|
||||||
def populate_schema(self, service):
|
def populate_schema(self, service):
|
||||||
super(ServiceStatusPayload, self).populate_schema(service=service)
|
super(ServiceStatusPayload, self).populate_schema(service=service)
|
||||||
|
|
||||||
If the `SCHEMA` field is defined then the payload object needs to be populated
|
If the ``SCHEMA`` field is defined then the payload object needs to be
|
||||||
with the `populate_schema` call before it can be emitted::
|
populated with the ``populate_schema`` call before it can be emitted::
|
||||||
|
|
||||||
payload = ServiceStatusPayload()
|
payload = ServiceStatusPayload()
|
||||||
payload.populate_schema(service=<nova.object.service.Service object>)
|
payload.populate_schema(service=<nova.object.service.Service object>)
|
||||||
|
@ -266,33 +270,35 @@ with the `populate_schema` call before it can be emitted::
|
||||||
The above code will emit the :ref:`already shown notification<service.update>`
|
The above code will emit the :ref:`already shown notification<service.update>`
|
||||||
on the wire.
|
on the wire.
|
||||||
|
|
||||||
Every item in the `SCHEMA` has the syntax of::
|
Every item in the ``SCHEMA`` has the syntax of::
|
||||||
|
|
||||||
<payload field name which needs to be filled>:
|
<payload field name which needs to be filled>:
|
||||||
(<name of the parameter of the populate_schema call>,
|
(<name of the parameter of the populate_schema call>,
|
||||||
<the name of a field of the parameter object>)
|
<the name of a field of the parameter object>)
|
||||||
|
|
||||||
The mapping defined in the `SCHEMA` field has the following semantics. When
|
The mapping defined in the ``SCHEMA`` field has the following semantics. When
|
||||||
the `populate_schema` function is called the content of the `SCHEMA` field is
|
the ``populate_schema`` function is called the content of the ``SCHEMA`` field
|
||||||
enumerated and the value of the field of the pointed parameter object is copied
|
is enumerated and the value of the field of the pointed parameter object is
|
||||||
to the requested payload field. So in the above example the `host` field of
|
copied to the requested payload field. So in the above example the ``host``
|
||||||
the payload object is populated from the value of the `host` field of the
|
field of the payload object is populated from the value of the ``host`` field
|
||||||
`service` object that is passed as a parameter to the `populate_schema` call.
|
of the ``service`` object that is passed as a parameter to the
|
||||||
|
``populate_schema`` call.
|
||||||
|
|
||||||
A notification payload object can reuse fields from multiple existing
|
A notification payload object can reuse fields from multiple existing
|
||||||
objects. Also a notification can have both new and reused fields in its
|
objects. Also a notification can have both new and reused fields in its
|
||||||
payload.
|
payload.
|
||||||
|
|
||||||
Note that the notification's publisher instance can be created two different
|
Note that the notification's publisher instance can be created two different
|
||||||
ways. It can be created by instantiating the `NotificationPublisher` object
|
ways. It can be created by instantiating the ``NotificationPublisher`` object
|
||||||
with a `host` and a `binary` string parameter or it can be generated from a
|
with a ``host`` and a ``binary`` string parameter or it can be generated from a
|
||||||
`Service` object by calling `NotificationPublisher.from_service_obj` function.
|
``Service`` object by calling ``NotificationPublisher.from_service_obj``
|
||||||
|
function.
|
||||||
|
|
||||||
Versioned notifications shall have a sample file stored under
|
Versioned notifications shall have a sample file stored under
|
||||||
`doc/sample_notifications` directory and the notification object shall be
|
``doc/sample_notifications`` directory and the notification object shall be
|
||||||
decorated with the `notification_sample` decorator. For example the
|
decorated with the ``notification_sample`` decorator. For example the
|
||||||
`service.update` notification has a sample file stored in
|
``service.update`` notification has a sample file stored in
|
||||||
`doc/sample_notifications/service-update.json` and the
|
``doc/sample_notifications/service-update.json`` and the
|
||||||
ServiceUpdateNotification class is decorated accordingly.
|
ServiceUpdateNotification class is decorated accordingly.
|
||||||
|
|
||||||
Notification payload classes can use inheritance to avoid duplicating common
|
Notification payload classes can use inheritance to avoid duplicating common
|
||||||
|
|
Loading…
Reference in New Issue