Attempt to document logging levels

List the 5 logging levels. Attempt to document what each does and some
example use cases.

We have a use case where we want to log internal bmcweb errors. debug is
way too chatty. Want to be able to select the logging level. This is the
documentation for that end goal.

These are loosely followed today and more patches will come to move some
traces to the appropriate level.

In our use case, we don't want to be blown up by a fuzz tester but do
want internal errors. This is the difference between error logging level
and warning logging level. Warning is used for 4xx (e.g. 404) and error
is used for 5xx.

Plan to write a tool to walk the redfish tree and try random Redfish ids
and/or try a open source fuzzing tool. The logging for these 404s should
be warning.

Moved the ## Debug logging section from the README.md to this
DEVELOPING.md. Wanted the logging all together but didn't think we had
enough for a LOGGING.md and README seems too high level for this detail.

Tested: Pushed to my fork and formatting looked good.

Change-Id: I9713a4e674b3f519fec3f3caac0178af8d8d73a8
Signed-off-by: Gunnar Mills <gmills@us.ibm.com>

1 files changed, 43 insertions, 0 deletions

diff --git a/DEVELOPING.md b/DEVELOPING.md
index be61476f1d..ae6b5c008f 100644
--- a/DEVELOPING.md
+++ b/DEVELOPING.md
@@ -203,3 +203,46 @@ design patterns, and bug prone constructs. The checks are implemented in the
 .clang-tidy file in the root of bmcweb, and are expected to be passing.
 [openbmc-build-scripts](https://github.com/openbmc/openbmc-build-scripts/blob/master/run-unit-test-docker.sh)
 implements clang-tidy checks and is the recommended way to run these checks
+
+### Logging Levels
+
+Five bmcweb logging levels are supported, from least to most severity:
+
+- debug
+- info
+- warning
+- error
+- critical
+
+And their use cases:
+
+- critical: Something went badly wrong, and we're no longer able to serve
+  traffic. "critical" should be used when bmcweb encountered an event or entered
+  a state that caused crucial function to stop working or when bmcweb
+  encountered a fatal error.
+- error: Something went wrong, and we weren't able to give the expected
+  response. Service is still operational. "error" should be used for unexpected
+  conditions that prevented bmcweb from fulfilling the request. "error" shall be
+  used for 5xx errors.
+- warning: A condition occurred that is outside the expected flows, but isn't
+  necessarily an error in the webserver, or might only be an error in certain
+  scenarios. For example, connection drops or 4xx errors.
+- info: Information for the golden path debugging.
+- debug: Information that's overly verbose such that it shouldn't be printed in
+  all debug scenarios, but might be useful in some debug contexts.
+
+### Enabling logging
+
+bmcweb by default is compiled with runtime logging disabled, as a performance
+consideration. To enable it in a standalone build, add the
+
+```ascii
+-Dlogging='enabled'
+```
+
+option to your configure flags. If building within Yocto, add the following to
+your local.conf.
+
+```bash
+EXTRA_OEMESON:pn-bmcweb:append = "-Dbmcweb-logging='enabled'"
+```