From 215cab561937b90660cc6b1749d8a3f8c4356e4e Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Tue, 12 Aug 2025 14:09:41 -0500 Subject: [PATCH 1/2] [troubleshooting] Add log level adjustment documentation --- guides/troubleshooting.rst | 52 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/guides/troubleshooting.rst b/guides/troubleshooting.rst index dfc9d362aa..5365d2da21 100644 --- a/guides/troubleshooting.rst +++ b/guides/troubleshooting.rst @@ -112,6 +112,58 @@ If you already have a stack trace but need to decode it, you can use the `ESP St This tool runs entirely in your browser - no data is sent to any server, ensuring your firmware and debug information remain private. +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 :doc:`logger ` configuration: + +.. code-block:: 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. + +ESP-IDF Framework Log Level +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When using the ESP-IDF framework on :doc:`ESP32 `, you can also adjust the framework's internal log level to get more detailed information from the underlying system: + +.. code-block:: 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 :ref:`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. + Performance Troubleshooting --------------------------- From fd23a55d7253106875a384e2330e6f86472da2f9 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Thu, 21 Aug 2025 09:17:54 -0500 Subject: [PATCH 2/2] merge docs --- content/guides/troubleshooting.md | 48 +++++++++++++++++++++++++++++++ esp32_phy_docs_pr.md | 24 ---------------- esp32_s2_docs_pr.md | 19 ------------ idf_ota_web_server_docs_pr.md | 17 ----------- runtime_stats_docs_pr.md | 36 ----------------------- troubleshooting_with_logs_pr.md | 23 --------------- 6 files changed, 48 insertions(+), 119 deletions(-) delete mode 100644 esp32_phy_docs_pr.md delete mode 100644 esp32_s2_docs_pr.md delete mode 100644 idf_ota_web_server_docs_pr.md delete mode 100644 runtime_stats_docs_pr.md delete mode 100644 troubleshooting_with_logs_pr.md 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: diff --git a/esp32_phy_docs_pr.md b/esp32_phy_docs_pr.md deleted file mode 100644 index 1f2d2a886b..0000000000 --- a/esp32_phy_docs_pr.md +++ /dev/null @@ -1,24 +0,0 @@ -## Description: - -Adds documentation for the new `preferred_phy` configuration option in the `esp32_ble` component. - -This documentation explains: -- The new PHY configuration option with its three modes (1m, 2m, auto) -- Why 1M PHY is now the default (compatibility and reliability) -- Platform restrictions (2M PHY only available on ESP32-C3/S3/C6/H2) -- Practical guidance on when to use different PHY modes -- The connection issues that can occur with 2M PHY when WiFi is active - -**Related issue (if applicable):** fixes esphome/issues#[BLE disconnection issues with ESP32-S3] - -**Pull request in [esphome](https://github.com/esphome/esphome) with YAML changes (if applicable):** - -- esphome/esphome#9968 - -## Checklist: - - - [x] I am merging into `next` because this is new documentation that has a matching pull-request in [esphome](https://github.com/esphome/esphome) as linked above. - or - - [ ] I am merging into `current` because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature. - - - [ ] Link added in `/components/index.rst` when creating new documents for new components or cookbook. \ No newline at end of file diff --git a/esp32_s2_docs_pr.md b/esp32_s2_docs_pr.md deleted file mode 100644 index 91b0f43824..0000000000 --- a/esp32_s2_docs_pr.md +++ /dev/null @@ -1,19 +0,0 @@ -## Description: - -Add ESP32-S2/S3 touch configuration guidance and working example - -This PR improves the ESP32 touch documentation by adding a prominent info box that explains the critical timing differences between original ESP32 and S2/S3 variants. The default `measurement_duration` value of 8ms (optimized for original ESP32) often prevents touch detection from working on S2/S3 variants entirely. This documentation update provides a working configuration example with appropriate timing values that have been found to work across many S2/S3 devices. - -**Related issue (if applicable):** fixes - -**Pull request in [esphome](https://github.com/esphome/esphome) with YAML changes (if applicable):** - -- esphome/esphome#9059 - -## Checklist: - - - [ ] I am merging into `next` because this is new documentation that has a matching pull-request in [esphome](https://github.com/esphome/esphome) as linked above. - or - - [x] I am merging into `current` because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature. - - - [ ] Link added in `/components/index.rst` when creating new documents for new components or cookbook. \ No newline at end of file diff --git a/idf_ota_web_server_docs_pr.md b/idf_ota_web_server_docs_pr.md deleted file mode 100644 index af51e5564b..0000000000 --- a/idf_ota_web_server_docs_pr.md +++ /dev/null @@ -1,17 +0,0 @@ -## Description: - -Remove ESP-IDF framework limitation for web_server OTA feature. OTA functionality is now available when using the ESP-IDF framework with the web_server component. - -**Related issue (if applicable):** fixes - -**Pull request in [esphome](https://github.com/esphome/esphome) with YAML changes (if applicable):** - -- esphome/esphome#9264 - -## Checklist: - - - [ ] I am merging into `next` because this is new documentation that has a matching pull-request in [esphome](https://github.com/esphome/esphome) as linked above. - or - - [x] I am merging into `current` because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature. - - - [ ] Link added in `/components/index.rst` when creating new documents for new components or cookbook. \ No newline at end of file diff --git a/runtime_stats_docs_pr.md b/runtime_stats_docs_pr.md deleted file mode 100644 index a58905d4a9..0000000000 --- a/runtime_stats_docs_pr.md +++ /dev/null @@ -1,36 +0,0 @@ -# Add documentation for runtime_stats component - -## Summary - -This PR adds documentation for the new `runtime_stats` component that helps developers debug performance issues and identify components blocking the event loop. - -## Related ESPHome PR - -- esphome/esphome#[PR number] - Add runtime_stats component for performance debugging and analysis - -## Changes - -- Added `components/runtime_stats.rst` with comprehensive documentation including: - - Component description and use cases - - Configuration options - - Understanding the output format - - Example configurations and output - - Tips for effective usage - - Important notes about millisecond resolution and performance overhead - -## Key points documented - -- The component is intended for debugging and troubleshooting -- Can be temporarily enabled in production but should not be left running long-term -- Uses millisecond resolution (millis()) so cannot measure sub-millisecond operations -- Provides both period and total statistics -- Components are sorted by execution time to highlight performance bottlenecks - -## Preview - -The documentation includes: -- Clear warnings about performance overhead -- Example YAML configuration -- Sample output with explanation -- Use cases for different debugging scenarios -- Best practices for using the component effectively \ No newline at end of file diff --git a/troubleshooting_with_logs_pr.md b/troubleshooting_with_logs_pr.md deleted file mode 100644 index 9be3e3d9fe..0000000000 --- a/troubleshooting_with_logs_pr.md +++ /dev/null @@ -1,23 +0,0 @@ -## Description: - -Add documentation for adjusting log levels when troubleshooting ESPHome devices. This includes: -- Setting global log levels (with link to logger component) -- Using VERBOSE and VERY_VERBOSE levels for debugging -- Configuring ESP-IDF framework log levels for ESP32 -- Component-specific log level configuration - -**Related issue (if applicable):** N/A - -**Pull request in [esphome](https://github.com/esphome/esphome) with YAML changes (if applicable):** N/A - -## Checklist: - - - [ ] I am merging into `next` because this is new documentation that has a matching pull-request in [esphome](https://github.com/esphome/esphome) as linked above. - or - - [x] I am merging into `current` because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature. - - - [ ] Link added in `/components/index.rst` when creating new documents for new components or cookbook. - ---- - -**Suggested PR Title:** `[troubleshooting] Add log level adjustment documentation` \ No newline at end of file