@@ -208,15 +208,33 @@ Runtime logging affects the ongoing operation of your component:
208208
209209### 1. Use Appropriate Log Levels
210210
211+ We have macros to log messages at the following log levels:
212+
211213```cpp
212- ESP_LOGVV(TAG, "Detailed trace info"); // VERY_VERBOSE - Usually compiled out
213- ESP_LOGV(TAG, "Verbose information"); // VERBOSE - Detailed logging
214- ESP_LOGD(TAG, "Debug information"); // DEBUG - For development
215- ESP_LOGI(TAG, "Informational message"); // INFO - Important events
216- ESP_LOGW(TAG, "Warning condition"); // WARNING - Potential issues
217- ESP_LOGE(TAG, "Error occurred"); // ERROR - Definite problems
214+ ESP_LOGVV(TAG, "Detailed trace info"); // VERY_VERBOSE - Usually compiled out
215+ ESP_LOGV(TAG, "Verbose information"); // VERBOSE - Detailed logging for troubleshooting/commissioning
216+ ESP_LOGD(TAG, "Debug information"); // DEBUG - For development
217+ ESP_LOGI(TAG, "Informational message"); // INFO - Important user-facing events
218+ ESP_LOGW(TAG, "Warning condition"); // WARNING - Potential issues
219+ ESP_LOGE(TAG, "Error occurred"); // ERROR - Definite problems/unexpected behavior
218220```
219221
222+ In general, use:
223+
224+ - ` ESP_LOGVV ` to log detailed technical information, such as the content of data packets/messages being processed
225+ and/or processing state/status.
226+ - ` ESP_LOGV ` to log messages that don't normally need to be seen but may add value when troubleshooting or
227+ preparing/commissioning a new device/configuration.
228+ - ` ESP_LOGD ` to log messages that are necessary for normal use; we try to use it sparingly as, when it's too noisy, it
229+ becomes difficult to spot these and/or other important messages. Note that, as a project, we abuse this log level a
230+ bit; it's normally more verbose than "very verbose" but it is instead ESPHome's default log level and we treat it
231+ accordingly.
232+ - ` ESP_LOGI ` to log information that a non-tech-savvy user might want to see; this log level should not contain any
233+ technical detail that a normal, non-developer human would not be able to make sense of at a glance.
234+ - ` ESP_LOGW ` when something potentially bad happened, but we can likely continue without any real issues.
235+ - ` ESP_LOGE ` when something really bad happened and we cannot continue and/or unexpected behavior is likely to be the
236+ result of the failure.
237+
220238### 2. Avoid Logging in Tight Loops
221239
222240``` cpp
0 commit comments