Add message ids for Warning, Error and Critical log messages

Registered by Mark Vanderwiel

Having formal Message IDs assigned to Warning, Error and Critical log messages can increase the serviceability and useability of the platform. The primary purpose will be to assist with the look up of more information from a product’s documentation especially when the messages are translated. Secondary purposes would be to help stream line translations, log analysis, context correlation and improve the message feedback loop. Informational log messages are considered self explanatory and don't require message id for additional look ups. A batch job could be run to collect and summarize the existing messages as a starting point for a wiki page with more explanations and possible resolutions.

Blueprint information

Status:
Complete
Approver:
Russell Bryant
Priority:
Undefined
Drafter:
Mark Vanderwiel
Direction:
Needs approval
Assignee:
None
Definition:
Obsolete
Series goal:
None
Implementation:
Unknown
Milestone target:
None
Completed by
Matt Riedemann

Related branches

Sprints

Whiteboard

Message ID format

   The format of the message ID is to contain 4 alpha characters followed by 4 digits:

    Component Identifier: 2 Alpha Characters
    Sub-Component Identifier: 2 Alpha Characters
    Message Identifier: 4 Digits

         Example: "ABcd1234 This is an example message"

Component Identifiers

   Component Identifiers are used to identify the brand from which the event was generated.
   General naming rule is to use the first character of the component name followed by the and then the next non-vowel character in the name.

    NV = Nova
    GL = Glance
    KY = Keystone
    SW = Swift
    CN = Cinder
    QN = Quantum
    HT = Heat
    CL = Ceilometer
    HR = Horizon
    IR = Ironic
    OL = Oslo *** used OL instead of OS to avoid confusion
    ...

Sub-component Identifiers

   Sub-component identifiers are used to identify the internal component affected by the message event. These can be shared across the various components as needed.
   General naming rule is to use the first character of the component name followed by the and then the next non-vowel character in the name.

    SC = Scheduler
    CM = Compute
    AP = API
    CL = Client
    HY = Hypervisor Driver
    NT = Network
    ...

Message Identifiers

   The message identifier is used to uniquely identify the specific message being sent within the component/subsystem. It is a four digit decimal identifier. Messages will be numbered from 0000-9999.

Display

   Message ID's will be displayed as an alphanumerical string. No deciphering of the message ID is expected on the end-users part.

Translation

   Message ID's will NEVER be translated.
   The message_ids.txt file noted below will NEVER be translated, it's used
   for development to track the IDs.

Examples

   "NVCM1234 Nova compute service message about %s."

   "QNAP1234 Quantum interface message about %s."

Implementation Notes

   A wiki page would be created to help guide the first time developer through the process of selecting the next available message id and creating a good message content at the right level with the appropriate context. Messages should be reviewed for level, context and content.

To start things off, here are some proposed guidelines to be used for log messages:
Proposed log level definitions:

    CRITICAL: This level is intended to represent conditions that should *never* happen. Service-level scope, triggered by conditions outside of OpenStack context
    (i.e. python run time error, kernel error, operating system issue).
    ERROR: This level is intended to represent conditions that should *never* happen. Operation-level scope, triggered by issues within OpenStack context
    (i.e. hardware managed by OS unexpected failed).
    WARNING: This level is intended to represent conditions that are *expected* to occasionally happen. Operation-level scope.
    Attempts are made (within code) to gracefully handle/recover.
    INFO: This class of message is for informational purposes only and provide an additional level of confirmation/status.
    DEBUG: This class of message is for development purposes only. It is not intended to be used in production environments.

See blueprint https://blueprints.launchpad.net/nova/+spec/message-improvements
for help with message content and context improvements.

  New log messages with levels of Warning, Error and Critical, would be updated with a new message id prefix as shown in the following examples:

  LOG.error(_("NVNT1234 Network driver option required, but not specified"))

  LOG.info(_("NVSC1234 Attempting to build %(num_instances)d instance(s) "
                    "uuids: %(instance_uuids)s"),
                  {'num_instances': len(instance_uuids),
                   'instance_uuids': instance_uuids})

  LOG.info(_('NVAP1000 Cannot update aggregate: %s'), id)

 New message ids are assigned from a simple text file, message_ids.txt, stored within the base of each component. As message ids are used, the file is updated within the patch set that created the new message either with a single message id or a range. The text file can also be used to capture possible resolutions and known use case scenarios that are fresh in the mind of the developer. This can then be used to help create additional formal product documentation as needed. It might be useful to create batch jobs to check for missing and unused entries within the text file. The message_ids file is not related to globalization, it's just a simple way to track used message ids within a component.

message_ids.txt

#
# The Nova Message ID file
#
# The Nova Scheduler NV SC
NVSC1234 <optional comments about the message usage including possible resolutions and known use case scenarios to be used in a wiki later>

# The Nova Network NV NT
NVNT1234 <optional comments about the message usage including possible resolutions and known use case scenarios to be used in a wiki later>

# The Nova APIs NV AP
NVAP1000-1100 Used for host aggregates

