OpenBMC Logging and Error Handling Dos and Don'ts

[Brad Bishop <bradleyb@fuzziesquirrel.com>]

I would like to start a document centered on logging best practices in
OpenBMC.  To get started I used a simple Do/Don't format and picked an
easy topic that I've repeatedly gotten feedback on.

Please let me know if you like the format or have any feedback.

Also please feel free to reply with suggestions for additional Do/Don't
items...I may write them up if time allows.

thanks!

-brad

----------

# OpenBMC Logging and Error Handling Dos and Don'ts
**Audience:** OpenBMC application developers

**Prerequisites:** None

---
## Don't require `-o verbose` for systemd journal MESSAGE field context
The MESSAGE field of a systemd journal entry should be self describing and not
rely on additional structured log data.  For example when the MESSAGE field
references a filesystem path, the path should appear in the MESSAGE field.
When the MESSAGE field references a failed system call, the system call and the
return value should appear in the MESSAGE field.  This keeps the journal
informative and useful for casual journal users.  Note that it is perfectly
acceptible to add (duplicate) structured log entry values for the data that
appears in MESSAGE.  This guideline only prescribes that the data _not_ be
omitted from the MESSAGE field value.


## Don't #2
TBD

## Do #1
TBD