Add message ids for Warning, Error and Critical log messages
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
- Started by
- Completed by
- Matt Riedemann
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/
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/
DEBUG: This class of message is for development purposes only. It is not intended to be used in production environments.
See blueprint https:/
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(
LOG.info(
LOG.info(
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_
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/
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/
DEBUG: This class of message is for development purposes only. It is not intended to be used in production environments.
See blueprint https:/
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(
LOG.info(
LOG.info(
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_
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