日志组件

日志组件自动通过串口和 MQTT 主题（如果配置中有 MQTT 客户端）记录所有日志消息。默认情况下，所有严重级别为 DEBUG 或更高的日志都会显示。 提高日志级别严重性（例如到 INFO 或 WARN）可以帮助提高应用程序性能和内存大小。

NOTE

日志消息的”严重性”表示消息的重要性，即它的关键程度。严重级别在 日志级别 部分定义。

# 示例配置项
logger:
  level: DEBUG

配置变量

• baud_rate (Optional, int): 串行 UART 端口使用的波特率。 默认为 115200。设置为 0 可禁用通过 UART 的日志记录。

• level (Optional, string): 全局日志级别。任何较低严重性的日志消息 都不会显示。默认为 DEBUG。

• initial_level (Optional, string): 初始日志级别，可在运行时更改。默认为与 level 相同的值。

• logs (Optional, mapping): 手动设置特定 组件或标签的日志级别。请参阅 手动日志级别。

• runtime_tag_levels (Optional, boolean): 启用运行时按标签日志级别更改。当配置了 logs 或使用带有 tag 参数的 logger.set_level 时，这会自动启用。仅当从 lambda 或外部组件调用 set_log_level() 时才需要手动启用。默认为 false（根据需要自动启用）。

• id (Optional, ID): 手动指定用于代码生成的 ID。

高级设置：

• tx_buffer_size (Optional, int): 用于日志消息的缓冲区大小。 如果遇到内存问题，请减小此值。 默认为 512。

• task_log_buffer_size (Optional, int): 仅适用于 ESP32、LibreTiny 和 nRF52：用于任务日志消息的内部线程安全环形缓冲区大小。 这可以防止多个线程同时尝试记录日志时 API 断开连接。 设置为 0 可禁用日志缓冲区。默认为 768B。

• hardware_uart (Optional, string): 用于日志记录的硬件 UART。默认值取决于 您使用的特定处理器/芯片和框架。请参阅 下表。

• esp8266_store_log_strings_in_flash (Optional, boolean): 如果设置为 false，则禁用将 日志字符串存储在设备的闪存部分（使用更多内存）。默认为 true。

• on_message (Optional, Automation): 当要记录 消息时要执行的动作。变量 int level、const char* tag 和 const char* message 可用于 lambda 处理。

• deassert_rts_dtr (Optional, boolean): 使 ESPHome 在打开 串行日志连接后按顺序将 DTR 和 RTS 置为无效。默认为 false。 许多 ESP 板使用这些信号来重置芯片或进入 引导加载程序模式，设置此选项的效果是在打开串口后 在应用程序模式下重置芯片，从而确保捕获所有来自引导过程的日志消息。 注意：Deassert 通常意味着 TTL 高电平，因为 RTS/DTR 通常是低电平有效信号。

硬件 UART

日志组件使用平台特定的硬件 UART 进行串行日志记录。例如，ESP32 有三个硬件 UART，都可以用于发送和接收。ESP8266 只有两个 硬件 UART，其中一个是仅发送的。ESP8266 的 UART0 也可以”交换”到 CTS/RTS 引脚上的 TX/RX，以便您需要将 GPIO1 和 GPIO3 用于其他用途。

请注意，许多常见的板子将其 USB 转串口适配器固定到 UART0 使用的默认 GPIO， 因此如果您使用任何其他配置，您将无法通过板载 USB 获取日志消息。

默认 UART GPIO 引脚

变体	UART0	UART0_SWAP	UART1	UART2	USB_CDC	USB_SERIAL_JTAG
ESP8266	TX: 1, RX: 3	TX: 15, RX: 13	TX: 2, RX: N/A	N/A	N/A	N/A
ESP32	TX: 1, RX: 3	N/A	TX: 10, RX: 9	TX: 17, RX: 16	N/A	N/A
ESP32-C3	TX: 21, RX: 20	N/A	未定义	N/A	N/A	18/19
ESP32-C5	TX: 10, RX: 11	N/A	未定义	N/A	N/A	13/14
ESP32-C6	TX: 16, RX: 17	N/A	未定义	N/A	N/A	12/13
ESP32-C61	TX: 5, RX: 4	N/A	未定义	N/A	N/A	12/13
ESP32-P4	TX: 37, RX: 38	N/A	TX: 10, RX: 11	N/A	N/A	24/25
ESP32-S2	TX: 43, RX: 44	N/A	TX: 17, RX: 18	N/A	19/20	N/A
ESP32-S3	TX: 43, RX: 44	N/A	TX: 17, RX: 18	未定义	19/20	19/20
NRF52	引脚因板而异	N/A	引脚因板而异	未定义	D+/D-	N/A

未定义 表示日志组件目前无法使用此硬件 UART。

