Open Stack

We were recently having a discussion over here in trove regarding a 
standardized format to use for log and error messages - obviously 
consistency is ideal (within and across projects). As this discussion 
involves the broader dev community, bringing this topic to the list for 
feedback...


I'm aware of the logging standards wiki[1], however this page does not 
describe in depth a standardized format to use for log / error messages.

In particular w/r/t program values in messages:

(a) For in-line program values, I've seen both single quoted and 
unquoted formatting used. e.g.
single quote: LOG.info("The ID '%s' is not invalid." % (resource.id))
unquoted: LOG.info("The ID %s is not valid." % (resource.id))

(b) For program values appended to the message, I've seen various 
formats used. e.g.
LOG.info("This path is invalid: %s" % (obj.path))
LOG.info("This path is invalid %s" % (obj.path))
LOG.info("This path is invalid - %s" % (obj.path))


 From a consistency perspective, it seems we should consider 
standardizing a best practice for such formatting.

For in-line values (#a above) I find single quotes the most consumable 
as they are a clear indication the value came from code and moreover 
provide a clear set of delimiters around the value. However to date 
unquoted appears to be the most widely used.

For appended values (#b above) I find a delimiter such as ':' most 
consumable as it provides a clear boundary between the message and 
value. Using ':' seems fairly common today, but you'll find other 
formatting throughout the code.

If we wanted to squash this topic the high level steps are (approximately):
- Determine and document message format.
- Ensure the format is part of the dev process (coding + review).
- Cross team work to address existing messages not following the format.


Thoughts / comments?


[1] https://wiki.openstack.org/wiki/LoggingStandards