.. _admin-notifications:

=============
Notifications
=============

Like other OpenStack services, Neutron emits notifications to the message bus
using the ``Notifier`` class provided by :oslo.messaging-doc:`oslo.messaging
<reference/notifier.html>`. From the consumer point of view, a notification
consists of an envelope with a fixed structure defined by oslo.messaging and a
payload defined by Neutron.

Notification envelope
~~~~~~~~~~~~~~~~~~~~~

The wire format of a notification 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 was emitted>,
        "publisher_id": <string, defined by the sender>,
        "message_id": <uuid, generated by oslo>,
        "payload": <json serialized dict, defined by the sender>
    }

Neutron emits legacy (unversioned) notifications only. The payload is a
free-form dictionary that mirrors API request or response bodies. Unlike Nova,
Neutron does not provide versioned notification payloads or a backward
compatibility contract for them.

When notifications are sent
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Most notifications are emitted by the Pecan WSGI ``NotifierHook`` when the
Neutron API processes create, update, or delete operations on REST resources.

* Notifications are sent for ``POST``, ``PUT``, and ``DELETE`` requests only.
* Member actions (for example,
  ``PUT /routers/{router_id}/add_router_interface``) do not trigger these
  notifications.
* For each operation, a ``*.start`` notification is sent before the plugin
  runs and a matching ``*.end`` notification is sent after a successful
  response (HTTP status code 300 or lower). If the operation fails, only the
  ``*.start`` notification is emitted.

Additional notifications are sent directly by specific plugins and agents for
router interfaces, resource tags, agent scheduling, metering, and usage
auditing. See :doc:`/reference/notifications` for the full event catalog and
payload details.

Publisher identifiers
~~~~~~~~~~~~~~~~~~~~~

Neutron uses ``neutron_lib.rpc.get_notifier()`` to obtain notifier instances.
The ``publisher_id`` field in the envelope is built from the service name and
host, for example ``network.myhost`` or ``router.myhost``. The most common
publisher identifiers are:

* ``network.<host>`` — API resource CRUD, router interfaces, tags, DHCP agent
  scheduling, usage audit
* ``router.<host>`` — L3 agent scheduling events
* ``metering.<host>`` — metering agent traffic reports

Configuration
~~~~~~~~~~~~~

Notifications are configured through oslo.messaging options in
``neutron.conf``. To enable notifications, set a driver other than ``noop``:

.. code-block:: ini

   [DEFAULT]
   transport_url = rabbit://guest:guest@localhost:5672/

   [oslo_messaging_notifications]
   driver = messagingv2
   topics = notifications

The available drivers are:

* ``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 using Python logging infrastructure
* ``test`` — store notifications in memory for test verification
* ``noop`` — disable sending notifications entirely

The default topic is ``notifications``. Messages are published to
``<topic>.<priority>`` (for example, ``notifications.INFO``).

To support the DHCP agent, the ``messagingv2`` driver must be enabled so that
RPC-based agent notifiers can receive resource change events.

Notifications can be disabled entirely by setting
:oslo.config:option:`oslo_messaging_notifications.driver` to ``noop``.

Reference
~~~~~~~~~

A list of notification events and example payloads can be found in
:doc:`/reference/notifications`.
