From d5bdebdcac6639c1f1820e86dcab587e98498dd1 Mon Sep 17 00:00:00 2001 From: dapplion <35266934+dapplion@users.noreply.github.com> Date: Thu, 23 Mar 2023 11:20:10 +0900 Subject: [PATCH 1/5] Add logging policy --- CONTRIBUTING.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a36aee18fab3..7c0d2e34049f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -150,6 +150,27 @@ We're currently experimenting with hosting the majority of lodestar packages and - Error: One or more main functionalities are not working, preventing some functions from working properly. - Fatal: One or more main functionalities are not working and preventing the application from fulfilling its duties. +## Logging policy + +### Logging Levels + +- `error`: Critical issues that prevent the application from functioning correctly or cause significant disruption to users. Examples include failed network connections, crashes, or data corruption. +- `warn`: Situations that may lead to critical issues if not addressed but do not prevent the application from functioning. Examples include configuration issues, deprecated features, or temporary network disruptions. +- `info`: General sporadic informational about the node's state. Examples include initialization messages, infrequent periodic status updates, or high-level progress reports. +- `verbose`: _TBD_ +- `debug`: Detailed diagnostic information that can help developers or users troubleshoot specific issues. Examples include individual request logs for every REST API, networking interactions, or internal components status changes. + +### Guideliness + +1. Always use the appropriate log level as defined above. Log messages should be clear and concise, providing enough information to understand the context and severity of the issue. +2. Avoid excessive logging. Log only the information that is necessary for understanding and troubleshooting issues. Over-logging can make it more difficult for users to find relevant information. +3. Do not log sensitive data, such as private keys, user credentials, or personal information. +4. Do not log arbitrary data from the network as ASCII or UTF8 at levels higher or equal to the current default level. +5. Use clear and concise language. Prefer to log variables in JSON format `log.debug("Action", {slot})` instead of formating the text yourself `log.debug('slot=${slot}')`. +6. Include only relevant context in log messages, sufficient to debug the issue or action it refers to. + +Contributors must chose the log level carefully to ensure a consistent experience for every type of user: + ## Contributing to Grafana dashboards To edit or extend an existing Grafana dashboard with minimal diff: From 92f7e9d6269c933563b1bc0626d152b6fc5b482a Mon Sep 17 00:00:00 2001 From: Lion - dapplion <35266934+dapplion@users.noreply.github.com> Date: Tue, 28 Mar 2023 10:50:57 +0900 Subject: [PATCH 2/5] Update CONTRIBUTING.md Co-authored-by: Cayman --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7c0d2e34049f..7b85ee3017ea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -157,7 +157,7 @@ We're currently experimenting with hosting the majority of lodestar packages and - `error`: Critical issues that prevent the application from functioning correctly or cause significant disruption to users. Examples include failed network connections, crashes, or data corruption. - `warn`: Situations that may lead to critical issues if not addressed but do not prevent the application from functioning. Examples include configuration issues, deprecated features, or temporary network disruptions. - `info`: General sporadic informational about the node's state. Examples include initialization messages, infrequent periodic status updates, or high-level progress reports. -- `verbose`: _TBD_ +- `verbose`: High-level state changes to internal modules. Examples include chain and state updates. - `debug`: Detailed diagnostic information that can help developers or users troubleshoot specific issues. Examples include individual request logs for every REST API, networking interactions, or internal components status changes. ### Guideliness From 37c9b40d815b5b1286a9e1a9cecace81cb514ecd Mon Sep 17 00:00:00 2001 From: dapplion <35266934+dapplion@users.noreply.github.com> Date: Thu, 30 Mar 2023 09:55:47 +0900 Subject: [PATCH 3/5] Review PR --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b85ee3017ea..d1c61601834e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -157,15 +157,15 @@ We're currently experimenting with hosting the majority of lodestar packages and - `error`: Critical issues that prevent the application from functioning correctly or cause significant disruption to users. Examples include failed network connections, crashes, or data corruption. - `warn`: Situations that may lead to critical issues if not addressed but do not prevent the application from functioning. Examples include configuration issues, deprecated features, or temporary network disruptions. - `info`: General sporadic informational about the node's state. Examples include initialization messages, infrequent periodic status updates, or high-level progress reports. -- `verbose`: High-level state changes to internal modules. Examples include chain and state updates. -- `debug`: Detailed diagnostic information that can help developers or users troubleshoot specific issues. Examples include individual request logs for every REST API, networking interactions, or internal components status changes. +- `debug`: Detailed diagnostic information that can help developers or users troubleshoot specific issues. Examples include individual request logs for every REST API, networking interactions, or internal components status changes. Alias to `verbose`. +- `trace`: Reserved for extremely verbose logs such a step by step execution traces of individual network packets or similar granular actions ### Guideliness -1. Always use the appropriate log level as defined above. Log messages should be clear and concise, providing enough information to understand the context and severity of the issue. -2. Avoid excessive logging. Log only the information that is necessary for understanding and troubleshooting issues. Over-logging can make it more difficult for users to find relevant information. +1. Always use the appropriate log level as defined above. +2. Avoid excessive logging. Log messages should be clear and concise, providing enough information to understand the context and severity of the issue. 3. Do not log sensitive data, such as private keys, user credentials, or personal information. -4. Do not log arbitrary data from the network as ASCII or UTF8 at levels higher or equal to the current default level. +4. Do not log arbitrary data from the network as ASCII or UTF8 at levels higher or equal to `info`. 5. Use clear and concise language. Prefer to log variables in JSON format `log.debug("Action", {slot})` instead of formating the text yourself `log.debug('slot=${slot}')`. 6. Include only relevant context in log messages, sufficient to debug the issue or action it refers to. From 2757afab4f4c7a4afcd1864041b930e7533fa853 Mon Sep 17 00:00:00 2001 From: dapplion <35266934+dapplion@users.noreply.github.com> Date: Fri, 31 Mar 2023 14:31:05 +0900 Subject: [PATCH 4/5] Address review --- CONTRIBUTING.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d1c61601834e..bccc1330c783 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -154,22 +154,21 @@ We're currently experimenting with hosting the majority of lodestar packages and ### Logging Levels +Contributors must chose the log level carefully to ensure a consistent experience for every type of user: + - `error`: Critical issues that prevent the application from functioning correctly or cause significant disruption to users. Examples include failed network connections, crashes, or data corruption. - `warn`: Situations that may lead to critical issues if not addressed but do not prevent the application from functioning. Examples include configuration issues, deprecated features, or temporary network disruptions. - `info`: General sporadic informational about the node's state. Examples include initialization messages, infrequent periodic status updates, or high-level progress reports. - `debug`: Detailed diagnostic information that can help developers or users troubleshoot specific issues. Examples include individual request logs for every REST API, networking interactions, or internal components status changes. Alias to `verbose`. - `trace`: Reserved for extremely verbose logs such a step by step execution traces of individual network packets or similar granular actions -### Guideliness +### Logging guidelines -1. Always use the appropriate log level as defined above. -2. Avoid excessive logging. Log messages should be clear and concise, providing enough information to understand the context and severity of the issue. -3. Do not log sensitive data, such as private keys, user credentials, or personal information. -4. Do not log arbitrary data from the network as ASCII or UTF8 at levels higher or equal to `info`. -5. Use clear and concise language. Prefer to log variables in JSON format `log.debug("Action", {slot})` instead of formating the text yourself `log.debug('slot=${slot}')`. -6. Include only relevant context in log messages, sufficient to debug the issue or action it refers to. - -Contributors must chose the log level carefully to ensure a consistent experience for every type of user: +- Avoid excessive logging. Log messages should be clear and concise, providing enough information to understand the context and severity of the issue. +- Do not log sensitive data, such as private keys, user credentials, or personal information. +- Do not log arbitrary data from the network as ASCII or UTF8 at levels higher or equal to `info`. +- Use clear and concise language. Prefer to log variables in JSON format `log.debug("Action", {slot})` instead of formatting the text yourself `log.debug('slot=${slot}')`. +- Include only relevant context in log messages, sufficient to debug the issue or action it refers to. ## Contributing to Grafana dashboards From 653feeab1bf509e514422aca9e9e003455d07380 Mon Sep 17 00:00:00 2001 From: dapplion <35266934+dapplion@users.noreply.github.com> Date: Tue, 4 Apr 2023 09:52:41 +0900 Subject: [PATCH 5/5] review PR --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bccc1330c783..e76e5a4ccdc5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -154,13 +154,12 @@ We're currently experimenting with hosting the majority of lodestar packages and ### Logging Levels -Contributors must chose the log level carefully to ensure a consistent experience for every type of user: +Contributors must choose the log level carefully to ensure a consistent experience for every type of user: - `error`: Critical issues that prevent the application from functioning correctly or cause significant disruption to users. Examples include failed network connections, crashes, or data corruption. - `warn`: Situations that may lead to critical issues if not addressed but do not prevent the application from functioning. Examples include configuration issues, deprecated features, or temporary network disruptions. - `info`: General sporadic informational about the node's state. Examples include initialization messages, infrequent periodic status updates, or high-level progress reports. - `debug`: Detailed diagnostic information that can help developers or users troubleshoot specific issues. Examples include individual request logs for every REST API, networking interactions, or internal components status changes. Alias to `verbose`. -- `trace`: Reserved for extremely verbose logs such a step by step execution traces of individual network packets or similar granular actions ### Logging guidelines