Explicit user messages

Explicit user messages


Use ‘action’, ‘resource’, ‘message’ to replace ‘event’ in user messages.

Problem description

We have introduced user messages since Ocata, that’s a beneficial feature, because it solves the problem that we don’t provide enough message when an async task is failed (especially for volume and snapshot resources). It’s easy to find out when and where the task failed with our new messages APIs.

But, the better user experience all depend on whether we have hard coded enough user messages in our projects. So that raises a new question, how could we add these messages without changing our code frequently and how could we maintain this ‘better user experience but not functionality involved’ code cleanly.

Here are some of our user message related codes:

# CODE1: defined event ids
# CODE2: try/except and write the user messages
with excutils.save_and_reraise_exception():
    if isinstance(error, exception.ImageLimitExceeded):

We would possibly have several issues if we try to add more user messages based on those presets.

  • [CODE1]: We would redefine a lot of similar event ids, such as UNABLE_CREATE_VOLUME_DRIVER_NOT_READY, UNABLE_CREATE_SNAPSHOT_DRIVER_NOT_READY and UNABLE_CREATE_BACKUP_DRIVER_NOT_READY, it’s obvious that they are all due to the same error and are created at same procedure (create resource).
  • [CODE2]: To have an explicit message, we would have a bunch of ‘if/else’ codes which only focus on detecting the error class and write down the corresponding messages, and even worse if the exception gets more and more, we have to update the code again and again.

So could we have a better way to fix these?

Use Cases

The main use-case here is for an explicit user message to end users and a better maintaining experience for cinder developers.

Proposed change

The proposed changes are:

  • Introduce message (or name it detail to avoid confusion) to user messages, the ‘message’ only represent what (no matter error or warning) happened at that explicit time, that means QUOTA_EXCEED is a valid one while UPLOAD_TO_IMAGE_OVER_QUOTA isn’t.

  • Build the relationship from exceptions to messages, we have a bunch of exceptions which could directly point out what happened and how to fix, but we couldn’t expose this to the end user because it would expose some sensitive information. We couldn’t hard code the cleaned messages into exceptions either, because the exceptions would be defined at different places (take cinder exceptions and driver exceptions for example) and different exceptions can be translated into one user messages. so this is proposed how to do, build a dictionary from exception name to messages (introduced above):

    # multi_key dictionary
    ['HBSDBusy','XtremIOArrayBusy']: MessageIds.DEVICE_IS_BUSY
     'ViolinInvalidBackendConfig']: MessageIds.INVALID_CONFIGURATION
    message_map = {
    MessageIds.DEVICE_IS_BUSY: _("Backend device is busy at present."),
    MessageIds.INVALID_CONFIGURATION: _("Invalid configuration."),
  • Introduce action to user messages. This one should be introduced along with the messages, and can use it to indicate when the message is created, such as CREATE_SNAPSHOT_IN_BACKEND, UPLOAD_TO_IMAGE.

  • Generate event_id automatically, user message is used to build user friendly messages for project which directly display the information for administrators. But when referring to the projects which detect, classify and use our messages, the event_id is more useful at this case, so we should have ‘event_id’ no matter how we change the underground behaviour. Instead of manually define and maintain this event_ids we could build them by a combination of RESOURCE, ACTION and MESSAGE, take these for example:

    # This is how we define event currently
    # This is how we would build the event_id at response after this change.

    We could have these benefits:

    1. We don’t need to define that much events. (we only need to define less messages).
    2. It’s also unique cross all of OpenStack.
    3. It’s reading friendly and easy to classify or analysis.


The alternatives is we could keep adding user messages in the way of we currently have [1]. (There could be more alternatives or better solutions, but I failed to figure out.)

Data model impact

Database update is required to store the ‘action_id’ and ‘message_id’, also we can deprecate the ‘event_id’, because we could generate it anytime we want.

REST API impact

We don’t have API impact because we didn’t expose the create API.

Security impact


Notifications impact


Other end user impact


Performance Impact


Other deployer impact


Developer impact

For a better experience, developers have to maintain the relationship from exception to messages when any related change is made.



Primary assignee:

Work Items

  • Upgrade database to reflect new user message object.
  • Support ‘exception’ and ‘action’ in user message APIs.
  • Add some unit tests.
  • Add script for database migration.




  • Unit tests

Documentation Impact

  • Update developer documentation for ‘exception-to-message’ dictionary.
Creative Commons Attribution 3.0 License

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

Cinder Specs