..
      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.

Notifications in Masakari
==========================

Similarly to other OpenStack services Masakari emits notifications to the message
bus with the Notifier class provided by `oslo.messaging-doc`_. From the notification
consumer point of view a notification consists of two parts: an envelope with a fixed
structure defined by oslo.messaging and a payload defined by the service emitting the
notification. The envelope format is 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>
    }

oslo.messaging provides below choices of notification drivers:
    ===============   ==========================================================================
    Driver            Description
    ===============   ==========================================================================
    messaging         Send notifications using the 1.0 message format
    messagingv2       Send notifications using the 2.0 message format (with a message envelope)
    routing           Configurable routing notifier (by priority or event_type)
    log               Publish notifications via Python logging infrastructure
    test              Store notifications in memory for test verification
    noop              Disable sending notifications entirely
    ===============   ==========================================================================

So notifications can be completely disabled by setting the following in
Masakari configuration file:

.. code-block:: ini

  [oslo_messaging_notifications]
  driver = noop

Masakari supports only Versioned notifications.

Versioned notifications
-----------------------
Masakari code uses the masakari.rpc.get_notifier call to get a configured
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 depends on the parameters of the get_notifier call and the
value of the oslo.messaging configuration options ``driver`` and ``topics``.
The versioned notification the the payload is not a free form dictionary but a
serialized `oslo.versionedobjects-doc`_.

.. _service.update:

For example the wire format of the ``segment.update`` notification looks like
the following::

    {
        "event_type": "api.update.segments.start",
        "timestamp": "2018-11-27 14:32:20.396940",
        "payload": {
            "masakari_object.name": "SegmentApiPayload",
            "masakari_object.data": {
                "description": null,
                "fault": null,
                "recovery_method": "auto",
                "name": "test",
                "service_type": "compute",
                "id": 877,
                "uuid": "89597691-bebd-4860-a93e-1b6e9de34b9e"
            }, "
            "masakari_object.version": "1.0",
            "masakari_object.namespace": "masakari"
        },
        "priority": "INFO",
        "publisher_id": "masakari-api:test-virtualbox",
        "message_id": "e6322900-025d-4dd6-a3a1-3e0e1e9badeb"
    }

The serialized oslo versionedobject as a payload provides a version number to
the consumer so the consumer can detect if the structure of the payload is
changed. Masakari provides the following contract regarding the versioned
notification payload:

* the payload version defined by the ``masakari_object.version`` field of the
  payload will be increased if and only if the syntax or the semantics of the
  ``masakari_object.data`` field of the payload is changed.
* 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
  consume the new payload without any change.
* a major version bump indicates a backward incompatible change of the payload
  which can mean removed fields, type change, etc in the payload.
* there is an additional field 'masakari_object.name' for every payload besides
  'masakari_object.data' and 'masakari_object.version'. This field contains the name of
  the Masakari internal representation of the payload type. Client code should not
  depend on this name.

Existing versioned notifications
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
* This provides the list of existing versioned notifications with sample payloads.

.. versioned_notifications::
.. _`oslo.messaging-doc`: 	http://docs.openstack.org/developer/oslo.messaging/notifier.html
.. _`oslo.versionedobjects-doc`: 	http://docs.openstack.org/developer/oslo.messaging/notifier.html