diff --git a/content/guides/troubleshooting.md b/content/guides/troubleshooting.md index 6bdaabbf85..2b41906c63 100644 --- a/content/guides/troubleshooting.md +++ b/content/guides/troubleshooting.md @@ -126,6 +126,54 @@ If you already have a stack trace but need to decode it, you can use the {{< /note >}} +## Adjusting Log Levels for Debugging + +When troubleshooting issues with your ESPHome device, increasing the log level can provide more detailed information about what's happening internally. This is particularly useful for diagnosing component-specific problems or understanding the data flow between components. + +### Setting Global Log Level + +To increase the verbosity of logs globally, adjust the `level` in your {{< docref "/components/logger" >}} configuration: + +```yaml +logger: + level: VERBOSE # or VERY_VERBOSE for maximum detail +``` + +Available log levels from least to most verbose: + +- `NONE` - No messages logged +- `ERROR` - Only errors +- `WARN` - Warnings and above +- `INFO` - Informational messages and above +- `DEBUG` - Debug messages and above (default) +- `VERBOSE` - Detailed debug messages and above +- `VERY_VERBOSE` - All internal messages including data bus traffic + +{{< warning >}} +Using `VERY_VERBOSE` can significantly slow down your device and may cause connectivity issues due to the volume of log messages generated. Use it only for short debugging sessions. +{{< /warning >}} + +### ESP-IDF Framework Log Level + +When using the ESP-IDF framework on {{< docref "/components/esp32" >}}, you can also adjust the framework's internal log level to get more detailed information from the underlying system: + +```yaml +esp32: + framework: + type: esp-idf + log_level: VERBOSE # Framework log level +``` + +Available ESP-IDF log levels: `NONE`, `ERROR` (default), `WARN`, `INFO`, `DEBUG`, `VERBOSE` + +### Component-Specific Log Levels + +You can also configure log levels for specific components to reduce noise or get more detail from individual components. See the {{< docref "/components/logger#manual-tag-specific-log-levels" "logger manual tag-specific log levels" >}} documentation for detailed information and examples. + +{{< important >}} +The global log level determines which messages are compiled into the binary. Component-specific log levels can only reduce verbosity, not increase it beyond the global level. For example, if the global level is `INFO`, setting a component to `DEBUG` will have no effect. +{{< /important >}} + ## Performance Troubleshooting If your device is experiencing performance issues such as: