From 1cc14b18695fd2d4c1679f349f44dab4f66fc8e6 Mon Sep 17 00:00:00 2001 From: Matej Pavlovic Date: Fri, 28 Apr 2023 03:06:56 +0200 Subject: [PATCH] Add description of logging levels Signed-off-by: Matej Pavlovic --- docs/coding-guidelines.md | 51 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/coding-guidelines.md diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md new file mode 100644 index 000000000..ba26161ae --- /dev/null +++ b/docs/coding-guidelines.md @@ -0,0 +1,51 @@ +# Guidelines and conventions contributed code + +[DRAFT] + +TODO: Fill in 1-2 introductory sentences and more content. + +## Logging + +Each module that produces any log output should have a logger parameter. +Important events during the module's operation should produce a log output. +In the context of distributed protocols, the log levels have the following semantics: + +### FATAL +This should never happen and is the cause of immediate system halt. +No further execution is meaningful when the error occurs. +This log entry should provide the immediate reason for a crash. + +### ERROR +This should never happen. +An error is logged if and only if the functionality of the system might be compromised +and the system might not provide the advertised guarantees. +This should only be the case if there is a bug in the implementation +or if some assumptions of the implemented protocol (e.g. on the upper bound of faulty nodes) have been violated. + +### WARNING +A warning indicates that something potentially suspicious, but technically legitimate is happening. +When a warning is output, the distributed system as a whole is still fully functional, +even tough parts of it might not be any more. +A warning is the sign of something being sub-optimal, but accounted for. +For example, a warning should be triggered by the reception of a malformed message (another node might be faulty), +a buffer running out of space and dropping messages (network asynchrony or sub-optimal configuration), +a node (local or remote) severely lagging behind (slow node), etc. +If all the nodes are correct and operating smoothly (no significant slow-down) +and the network does not drop or significantly delay messages, no warnings should be logged. + +### INFO +An event that indicates the system making progress in its operation. +Info-level log events should be used sparingly, such that the stream of info-level output gives good insight +of what the node is currently doing, but is still observable in real time by a human. +For example, a block being delivered, the configuration having changed, or a checkpoint being created, +all are typical info-level events. + +### DEBUG +Debug events provide insight into the internal workings of the system. +The debug events can be produced at a higher rate than a human can perceive +and are intended for recording and studying later. +Interpreting a debug-level log entry can require deep knowledge of the details of the implementation. + +### TRACE +Very fine-grained log messages, providing a detailed insight about what code is being executed. +Trace-level logging is not expected to occur all throughout the code, but should only be inserted when needed.