Skip to content

Commit 8bf9623

Browse files
authored
[logging.md] Add log level explanations (#58)
1 parent de23bd0 commit 8bf9623

File tree

1 file changed

+24
-6
lines changed

1 file changed

+24
-6
lines changed

docs/architecture/logging.md

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -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

Comments
 (0)