# Notifications

Like many other OpenStack services, nova emits notifications to the message bus with the `Notifier` class provided by oslo.messaging. 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>
    }

There are two types of notifications in nova: legacy notifications which have an unversioned payload and newer notifications which have a versioned payload.

## Legacy (unversioned) notifications

The unversioned notifications exist from the early days of nova and have mostly grown organically. The structure of the payload of the unversioned notifications is defined in the code that emits the notification and no documentation or enforced backward compatibility contract exists for that format.

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 `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 `oslo_messaging_notifications.driver` and `oslo_messaging_notifications.topics`.

## Versioned notifications

The versioned notification concept was created to fix the shortcomings of the unversioned notifications. The envelope structure of the emitted notification is the same as in the unversioned notification case as it is provided by oslo.messaging. However, the payload is not a free-form dictionary but a serialized oslo versionedobjects object.

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

    {
        "priority": "INFO",
        "payload": {
            "nova_object.namespace": "nova",
            "nova_object.name": "ServiceStatusPayload",
            "nova_object.version": "1.0",
            "nova_object.data": {
                "host": "host1",
                "disabled": false,
                "last_seen_up": null,
                "binary": "nova-compute",
                "topic": "compute",
                "disabled_reason": null,
                "report_count": 1,
                "forced_down": false,
                "version": 2
            }
        },
        "event_type": "service.update",
        "publisher_id": "nova-compute:host1"
    }

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 has changed. Nova provides the following contract regarding the versioned notification payload:

- 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 `nova_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, `nova_object.name`, for every payload alongside the `nova_object.data` and `nova_object.version` fields. This field contains the name of the nova internal representation of the payload type. Client code should not depend on this name.

A presentation from the Train summit goes over the background and usage of versioned notifications, and provides a demo.

## Configuration

The `notifications.notification_format` config option can be used to specify which notifications are emitted by nova.

The versioned notifications are emitted to a different topic than the legacy notifications. By default they are emitted to `versioned_notifications` but this can be configured using the `notifications.versioned_notifications_topics` config option.

There are notification configuration options in nova which are specific for certain notification types like `notifications.notify_on_state_change`, `notifications.default_level`, etc.

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

## Reference

A list of all currently supported versioned notifications can be found in Available versioned notifications.

this page last updated: 2026-04-21 19:00:00

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.

found an error? report a bug