From 3975aa3e87b21b5b7e007dfd303ff1a43dcd661a Mon Sep 17 00:00:00 2001 From: Athanasius Date: Mon, 7 Jun 2021 11:16:02 +0100 Subject: [PATCH] Contributing: Choose an appropriate logging level Open to comments on my definitions. --- Contributing.md | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/Contributing.md b/Contributing.md index 6257fea3..3a296798 100644 --- a/Contributing.md +++ b/Contributing.md @@ -312,6 +312,43 @@ exception*. e.g. Logging will know you were in your `get_foo()` function but you should still tell it what actually (failed to have) happened in there. +### Use the appropriate logging level +You must ensure necessary information is always in the log files, but +not so much that it becomes more difficult to discern important information +when diagnosing an issue. + +`logging`, and thus our `logger` instances provide functions of the +following names: + +- `info` - For general messages that don't occur too often outside of startup + and shutdown. +- `warning` - An error has been detected, but it doesn't impact continuing + functionality. In particular **use this when logging errors from + external services**. This would include where we detected a known issue + with Frontier-supplied data. A currently unknown issue *may* end up + triggering logging at `error` level or above. +- `error` - An error **in our code** has occurred. The application might be + able to continue, but we want to make it obvious there's a bug that we + need to fix. +- `critical` - An error has occurred **in our code** that impacts the + continuation of the current process. +- `debug` - Information about code flow and data that is occurs too often + to be at `info` level. Keep in mind our *default* logging level is DEBUG, + but users can change it for the + [plain log file](https://github.com/EDCD/EDMarketConnector/wiki/Troubleshooting#plain-log-file), + but the + [debug log giles](https://github.com/EDCD/EDMarketConnector/wiki/Troubleshooting#debug-log-files) + are always at least at DEBUG level. + +In addition to that we utilise one of the user-defined levels as: + +- `trace` - This is a custom log level intended for debug messages which + occur even more often and would cause too much log output for even + 'normal' debug use. + In general only developers will set this log level, but we do supply a + command-line argument and `.bat` file for users to enable it. It cannot be + selected from Settings in the UI. + ## Prefer fstrings to modulo-formatting and .format [fstrings](https://www.python.org/dev/peps/pep-0498/) are new in python 3.6, and allow for string interpolation rather