From 2c877bae806bf215e6e8ba522f679444bf282ca0 Mon Sep 17 00:00:00 2001 From: Kevin Heifner Date: Fri, 23 Sep 2022 14:08:17 -0500 Subject: [PATCH 1/6] GH-209 Add information about log levels --- .../01_nodeos/06_logging/01_logging-levels.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/01_nodeos/06_logging/01_logging-levels.md b/docs/01_nodeos/06_logging/01_logging-levels.md index bb68ceeeb1..637473ede5 100644 --- a/docs/01_nodeos/06_logging/01_logging-levels.md +++ b/docs/01_nodeos/06_logging/01_logging-levels.md @@ -64,3 +64,43 @@ Sample `logging.json`: ] } ``` + +## Expected output of debug levels + +* `error` + * Log output that likely requires operator intervention. Error level logging should + be reserved for conditions that are completely unexpected or otherwise needs human + intervention. Currently, there are numerous `error` level logging that likely should + be `warn` as they do not require human intervention. The `net_plugin_impl`, for + example, has a number of `error` level logs for bad network connections. This is + handled and processed correctly. These should be changed to `warn` or `info`. +* `warn` + * Log output indicating unexpected but recoverable errors. Although, `warn` level + typically does not require human intervention, repeated output of `warn` + level logs may indicate action is needed by an operator. `warn` should not be used + for simply conveying information. A `warn` level log is something to take notice + of, but not necessarily be concerned about. +* `info` (default) + * Log output that provides useful information to an operator. Can just be progress + indication or other useful data to a user. Care is taken not to create excessive + log output with `info` level logging. For example, no `info` level logging should + be produced for every transaction. For progress indication, some multiple of + transactions should be processed between each log output; typically, every 1000 + transactions. +* `debug` + * Useful log output for when non-default logging is enabled. Answers the question: + is this useful information for a user that is monitoring the log output. Care + should be taken to not create excessive log output; similar to `info` level + logging. `debug` level should not be used for `trace` level logging. Enabling + `debug` level logging should provide greater insight into behavior without + overwhelming the output with log entries. Like `info`, no `debug` level + logging should be produced for every transaction. There are specific + transaction level loggers dedicated to transaction level logging: `transaction`, + `transaction_trace_failure`, `transaction_trace_success`, `transaction_failure_tracing`, + `transaction_success_tracing`. +* `all` (trace) + * `all` level logging is for logging that would be overwhelming if it was `debug` + level logging. Only used in a few places and not completely supported. In the + future a different logging library may provide better trace level logging support. + The current logging framework is not performant enough to enable excess trace + level output. \ No newline at end of file From 954ee42233ee4f42b355a41ca58e72d09344e9dd Mon Sep 17 00:00:00 2001 From: Kevin Heifner Date: Fri, 23 Sep 2022 14:10:32 -0500 Subject: [PATCH 2/6] GH-209 log levels not debug levels --- docs/01_nodeos/06_logging/01_logging-levels.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/01_nodeos/06_logging/01_logging-levels.md b/docs/01_nodeos/06_logging/01_logging-levels.md index 637473ede5..97fe09c489 100644 --- a/docs/01_nodeos/06_logging/01_logging-levels.md +++ b/docs/01_nodeos/06_logging/01_logging-levels.md @@ -65,7 +65,7 @@ Sample `logging.json`: } ``` -## Expected output of debug levels +## Expected output of log levels * `error` * Log output that likely requires operator intervention. Error level logging should From dec785155c425f664561b10b4edbdcd3a1681465 Mon Sep 17 00:00:00 2001 From: Kevin Heifner Date: Fri, 23 Sep 2022 14:33:47 -0500 Subject: [PATCH 3/6] GH-209 PR feedback --- docs/01_nodeos/06_logging/01_logging-levels.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/01_nodeos/06_logging/01_logging-levels.md b/docs/01_nodeos/06_logging/01_logging-levels.md index 97fe09c489..cd69de334e 100644 --- a/docs/01_nodeos/06_logging/01_logging-levels.md +++ b/docs/01_nodeos/06_logging/01_logging-levels.md @@ -70,10 +70,13 @@ Sample `logging.json`: * `error` * Log output that likely requires operator intervention. Error level logging should be reserved for conditions that are completely unexpected or otherwise needs human - intervention. Currently, there are numerous `error` level logging that likely should - be `warn` as they do not require human intervention. The `net_plugin_impl`, for - example, has a number of `error` level logs for bad network connections. This is - handled and processed correctly. These should be changed to `warn` or `info`. + intervention. Also used to indicate a software error like impossible values of an + `enum`, out of bounds array access, null pointers, or other conditions that likely + will throw an exception. Currently, there are numerous `error` level logging + that likely should be `warn` as they do not require human intervention. The + `net_plugin_impl`, for example, has a number of `error` level logs for bad network + connections. This is handled and processed correctly. These should be changed + to `warn` or `info`. * `warn` * Log output indicating unexpected but recoverable errors. Although, `warn` level typically does not require human intervention, repeated output of `warn` From 873c2b9dc19cc59bca22b1df0bce9c5f8d3c2856 Mon Sep 17 00:00:00 2001 From: Luis Date: Thu, 29 Sep 2022 10:11:51 -0400 Subject: [PATCH 4/6] remove line wraps, no need for docs :doc --- .../01_nodeos/06_logging/01_logging-levels.md | 40 +++---------------- 1 file changed, 5 insertions(+), 35 deletions(-) diff --git a/docs/01_nodeos/06_logging/01_logging-levels.md b/docs/01_nodeos/06_logging/01_logging-levels.md index cd69de334e..c2e404b1d0 100644 --- a/docs/01_nodeos/06_logging/01_logging-levels.md +++ b/docs/01_nodeos/06_logging/01_logging-levels.md @@ -68,42 +68,12 @@ Sample `logging.json`: ## Expected output of log levels * `error` - * Log output that likely requires operator intervention. Error level logging should - be reserved for conditions that are completely unexpected or otherwise needs human - intervention. Also used to indicate a software error like impossible values of an - `enum`, out of bounds array access, null pointers, or other conditions that likely - will throw an exception. Currently, there are numerous `error` level logging - that likely should be `warn` as they do not require human intervention. The - `net_plugin_impl`, for example, has a number of `error` level logs for bad network - connections. This is handled and processed correctly. These should be changed - to `warn` or `info`. + * Log output that likely requires operator intervention. Error level logging should be reserved for conditions that are completely unexpected or otherwise needs human intervention. Also used to indicate a software error like impossible values of an `enum`, out of bounds array access, null pointers, or other conditions that likely will throw an exception. Currently, there are numerous `error` level logging that likely should be `warn` as they do not require human intervention. The `net_plugin_impl`, for example, has a number of `error` level logs for bad network connections. This is handled and processed correctly. These should be changed to `warn` or `info`. * `warn` - * Log output indicating unexpected but recoverable errors. Although, `warn` level - typically does not require human intervention, repeated output of `warn` - level logs may indicate action is needed by an operator. `warn` should not be used - for simply conveying information. A `warn` level log is something to take notice - of, but not necessarily be concerned about. + * Log output indicating unexpected but recoverable errors. Although, `warn` level typically does not require human intervention, repeated output of `warn` level logs may indicate action is needed by an operator. `warn` should not be used for simply conveying information. A `warn` level log is something to take notice of, but not necessarily be concerned about. * `info` (default) - * Log output that provides useful information to an operator. Can just be progress - indication or other useful data to a user. Care is taken not to create excessive - log output with `info` level logging. For example, no `info` level logging should - be produced for every transaction. For progress indication, some multiple of - transactions should be processed between each log output; typically, every 1000 - transactions. + * Log output that provides useful information to an operator. Can just be progress indication or other useful data to a user. Care is taken not to create excessive log output with `info` level logging. For example, no `info` level logging should be produced for every transaction. For progress indication, some multiple of transactions should be processed between each log output; typically, every 1000 transactions. * `debug` - * Useful log output for when non-default logging is enabled. Answers the question: - is this useful information for a user that is monitoring the log output. Care - should be taken to not create excessive log output; similar to `info` level - logging. `debug` level should not be used for `trace` level logging. Enabling - `debug` level logging should provide greater insight into behavior without - overwhelming the output with log entries. Like `info`, no `debug` level - logging should be produced for every transaction. There are specific - transaction level loggers dedicated to transaction level logging: `transaction`, - `transaction_trace_failure`, `transaction_trace_success`, `transaction_failure_tracing`, - `transaction_success_tracing`. + * Useful log output for when non-default logging is enabled. Answers the question: is this useful information for a user that is monitoring the log output. Care should be taken to not create excessive log output; similar to `info` level logging. `debug` level should not be used for `trace` level logging. Enabling `debug` level logging should provide greater insight into behavior without overwhelming the output with log entries. Like `info`, no `debug` level logging should be produced for every transaction. There are specific transaction level loggers dedicated to transaction level logging: `transaction`, `transaction_trace_failure`, `transaction_trace_success`, `transaction_failure_tracing`, `transaction_success_tracing`. * `all` (trace) - * `all` level logging is for logging that would be overwhelming if it was `debug` - level logging. Only used in a few places and not completely supported. In the - future a different logging library may provide better trace level logging support. - The current logging framework is not performant enough to enable excess trace - level output. \ No newline at end of file + * `all` level logging is for logging that would be overwhelming if it was `debug` level logging. Only used in a few places and not completely supported. In the future a different logging library may provide better trace level logging support. The current logging framework is not performant enough to enable excess trace level output. From 0c203a7c14a5e85aea4b574ea3aff2e90b0b4051 Mon Sep 17 00:00:00 2001 From: Luis Date: Thu, 29 Sep 2022 10:49:30 -0400 Subject: [PATCH 5/6] make first sentence summary for each log level :doc --- .../01_nodeos/06_logging/01_logging-levels.md | 20 +++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/01_nodeos/06_logging/01_logging-levels.md b/docs/01_nodeos/06_logging/01_logging-levels.md index c2e404b1d0..5f4314eef4 100644 --- a/docs/01_nodeos/06_logging/01_logging-levels.md +++ b/docs/01_nodeos/06_logging/01_logging-levels.md @@ -67,13 +67,13 @@ Sample `logging.json`: ## Expected output of log levels -* `error` - * Log output that likely requires operator intervention. Error level logging should be reserved for conditions that are completely unexpected or otherwise needs human intervention. Also used to indicate a software error like impossible values of an `enum`, out of bounds array access, null pointers, or other conditions that likely will throw an exception. Currently, there are numerous `error` level logging that likely should be `warn` as they do not require human intervention. The `net_plugin_impl`, for example, has a number of `error` level logs for bad network connections. This is handled and processed correctly. These should be changed to `warn` or `info`. -* `warn` - * Log output indicating unexpected but recoverable errors. Although, `warn` level typically does not require human intervention, repeated output of `warn` level logs may indicate action is needed by an operator. `warn` should not be used for simply conveying information. A `warn` level log is something to take notice of, but not necessarily be concerned about. -* `info` (default) - * Log output that provides useful information to an operator. Can just be progress indication or other useful data to a user. Care is taken not to create excessive log output with `info` level logging. For example, no `info` level logging should be produced for every transaction. For progress indication, some multiple of transactions should be processed between each log output; typically, every 1000 transactions. -* `debug` - * Useful log output for when non-default logging is enabled. Answers the question: is this useful information for a user that is monitoring the log output. Care should be taken to not create excessive log output; similar to `info` level logging. `debug` level should not be used for `trace` level logging. Enabling `debug` level logging should provide greater insight into behavior without overwhelming the output with log entries. Like `info`, no `debug` level logging should be produced for every transaction. There are specific transaction level loggers dedicated to transaction level logging: `transaction`, `transaction_trace_failure`, `transaction_trace_success`, `transaction_failure_tracing`, `transaction_success_tracing`. -* `all` (trace) - * `all` level logging is for logging that would be overwhelming if it was `debug` level logging. Only used in a few places and not completely supported. In the future a different logging library may provide better trace level logging support. The current logging framework is not performant enough to enable excess trace level output. +* `error` - Log output that likely requires operator intervention. + * Error level logging should be reserved for conditions that are completely unexpected or otherwise needs human intervention. Also used to indicate a software error like impossible values of an `enum`, out of bounds array access, null pointers, or other conditions that likely will throw an exception. Currently, there are numerous `error` level logging that likely should be `warn` as they do not require human intervention. The `net_plugin_impl`, for example, has a number of `error` level logs for bad network connections. This is handled and processed correctly. These should be changed to `warn` or `info`. +* `warn` - Log output indicating unexpected but recoverable errors. + * Although, `warn` level typically does not require human intervention, repeated output of `warn` level logs may indicate action is needed by an operator. `warn` should not be used for simply conveying information. A `warn` level log is something to take notice of, but not necessarily be concerned about. +* `info` (default) - Log output that provides useful information to an operator. + * Can just be progress indication or other useful data to a user. Care is taken not to create excessive log output with `info` level logging. For example, no `info` level logging should be produced for every transaction. For progress indication, some multiple of transactions should be processed between each log output; typically, every 1000 transactions. +* `debug` - Useful log output for when non-default logging is enabled. + * Answers the question: is this useful information for a user that is monitoring the log output. Care should be taken to not create excessive log output; similar to `info` level logging. `debug` level should not be used for `trace` level logging. Enabling `debug` level logging should provide greater insight into behavior without overwhelming the output with log entries. Like `info`, no `debug` level logging should be produced for every transaction. There are specific transaction level loggers dedicated to transaction level logging: `transaction`, `transaction_trace_failure`, `transaction_trace_success`, `transaction_failure_tracing`, `transaction_success_tracing`. +* `all` (trace) - For logging that would be overwhelming if `debug` level logging were used. + * Only used in a few places and not completely supported. In the future a different logging library may provide better trace level logging support. The current logging framework is not performant enough to enable excess trace level output. From 2f201f4590cff78ce53f43061d00dbaf1633b65f Mon Sep 17 00:00:00 2001 From: Luis Date: Thu, 29 Sep 2022 11:09:50 -0400 Subject: [PATCH 6/6] split log level info into bullets and minor edits :doc --- .../01_nodeos/06_logging/01_logging-levels.md | 20 +++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/01_nodeos/06_logging/01_logging-levels.md b/docs/01_nodeos/06_logging/01_logging-levels.md index 5f4314eef4..ecf99c59b4 100644 --- a/docs/01_nodeos/06_logging/01_logging-levels.md +++ b/docs/01_nodeos/06_logging/01_logging-levels.md @@ -65,15 +65,23 @@ Sample `logging.json`: } ``` -## Expected output of log levels +## Expected Output of Log Levels * `error` - Log output that likely requires operator intervention. - * Error level logging should be reserved for conditions that are completely unexpected or otherwise needs human intervention. Also used to indicate a software error like impossible values of an `enum`, out of bounds array access, null pointers, or other conditions that likely will throw an exception. Currently, there are numerous `error` level logging that likely should be `warn` as they do not require human intervention. The `net_plugin_impl`, for example, has a number of `error` level logs for bad network connections. This is handled and processed correctly. These should be changed to `warn` or `info`. + - Error level logging should be reserved for conditions that are completely unexpected or otherwise need human intervention. + - Also used to indicate software errors such as: impossible values for an `enum`, out of bounds array access, null pointers, or other conditions that likely will throw an exception. + - *Note*: Currently, there are numerous `error` level logging that likely should be `warn` as they do not require human intervention. The `net_plugin_impl`, for example, has a number of `error` level logs for bad network connections. This is handled and processed correctly. These should be changed to `warn` or `info`. * `warn` - Log output indicating unexpected but recoverable errors. - * Although, `warn` level typically does not require human intervention, repeated output of `warn` level logs may indicate action is needed by an operator. `warn` should not be used for simply conveying information. A `warn` level log is something to take notice of, but not necessarily be concerned about. + - Although, `warn` level typically does not require human intervention, repeated output of `warn` level logs might indicate actions needed by an operator. + - `warn` should not be used simply for conveying information. A `warn` level log is something to take notice of, but not necessarily be concerned about. * `info` (default) - Log output that provides useful information to an operator. - * Can just be progress indication or other useful data to a user. Care is taken not to create excessive log output with `info` level logging. For example, no `info` level logging should be produced for every transaction. For progress indication, some multiple of transactions should be processed between each log output; typically, every 1000 transactions. + - Can be just progress indication or other useful data to a user. Care is taken not to create excessive log output with `info` level logging. For example, no `info` level logging should be produced for every transaction. + - For progress indication, some multiple of transactions should be processed between each log output; typically, every 1000 transactions. * `debug` - Useful log output for when non-default logging is enabled. - * Answers the question: is this useful information for a user that is monitoring the log output. Care should be taken to not create excessive log output; similar to `info` level logging. `debug` level should not be used for `trace` level logging. Enabling `debug` level logging should provide greater insight into behavior without overwhelming the output with log entries. Like `info`, no `debug` level logging should be produced for every transaction. There are specific transaction level loggers dedicated to transaction level logging: `transaction`, `transaction_trace_failure`, `transaction_trace_success`, `transaction_failure_tracing`, `transaction_success_tracing`. + - Answers the question: is this useful information for a user that is monitoring the log output. Care should be taken not to create excessive log output; similar to `info` level logging. + - Enabling `debug` level logging should provide greater insight into behavior without overwhelming the output with log entries. + - `debug` level should not be used for *trace* level logging; to that end, use `all` (see below). + - Like `info`, no `debug` level logging should be produced for every transaction. There are specific transaction level loggers dedicated to transaction level logging: `transaction`, `transaction_trace_failure`, `transaction_trace_success`, `transaction_failure_tracing`, `transaction_success_tracing`. * `all` (trace) - For logging that would be overwhelming if `debug` level logging were used. - * Only used in a few places and not completely supported. In the future a different logging library may provide better trace level logging support. The current logging framework is not performant enough to enable excess trace level output. + - Can be used for trace level logging. Only used in a few places and not completely supported. + - *Note*: In the future a different logging library may provide better trace level logging support. The current logging framework is not performant enough to enable excess trace level output.