默认硬件接口

由于可用的板子和处理器/芯片种类繁多，我们为日志记录选择了不同的默认 硬件接口。许多基于 ESP32 变体（如 C3、S2 和 S3）的新板子使用 ESP 的板载 USB 硬件外设，而基于较旧处理器（如原始 ESP32 或 ESP8266）的板子继续使用 USB 转串口桥接 IC 进行通信。

变体	接口
ESP8266	UART0
ESP32	UART0
ESP32-C3	USB_SERIAL_JTAG
ESP32-C5	USB_SERIAL_JTAG
ESP32-C6	USB_SERIAL_JTAG
ESP32-C61	USB_SERIAL_JTAG
ESP32-P4	USB_SERIAL_JTAG
ESP32-S2	USB_CDC
ESP32-S3	USB_SERIAL_JTAG
RP2040	USB_CDC
NRF52	USB_CDC

日志级别

可能的日志级别（按严重性排序）：

级别	颜色	描述
NONE		不记录任何消息。
ERROR	红色	仅记录错误。错误会阻止 ESP 正常工作。
WARN	黄色	警告和错误。警告是可恢复的问题，如无效的传感器读数。
INFO	绿色	记录错误、警告和信息消息。
DEBUG（默认）	青色	包括调试在内的所有内容。包括传感器读数和状态消息。
VERBOSE	灰色	类似调试，但包括通常被视为垃圾的额外消息。
VERY_VERBOSE	白色	所有内部消息，包括流经 I²C、SPI 和 UART 总线的数据。

WARNING

使用 VERY_VERBOSE 可能会显著影响设备性能并可能导致连接不稳定。

手动标签特定日志级别

如果某个组件在日志中刷屏，您想调整其日志 级别，可以通过识别其标签在配置中设置其级别。

示例：全局详细日志，但减少 MQTT 噪音：

logger:
  level: VERBOSE
  logs:
    mqtt.component: DEBUG
    mqtt.client: ERROR

NOTE

当使用 logs 时，会自动启用运行时按标签日志级别支持。当此功能禁用时 （未配置 logs 时的默认值），日志组件会优化以获得更好的性能和减少内存使用。

level 选项控制固件中包含哪些日志语句。您不能将标签设置为比 全局级别更详细的级别，因为低于该严重性的日志语句不会被编译进去。 但是，您可以使用 initial_level 抑制它们，并为特定标签启用：

logger:
  level: VERBOSE
  initial_level: ERROR
  logs:
    wifi: VERBOSE

这里，VERBOSE 日志被编译，但不显示（因为 initial_level: ERROR） 但是，wifi 标签启用了 VERBOSE 级别，并会显示。

logger.log 动作

将格式化消息打印到日志。

在 format 选项中，您可以使用 printf 风格的格式化（请参阅 格式化文本）。

on_...:
  then:
    - logger.log: "Hello World"

    # 格式化：
    - logger.log:
        format: "温度传感器报告值 %.1f，湿度 %.1f"
        args: [ 'id(temperature_sensor).state', 'id(humidity_sensor).state' ]

配置选项：

• format (Required, string): printf 风格的消息格式。

• args (Optional, lambda 列表): 格式消息的可选参数。

• level (Optional, string): 打印消息的日志级别。 默认为 DEBUG。

• tag (Optional, string): 打印消息的标签（在日志中消息前面显示）。 默认为 main。

logger.set_level 动作

在运行时设置日志级别。级别只能设置为不低于全局日志级别的严重程度。

• level (Required, string): 要设置的新日志级别。
• tag (Optional, string): 要为其设置日志级别的标签。如果未设置，将设置全局日志级别。

on_...:
  then:
    - logger.set_level: INFO

    - logger.set_level:
        level: DEBUG
        tag: mqtt.client

NOTE

当使用带有 tag 参数的 logger.set_level 时，会自动启用运行时按标签日志级别支持。 如果您需要直接从 lambda 或外部组件调用 set_log_level()，必须手动启用 日志配置中的 runtime_tag_levels: true。

日志自动化

on_message

当日志中添加新消息时，此自动化将被触发。 在 lambda 中，您可以从触发器获取消息、日志级别和标签， 使用 message（const char *）、level（int）和 tag（const char *）。

logger:
  # ...
  on_message:
    level: ERROR
    then:
      - mqtt.publish:
          topic: some/topic
          payload: !lambda |-
            return "触发 on_message，级别 " + to_string(level) + "，标签 " + tag + "，消息 " + message;

NOTE

日志记录在 on_message 触发器中不起作用。您不能在此自动化中使用 logger.log 动作 和 ESP_LOGx 日志宏。

另见

• UART 总线
• 日志选择器
• 故障排除 - 调试崩溃和启动失败的故障排除指南
• API Reference: logger.h