notification_driver is poorly documented

Bug #1394397 reported by Andrew Bogott on 2014-11-19
24
This bug affects 3 people
Affects Status Importance Assigned to Milestone
openstack-manuals
Low
Joseph Robinson

Bug Description

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) on 2014-12-03
Changed in openstack-manuals:
status: New → Confirmed
importance: Undecided → Low
Tom Fifield (fifieldt) on 2015-06-18
tags: added: nova
Lana (loquacity) on 2015-06-29
tags: added: oslo
removed: nova
Changed in openstack-manuals:
status: Confirmed → Won't Fix
Lana (loquacity) wrote :

* 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) wrote :

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.

Changed in openstack-manuals:
status: Won't Fix → New
Tom Fifield (fifieldt) wrote :

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) wrote :

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

Changed in openstack-manuals:
status: New → Triaged
Michael Still (mikal) wrote :

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) wrote :

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) wrote :

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) wrote :

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.

Tom Fifield (fifieldt) on 2015-07-01
tags: added: ops-guide
tags: added: ops
removed: ops-guide
Changed in openstack-manuals:
assignee: nobody → Joseph Robinson (joseph-r-email)

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

Changed in openstack-manuals:
status: Triaged → In Progress

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

Changed in openstack-manuals:
status: In Progress → Fix Released

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

To post a comment you must log in.
This report contains Public information  Edit
Everyone can see this information.

Other bug subscribers