Logging Overview

Logging is an important function for both ESPHome developers and users alike. This functionality is enabled when the logger component is added to an ESPHome device configuration:

# Example: changing default log level for all components
logger:
  level: VERBOSE

# Example: VERBOSE for just `bmp581_base`; other components stay at DEBUG
logger:
  level: VERBOSE
  initial_level: DEBUG
  logs:
    bmp581_base: VERBOSE

Log messages can be retrieved over the device’s hardware serial port or UART interface (if configured), over the network API (if network is configured), and MQTT (if both network and MQTT are configured).

ESP_LOG Macro

The ESP_LOG macro is available to perform all of the necessary log functions in a space- and processing-efficient manner. The macro has the following signature (using the DEBUG log level):

ESP_LOGD(TAG, format, ...)

TAG is declared once per source file with ESPHOME_LOG_TAG (see declaring the log tag). format is a printf-style format string, and any values used to format the string are passed as the subsequent variadic arguments.

A full example of a VERBOSE log message:

// At namespace scope in the component's .cpp file
ESPHOME_LOG_TAG(TAG, "component_name");
// ...
ESP_LOGV(TAG, "Received data: %d", recv_data);

If logging over multiple lines, combine into a single log message (see best practices for more information):

ESP_LOGV(TAG,
         "Device properties updated:\n"
         "  Address: 0x%02X\n"
         "  Update Interval: %ums\n"
         "  Samples: %d\n"
         "  Mode: %s",
         this->address_,
         this->update_interval_,
         this->samples_,
         this->get_mode_str());

Log Levels

ESPHome has six runtime log levels, from ERROR to VERY_VERBOSE. In increasing order of verbosity, the levels are:

• ERROR (ESP_LOGE()): Indicates problems that prevent the ESPHome device from working correctly.
• WARN (ESP_LOGW()): Warnings are recoverable issues like invalid sensor readings.
• INFO (ESP_LOGI()): Informational messages that may be useful to a non-technically savvy user, such as detected serial numbers.
• DEBUG (ESP_LOGD()): Diagnostic detail useful when developing or troubleshooting a component; this is the default level.
• VERBOSE (ESP_LOGV()): Messages that don’t normally need to be seen but may add value when troubleshooting or preparing/commissioning a new device/configuration.
• VERY_VERBOSE (ESP_LOGVV()): Detailed technical information, such as the content of data packets/messages being processed and/or processing state/status.

In addition, ESPHome also has a configuration logging macro, ESP_LOGCONFIG(), which logs at the CONFIG level (between INFO and DEBUG) and is typically only used in a component’s dump_config() function. When developing your own component, remember to implement dump_config() and output relevant configuration options.

By default (DEBUG), ERROR, WARN, INFO, CONFIG (ESP_LOGCONFIG), and DEBUG level messages are logged. To see more verbose messages, set the logger component’s level to VERBOSE or VERY_VERBOSE; per-tag levels under logs cannot be more verbose than this global level. Messages above the configured level are compiled out, so you must recompile and reflash the firmware onto the device before the change takes effect.

Obtaining Log Data

Use esphome logs with the device’s configuration file to stream real-time logs from a running ESPHome device over serial, the ESPHome network API, or MQTT:

esphome logs path/to/configuration.yaml

If both network and serial connections for a single device are available, or if multiple devices are connected over serial, esphome will give you a choice of connection. You can automatically select the correct device using the --device flag:

esphome logs --device 192.168.1.111 path/to/configuration.yaml
esphome logs --device /dev/ttyACM1 path/to/configuration.yaml
esphome logs --device COM3 path/to/configuration.yaml

To publish ESPHome log messages to MQTT, you must configure MQTT with a log_topic configuration option:

mqtt:
  log_topic: my-device/logs

IMPORTANT

Missing Logs over the Network API or MQTT

Some problems may be difficult to troubleshoot when using the Network API or MQTT logs, either due to the errors occurring well before the device network stack is initialized, or if the network stack itself is causing an issue. If you are unable to retrieve relevant logs due to network startup, you may need to use hardware serial to obtain logs.

To retrieve logs over serial, you can either configure your hardware’s USB CDC if it has such hardware, or configure your device to use specific UART pins, which you can then connect to your computer using:

• A dedicated USB to UART adapter, such as one based on a CP2102, CH340 or FTDI chip, or an ESP-PROG for ESP32, or
• An RP2040 Debug Probe or another RP2040 device such as a Raspberry Pi Pico loaded with debug probe firmware. This will work for any UART-capable ESPHome device, not just RP2040 devices.

If your logs look garbled when using a serial connection, make sure that your PC UART interface baud rate is the same baud rate as your ESPHome device UART (default is 115200), and that both your interface and device have a shared ground connection.

Logging Best Practices

Review the logging best practices guide. In general, keep log messages short and to the point in order to avoid using too much processing power and network resources, and also to avoid overwhelming users and developers. Also remember to output your component’s configuration using ESP_LOGCONFIG() in your component’s dump_config() function.