notification_driver is poorly documented

[Andrew Bogott]

notification_driver is only barely mentioned in the nova docs. Where it is mentioned, it says terse things like "Driver or drivers to handle sending notifications"

The behavior of that setting has changed radically from version to version, with no updates in docs. In Icehouse, notification_driver can be set to several built-in drivers, none of them enumerated in docs as far as I can see. It can also refer to a custom notifier, but that notifier needs an entrypoint in the (again, undocumented) oslo.messaging.notify.drivers namespace.

(In Havana, it didn't use an entrypoint but just specified a file in the python path. In Juno or Kilo, who knows?)

[Lana (loquacity)]

* This is internal glue, albeit configurable internal glue, but it doesn't really have an end-user impact. For that reason, it probably belongs in dev or API docs, more than openstack-manuals.
* As far as we can tell (and I understand this is a difficult thing to measure), this driver is only minimally in use, so the impact even to devs is pretty trivial

I have contacted the Nova PTL, Oslo PTL, and the Oslo docs liaison regarding this. Please feel free to raise an objection and reopen if you feel I've closed this in error.

[Tom Fifield (fifieldt)]

So, notifications are actually consumed by end-users :)

They are important for keeping track of things without going directly to the database. Quite a few ops have little apps that use them - it's pretty good practice. One example app that makes use of them is StackTach.

As a result, I think notifications should be documented.

[Tom Fifield (fifieldt)]

There are some docs on the notification system at:

https://wiki.openstack.org/wiki/NotificationSystem
https://wiki.openstack.org/wiki/SystemUsageData

and we can see the design is actually to "make notifications available to users in as close to a real-time manner as is feasible."

[Tom Fifield (fifieldt)]

Further on Sandy Walsh's blog:

http://www.sandywalsh.com/2013/09/notification-usage-in-openstack-report.html

[Tom Fifield (fifieldt)]

To solve this bug, we should provide a general introduction to notifications, and an example of how to consume them.

[Michael Still (mikal)]

Tom, are these ops people consuming notifications from rabbitmq or writing their own notification drivers though? I don't think I've ever encountered anyone writing a new driver.

That said, if we had someone who had who would be willing to talk to me about it, I'd be happy to try and document some of this stuff better.

[Tom Fifield (fifieldt)]

For sure - I don't think people are doing their own drivers. I think the notification_driver and surrounds in the config is probably a starting point for most people to get into the consumption of things though, no?

I'm imagining a doc which is like "well, the default notification_driver is oslo.omg123. and what this does is ... and it is useful to do ... an example is ..."

At the moment, I don't think we document notifications at all, so I'd be happy to see just about anything!

[Andrew Bogott (andrewbogott)]

I have a custom notification driver, which keeps breaking. Hence my opening the bug. It's a bit of a hack, but hooking the driver calls directly allows me to respond to events synchronously, whereas notifications arrive at unpredictable times. I've gone around in circles a bit with this one, trying to get a stable, public hook for events like new instance creation (e.g. the old 'plugin framework' which I wrote but which was then deprecated.)

But, ok, regardless of whether or not this is a feature that Nova will support... if it's in a config file it needs to be documented. If the docs had something like "Hey, this is totally internal and will be changing all the time and don't use it for a hook" then maybe I wouldn't be down the path that I'm down now.

[Mike Dorman (mdorman-m)]

We utilize notifications with the stock driver, although we also publish to Kafka via the ceilometer notifications service. We've never had to use a different driver, so the default notification_driver has always worked for us.

But, yes, we definitely do use notifications and they do more or less get consumed by real end users.

[OpenStack Infra (hudson-openstack)]

Fix proposed to branch: master
Review: https://review.openstack.org/219575

[OpenStack Infra (hudson-openstack)]

Reviewed: https://review.openstack.org/219575
Committed: https://git.openstack.org/cgit/openstack/openstack-manuals/commit/?id=32131b7d3fde5bd52dc79ab8e45100d687b64cb6
Submitter: Jenkins
Branch: master

commit 32131b7d3fde5bd52dc79ab8e45100d687b64cb6
Author: Joseph Robinson <email address hidden>
Date: Wed Sep 2 16:42:47 2015 +1000

    Documenting notification_driver

    Adding further information on how the notification_driver
    works, and how administrators and users can interact with the
    configuration setting.

    Change-Id: I9ffd573da09ee6de0195063c5c6895971b686169
    Closes-Bug: #1394397

[OpenStack Infra (hudson-openstack)]

This issue was fixed in the openstack/openstack-manuals 15.0.0 release.