Examples of other message formats

MySQL client

Error: 2003 (CR_CONN_HOST_ERROR)

Message: Can't connect to MySQL server on '%s' (%d)

The message id is 2003 and is hardcoded in an errmsg.h header file. This would be similar to the message_ids.txt tracking file noted above.Message ID format

   The format of the message ID is to contain 4 alpha characters followed by 4 digits:

    Component Identifier: 2 Alpha Characters
    Sub-Component Identifier: 2 Alpha Characters
    Message Identifier: 4 Digits

         Example: "ABcd1234 This is an example message"

Component Identifiers

   Component Identifiers are used to identify the brand from which the event was generated.
   General naming rule is to use the first character of the component name followed by the and then the next non-vowel character in the name.

    NV = Nova
    GL = Glance
    KY = Keystone
    SW = Swift
    CN = Cinder
    QN = Quantum
    HT = Heat
    CL = Ceilometer
    HR = Horizon
    IR = Ironic
    OL = Oslo *** used OL instead of OS to avoid confusion
    ...

Sub-component Identifiers

   Sub-component identifiers are used to identify the internal component affected by the message event. These can be shared across the various components as needed.
   General naming rule is to use the first character of the component name followed by the and then the next non-vowel character in the name.

    SC = Scheduler
    CM = Compute
    AP = API
    CL = Client
    HY = Hypervisor Driver
    NT = Network
    ...

Message Identifiers

   The message identifier is used to uniquely identify the specific message being sent within the component/subsystem. It is a four digit decimal identifier. Messages will be numbered from 0000-9999.

Display

   Message ID's will be displayed as an alphanumerical string. No deciphering of the message ID is expected on the end-users part.

Translation

   Message ID's will NEVER be translated.
   The message_ids.txt file noted below will NEVER be translated, it's used
   for development to track the IDs.

Examples

   "NVCM1234 Nova compute service message about %s."

   "QNAP1234 Quantum interface message about %s."

Implementation Notes

   A wiki page would be created to help guide the first time developer through the process of selecting the next available message id and creating a good message content at the right level with the appropriate context. Messages should be reviewed for level, context and content.

To start things off, here are some proposed guidelines to be used for log messages:
Proposed log level definitions:

    CRITICAL: This level is intended to represent conditions that should *never* happen. Service-level scope, triggered by conditions outside of OpenStack context
    (i.e. python run time error, kernel error, operating system issue).
    ERROR: This level is intended to represent conditions that should *never* happen. Operation-level scope, triggered by issues within OpenStack context
    (i.e. hardware managed by OS unexpected failed).
    WARNING: This level is intended to represent conditions that are *expected* to occasionally happen. Operation-level scope.
    Attempts are made (within code) to gracefully handle/recover.
    INFO: This class of message is for informational purposes only and provide an additional level of confirmation/status.
    DEBUG: This class of message is for development purposes only. It is not intended to be used in production environments.

See blueprint https://blueprints.launchpad.net/nova/+spec/message-improvements
for help with message content and context improvements.

  New log messages with levels of Warning, Error and Critical, would be updated with a new message id prefix as shown in the following examples:

  LOG.error(_("NVNT1234 Network driver option required, but not specified"))

  LOG.info(_("NVSC1234 Attempting to build %(num_instances)d instance(s) "
                    "uuids: %(instance_uuids)s"),
                  {'num_instances': len(instance_uuids),
                   'instance_uuids': instance_uuids})

  LOG.info(_('NVAP1000 Cannot update aggregate: %s'), id)

 New message ids are assigned from a simple text file, message_ids.txt, stored within the base of each component. As message ids are used, the file is updated within the patch set that created the new message either with a single message id or a range. The text file can also be used to capture possible resolutions and known use case scenarios that are fresh in the mind of the developer. This can then be used to help create additional formal product documentation as needed. It might be useful to create batch jobs to check for missing and unused entries within the text file. The message_ids file is not related to globalization, it's just a simple way to track used message ids within a component.

message_ids.txt

#
# The Nova Message ID file
#
# The Nova Scheduler NV SC
NVSC1234 <optional comments about the message usage including possible resolutions and known use case scenarios to be used in a wiki later>

# The Nova Network NV NT
NVNT1234 <optional comments about the message usage including possible resolutions and known use case scenarios to be used in a wiki later>

# The Nova APIs NV AP
NVAP1000-1100 Used for host aggregates

Examples of other message formats

MySQL client

Error: 2003 (CR_CONN_HOST_ERROR)

Message: Can't connect to MySQL server on '%s' (%d)

The message id is 2003 and is hardcoded in an errmsg.h header file. This would be similar to the message_ids.txt tracking file noted above.

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)

(?)

Work Items

Work items:
Create a template/example message_ids.txt file. : TODO
Create a Nova message_ids.txt file. : TODO
Understand how these changes need to flow with globalization processes: TODO
Create first patch set maybe starting with some of the exception and manager.py parts: TODO
Maybe query Nova parts to understand numbers and locations of message types: TODO