From 9e7cad2f9d81cb188b72f01a816f0be3ca448dcd Mon Sep 17 00:00:00 2001 From: kbx81 Date: Mon, 15 Sep 2025 15:14:06 -0500 Subject: [PATCH 1/2] [logging best practices] Add log level explanations --- docs/architecture/logging.md | 30 ++++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/docs/architecture/logging.md b/docs/architecture/logging.md index 1720fc9..cd8709d 100644 --- a/docs/architecture/logging.md +++ b/docs/architecture/logging.md @@ -208,15 +208,33 @@ Runtime logging affects the ongoing operation of your component: ### 1. Use Appropriate Log Levels +We have macros to log messages at the following log levels + ```cpp -ESP_LOGVV(TAG, "Detailed trace info"); // VERY_VERBOSE - Usually compiled out -ESP_LOGV(TAG, "Verbose information"); // VERBOSE - Detailed logging -ESP_LOGD(TAG, "Debug information"); // DEBUG - For development -ESP_LOGI(TAG, "Informational message"); // INFO - Important events -ESP_LOGW(TAG, "Warning condition"); // WARNING - Potential issues -ESP_LOGE(TAG, "Error occurred"); // ERROR - Definite problems +ESP_LOGVV(TAG, "Detailed trace info"); // VERY_VERBOSE - Usually compiled out +ESP_LOGV(TAG, "Verbose information"); // VERBOSE - Detailed logging for troubleshooting/commissioning +ESP_LOGD(TAG, "Debug information"); // DEBUG - For development +ESP_LOGI(TAG, "Informational message"); // INFO - Important user-facing events +ESP_LOGW(TAG, "Warning condition"); // WARNING - Potential issues +ESP_LOGE(TAG, "Error occurred"); // ERROR - Definite problems/unexpected behavior ``` +In general, use: + +- `ESP_LOGVV` to log detailed technical information, such as the content of data packets/messages being processed + and/or processing state/status. +- `ESP_LOGV` to log messages that don't normally need to be seen but may add value when troubleshooting or + preparing/commissioning a new device/configuration. +- `ESP_LOGD` to log messages that are necessary for normal use; we try to use it sparingly as, when it's too noisy, it + becomes difficult to spot these and/or other important messages. Note that, as a project, we abuse this log level a + bit; it's normally more verbose than "very verbose" but it is instead ESPHome's default log level and we treat it + accordingly. +- `ESP_LOGI` to log information that a non-tech-savvy user might want to see; this log level should not contain any + technical detail that a normal, non-developer human would not be able to make sense of at a glance. +- `ESP_LOGW` when something potentially bad happened, but we can likely continue without any real issues. +- `ESP_LOGE` when something really bad happened and we cannot continue and/or unexpected behavior is likely to be the + result of the failure. + ### 2. Avoid Logging in Tight Loops ```cpp From 400ed67da3989db0c2c3a85d4ff9841d2659c359 Mon Sep 17 00:00:00 2001 From: Keith Burzinski Date: Mon, 15 Sep 2025 15:15:32 -0500 Subject: [PATCH 2/2] Update docs/architecture/logging.md --- docs/architecture/logging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/architecture/logging.md b/docs/architecture/logging.md index cd8709d..af6be86 100644 --- a/docs/architecture/logging.md +++ b/docs/architecture/logging.md @@ -208,7 +208,7 @@ Runtime logging affects the ongoing operation of your component: ### 1. Use Appropriate Log Levels -We have macros to log messages at the following log levels +We have macros to log messages at the following log levels: ```cpp ESP_LOGVV(TAG, "Detailed trace info"); // VERY_VERBOSE - Usually compiled out