Message content and context improvements

Starting with for example, nova/compute manager.py, looking at Info, Warning, Error and Critical messages, the following might be some of the suggested improvements.

An example of improving wording. It looks like a great code comment was added, but a rather poor message is given.

Before:
                # NOTE(vish): The instance failed to resume, so we set the
                # instance to error and attempt to continue.
                LOG.warning(_('Failed to resume instance'), instance=instance)

After:
                LOG.warning('The instance named (%(instance_name)s) on host' %(instance_host)s)'
                          'failed to resume. It\'s state will be set to error.', locals(), instance=instance)

 An example of improving context: Knowing the host should be useful.

Before:

                LOG.info("Instance disappeared before we could start it",
                         instance=instance)

After:
                LOG.info("The instance named (%(instance_name)s) on host (%(instance_host)s) was"
                        " removed before it could be started."),
                         instance=instance)

Some suggestions for better message context:

    Request information included when available.
    If there's more than one resource that the message could apply to, specify which resource is
           affected in the message.
    User/project that is involved.
    VM/Host that is involved.
    Storage/Network that is involved.

Some suggestions for better message content and wording:

    A short but clear description of the issue.
    Keep message wording consistent.
    State the problem. Focus on the problem, not the error.
    State what detected the problem.
    State what caused the problem.
    State why the problem happened.
    State what can be done to recover from/correct the issue if possible.

For information on log message levels and IDs, see blueprint
   https://blueprints.launchpad.net/nova/+spec/formal-message-ids.

Starting with for example, nova/compute manager.py, looking at Info, Warning, Error and Critical messages, the following might be some of the suggested improvements.

An example of improving wording. It looks like a great code comment was added, but a rather poor message is given.

Before:
                # NOTE(vish): The instance failed to resume, so we set the
                # instance to error and attempt to continue.
                LOG.warning(_('Failed to resume instance'), instance=instance)

After:
                LOG.warning('The instance named (%(instance_name)s) on host' %(instance_host)s)'
                          'failed to resume. It\'s state will be set to error.', locals(), instance=instance)

 An example of improving context: Knowing the host should be useful.

Before:

                LOG.info("Instance disappeared before we could start it",
                         instance=instance)

After:
                LOG.info("The instance named (%(instance_name)s) on host (%(instance_host)s) was"
                        " removed before it could be started."),
                         instance=instance)

Some suggestions for better message context:

    Request information included when available.
    If there's more than one resource that the message could apply to, specify which resource is
           affected in the message.
    User/project that is involved.
    VM/Host that is involved.
    Storage/Network that is involved.

Some suggestions for better message content and wording:

    A short but clear description of the issue.
    Keep message wording consistent.
    State the problem. Focus on the problem, not the error.
    State what detected the problem.
    State what caused the problem.
    State why the problem happened.
    State what can be done to recover from/correct the issue if possible.

For information on log message levels and IDs, see blueprint
   https://blueprints.launchpad.net/nova/+spec/formal-message-ids.

Marking this blueprint as definition: Drafting. If you are still working on this, please re-submit via nova-specs. If not, please mark as obsolete, and add a quick comment to describe why. --johnthetubaguy (20th April 2014)