Notifications¶

Like other OpenStack services, Neutron emits notifications to the message bus using the Notifier class provided by oslo.messaging. 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 Notification events 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:

[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_messaging_notifications.driver to noop.

Reference¶

A list of notification events and example payloads can be found in Notification events.

Notifications