ESP-IDF 日志库(Logging Library)完全指南:Log V1/V2、日志级别控制、格式化与二进制日志

原创2026-09-16 10:00:132,268 阅读
文章标签:物联网嵌入式嵌入式OSRTOS固件驱动开发硬件开发网络蓝牙IoT协议系统编程认证鉴权

ESP-IDF 日志库(Logging Library)完全指南:Log V1/V2、日志级别控制、格式化与二进制日志

导读

ESP-IDF 内置了一套灵活可配置的日志系统,通过 CONFIG_LOG_VERSION 可在 Log V1 与 Log V2 两种实现间切换。本文以官方文档 docs/en/api-reference/system/log.rst 为主线,结合 components/log 组件的源码与 Kconfig 配置,系统讲解两种日志版本的设计差异、六档日志级别、编译期与运行期级别控制、格式化选项、缓冲区日志与二进制日志的编解码流程,并给出可直接落地的代码示例与性能数据。读完本文,你将能够按需选型日志版本、精细控制每个模块的日志输出,甚至在资源受限场景下用二进制日志把 flash 占用压到最低。

日志系统概览:Log V1 与 Log V2

ESP-IDF 日志组件(components/log/CMakeLists.txt)提供两个可配置的实现版本,由 Kconfig 中的 CONFIG_LOG_VERSION 选择(见 components/log/Kconfig):

  • Log V1(默认):最初实现,主打简单。格式化信息被直接拼进用户传入的 format 字符串并整体编译进 Flash,对早期启动(early)和 DRAM 日志场景很快,但灵活性差。
  • Log V2:增强实现,把格式化集中到单一函数 esp_log(components/log/src/log.c),Flash 中只保存用户定义的格式串,二进制体积更小,支持运行时定制颜色、时间戳、标签等,但会多消耗一些栈空间。

兼容性规则:Log V2 向后兼容 Log V1,用 V1 编写的工程可以无改动切换到 V2;反之,一旦使用了 V2 专属特性,就无法回退到 V1。

Log V1 的特性

  • 格式化内容包含在 format 参数里,编译进 Flash;
  • 早期启动与 DRAM 日志比 ESP_LOGx 宏更快;
  • 实现简单,但有明显局限:
    • 冗余的格式化项导致二进制体积偏大;
    • 不支持自定义日志格式,缺乏灵活性;
    • 宏展开出错时,编译错误指向错误的参数序号。

从源码看,V1 的 ESP_LOG_LEVEL 宏会在编译期按日志级别展开出带 LOG_FORMAT(E, format) 的完整格式串(components/log/include/esp_log.h),正如 Kconfig 注释所描述的:V1 写入 flash 的格式串形如 "[0;32mI (%lu) %s: chip revision: v%d.%d [0m"。

Log V2 的特性

  • 通过单一函数 esp_log 集中格式化(components/log/src/log.c#L79-L91),Flash 中仅存用户格式串(如 "chip revision: v%d.%d"),显著减小体积;
  • 仅在需要输出且日志级别允许时才采集时间戳;
  • 可全局、按文件、按模块甚至按单条日志控制颜色/时间戳/标签的开关;
  • 支持无格式化输出(适合二进制日志);
  • 可为 bootloader 与应用设置不同的日志配置;
  • format 参数可以是变量,动态构造日志消息更灵活;
  • bootloader、ISR、启动代码与受限环境下统一走同一个 handler;
  • 缺点:栈与内存消耗更大;handler 比 V1 略慢,但与数据经 UART 传输的时间相比可忽略。

在 V2 中,ESP_LOGx、ESP_EARLY_LOGx、ESP_DRAM_LOGx 全部路由到 esp_log(),由 handler 自动检测受限环境(早期启动、中断关闭、flash cache 不可用)并动态选择打印函数(components/log/include/esp_log.h 中的 ESP_LOG_EARLY_IMPL、ESP_DRAM_LOG_IMPL)。

日志级别(Log Levels)

应用与 bootloader 的日志级别分开配置,因此可以通过各自的 Kconfig 选项施加不同设置——例如 bootloader 只开简洁日志,而应用开详细调试。

系统共定义六档级别(见 components/log/include/esp_log_level.h 中的 esp_log_level_t 枚举):

级别 枚举值 含义
Verbose(最高) ESP_LOG_VERBOSE = 5 高度详细、频繁的调试消息(常含内部状态),可能淹没输出
Debug ESP_LOG_DEBUG = 4 详细诊断消息(变量值、指针地址等)
Info ESP_LOG_INFO = 3 描述系统正常运行的一般信息
Warning ESP_LOG_WARN = 2 可能引发问题但已被处理/缓解的事件
Error ESP_LOG_ERROR = 1 软件无法自行恢复的严重错误
None(最低) ESP_LOG_NONE = 0 无日志输出,完全禁用

级别用 3 个 bit 表示(ESP_LOG_LEVEL_LEN),保证能容纳全部六档。

日志级别设置:编译期与运行期

日志级别设置控制两件事:哪些日志被编译进二进制、哪些在运行期可见。共分两类:

  • Log level(运行期显示级别):bootloader 由 CONFIG_BOOTLOADER_LOG_LEVEL 配置,应用由 CONFIG_LOG_DEFAULT_LEVEL 配置(components/log/Kconfig.level)。可通过 esp_log_get_default_level() 获取当前默认级别。
  • Maximum log level(编译期包含级别):决定哪些级别的日志被编入二进制,高于此级别的日志在编译期被丢弃。它可高于 log level,从而把额外日志编进二进制、日后通过 esp_log_level_set 按需开启(应用侧由 CONFIG_LOG_MAXIMUM_LEVEL 开启;bootloader 不支持该特性,其 maximum level 恒等于 log level)。

举例:若 log level 为 Warning、maximum log level 为 Debug,则二进制包含 Error/Warning/Info/Debug 四级日志;但运行期只输出 Error 和 Warning,除非显式用 esp_log_level_set 调整(可增可减)。

用 LOG_LOCAL_LEVEL 覆盖 Maximum Log Level

LOG_LOCAL_LEVEL 允许不改 Kconfig、针对单个源文件或整个组件覆盖 maximum log level,本地决定哪些日志进入二进制。适合只想对某块代码开更详细日志、又不想全局抬高 maximum level 影响体积的场景。

按源文件设置(注意不要写在头文件里,头文件被单次包含的方式可能导致其不生效),需在 #include "esp_log.h" 之前定义:

// 在 my_file.c 中
#define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE
#include "esp_log.h"

按组件设置——在组件的 CMakeLists.txt 中定义,对整个组件所有源文件生效:

# 在某组件的 CMakeLists.txt 中
target_compile_definitions(${COMPONENT_LIB} PUBLIC "-DLOG_LOCAL_LEVEL=ESP_LOG_VERBOSE")

从源码看,LOG_LOCAL_LEVEL 未显式定义时依次取自 CONFIG_BOOTLOADER_LOG_LEVEL(bootloader 构建)、CONFIG_SECURE_TEE_LOG_LEVEL(Secure TEE 构建)或 CONFIG_LOG_MAXIMUM_LEVEL(其他构建),并以 ESP_LOG_ENABLED(configs) 宏做编译期检查(components/log/include/esp_log_level.h#L51-L73)。

运行期 Log Level 设置

只有应用支持运行期改级别,bootloader 不支持。默认情况下启动时所有不高于 log level 的日志均开启。esp_log_level_set 可全局或按模块(tag)设置级别:

// 对所有组件全局设置为 ERROR
esp_log_level_set("*", ESP_LOG_ERROR);

// 仅对 Wi-Fi 组件设置为 WARNING
esp_log_level_set("wifi", ESP_LOG_WARN);

模块由 tag 标识(人类可读的 ASCII 零结尾字符串)。此功能依赖 CONFIG_LOG_DYNAMIC_LEVEL_CONTROL(默认开启);不需要时可关闭以减小代码体积、提升性能。按 tag 调整输出还依赖 CONFIG_LOG_TAG_LEVEL_IMPL(默认开启)。esp_log_level_set("*", level) 的实现会清空链表与缓存并重设默认级别,具体见 components/log/src/log_level/tag_log_level/tag_log_level.c。

使用日志库:宏与实战示例

在每个使用日志功能的 C 文件中定义 TAG 变量:

// #define LOG_LOCAL_LEVEL ESP_LOG_VERBOSE // 可选:提高本文件编入二进制的日志级别
#include "esp_log.h"
static const char* TAG = "MyModule";
// ...
ESP_LOGI(TAG, "Baud rate error %.1f%%. Requested: %d baud, actual: %d baud", error * 100, baud_req, baud_real);
ESP_EARLY_LOGW(TAG, "Early log message %d", i++);
ESP_DRAM_LOGE(DRAM_STR("TAG_IN_DRAM"), "DRAM log message %d", i++); // 需要时用 DRAM_STR 把 tag 放到 DRAM

对应输出:

I (112500) MyModule: Baud rate error 1.5%. Requested: 115200 baud, actual: 116928 baud
W (112500) MyModule: Early log message 1
E TAG_IN_DRAM: DRAM log message 2

关于 TAG 的注意点:TAG 指向存放在 flash 中的字符串字面量。同一翻译单元内多次使用相同 TAG 时,编译器/链接器通常通过**字符串池化(string pooling)**优化为 flash 中的单一副本;但跨组件或跨翻译单元使用相同 TAG 时,若无全局链接优化,每个单元都会保留自己的副本。

三组日志宏

按使用场景,日志宏分为三组(定义于 components/log/include/esp_log.h):

级别 常规宏 早期宏 DRAM 宏
Verbose ESP_LOGV ESP_EARLY_LOGV ESP_DRAM_LOGV
Debug ESP_LOGD ESP_EARLY_LOGD ESP_DRAM_LOGD
Info ESP_LOGI ESP_EARLY_LOGI ESP_DRAM_LOGI
Warning ESP_LOGW ESP_EARLY_LOGW ESP_DRAM_LOGW
Error ESP_LOGE ESP_EARLY_LOGE ESP_DRAM_LOGE
  • ESP_LOGx:常规宏,适用于正常运行期的大多数场景;避免在 ISR、早期启动或 flash cache 关闭时使用。特点是使用 Newlib 的 vprintf 进行格式化输出(V2 下 ESP_LOG_LEVEL 展开为 esp_log(...),见 components/log/include/esp_log.h#L178-L187)。
  • ESP_EARLY_LOGx:面向 heap 分配器或 syscalls 初始化之前的早期启动受限环境,常用于关键启动代码或中断被关闭的临界区。特点是使用 ROM printf,总是输出微秒级时间戳,不支持按模块设置日志级别。
  • ESP_DRAM_LOGx:面向中断关闭或 flash cache 不可访问的受限环境,应谨慎使用(影响性能)。特点是使用 ROM printf、不输出时间戳、格式参数分配在 DRAM 中以保证 cache 关闭时可访问,不支持按模块设置级别。

用 DRAM_STR("my_tag") 宏把 tag 分配到 DRAM,是保证 cache 关闭时 tag 可访问的必要手段。

V1 与 V2 的本质差异:V2 中所有这些宏都经过同一个 handler(esp_log),handler 自动检测受限环境(早期启动、中断关闭、flash cache 不可访问)并动态选择打印函数,从而在各种运行上下文高效输出。V2 下 esp_log_va 的完整处理链可见 components/log/src/log.c#L38-L77:先做 is_level_loggable 检查、必要时取时间戳、再做 tag 级别过滤,最后交给 esp_log_format(文本模式)或 esp_log_format_binary(二进制模式)。

日志格式(Log Format)

  • Log V1:仅支持全局关闭颜色;时间戳、标签等其他格式项始终开启。
  • Log V2:支持完全自定义格式——颜色、标签、时间戳均可全局、按文件、按模块甚至按单条日志关闭,输出控制更精细。
// #define ESP_LOG_COLOR_DISABLED     (1)  /* 仅 Log V2 */
// #define ESP_LOG_TIMESTAMP_DISABLED (1)  /* 仅 Log V2 */
#include "esp_log.h"
static const char* TAG = "boot";
// ...
ESP_LOGI(TAG, "chip revision: v%d.%d", major, minor);

输出及格式项拆解:

I (56) boot: chip revision: v3.0

    level name                            |end of line
       |                                  |
 [0;32mI (56) boot: chip revision: v3.0[0m
|_____|  |___||____||_________________||_|
|start   |    |tag  |                  |end color
|color   |          |user string
         |timestamp

格式化选项

以下选项对应用与 bootloader 均适用:

  • 颜色(Color):为日志增加颜色码,由 CONFIG_LOG_COLORS 全局控制,默认关闭——因为 IDF Monitor(idf.py monitor)能识别日志的级别名并按标准 IDF 配色上色。Log V2 另有 CONFIG_LOG_COLORS_SUPPORT 选项,允许在全局颜色关闭时仍为特定日志/文件/组件运行时启用颜色;特定上下文启用用 ESP_LOG_COLOR_DISABLED。

    IDF Monitor 的格式要求:要自动上色,日志必须满足"级别名 + 时间戳"的最小格式且每条以换行结尾,例如 I (56): Log message\n。不满足(如关闭了时间戳)时自动配色失效,此时建议在 menuconfig 里开启 CONFIG_LOG_COLORS;多行日志只有首行能正确着色。

  • 级别名(Level Name):每条消息开头的单个字母(I/W/E/D/V),标识日志级别;颜色关闭时尤其有用,IDF Monitor 即依赖它。
  • 时间戳(Timestamp):由 CONFIG_LOG_TIMESTAMP_SOURCE 全局控制,可选值:
    • None:无时间戳,适合时间不关键的日志分析,省处理与内存;仅 Log V2 可用。
    • Milliseconds since boot (18532)(默认):RTOS tick 计数乘 tick 周期,软件重启后归零。
    • System time (HH:MM:SS.sss) (14:31:18.532):来自 POSIX 时间函数(芯片 RTC + 高精度定时器),软件重启后不归零。
    • System time (YY-MM-DD HH:MM:SS.sss) (2023-08-15 14:31:18.532):上述基础上再含日期。
    • Unix time in milliseconds (1692099078532):Unix 毫秒时间戳。
    • Log V2 的 CONFIG_LOG_TIMESTAMP_SUPPORT 允许全局时间戳关闭时仍为特定上下文启用;特定上下文启用"启动后毫秒"时间戳用 ESP_LOG_TIMESTAMP_DISABLED。
    • 注意:Wi-Fi、蓝牙等二进制 blob 库的日志不会使用上述配置,始终打印"启动后毫秒"。
  • 标签(Tag):用户定义的模块标识。Log V2 中 tag 可传 NULL,此时不打印 tag,且按组件(per-component)的级别检查将失效。
  • 换行(End Line):每条日志末尾的换行符。

Log V2 专属格式化定义

以下定义仅 Log V2 有效,使用方式与 LOG_LOCAL_LEVEL 相同(定义于文件、组件或全局,作用域取决于定义位置):

  • ESP_LOG_CONSTRAINED_ENV:定义为 1 时,强制日志 handler esp_log 在指定作用域使用安全的 printf 函数。
  • ESP_LOG_FORMATTING_DISABLED:默认 0(启用颜色、时间戳、标签、换行等全部格式项);定义为 1 时禁用指定作用域的全部格式项。
  • ESP_LOG_COLOR_DISABLED:需要 CONFIG_LOG_COLORS_SUPPORT 开启。全局颜色关闭时定义为 0 可在指定作用域启用颜色;全局颜色开启时定义为 1 可关闭颜色。
  • ESP_LOG_TIMESTAMP_DISABLED:需要 CONFIG_LOG_TIMESTAMP_SUPPORT 开启。全局时间戳关闭时定义为 0 可在指定作用域输出 tick 时间戳;全局时间戳开启时定义为 1 可关闭。
  • ESP_LOG_MODE_BINARY_EN:需要 CONFIG_LOG_MODE_BINARY 或 CONFIG_BOOTLOADER_LOG_MODE_BINARY 开启。设为 0 时日志仍以二进制发送,但格式串不会从 flash 移除、参数分析在运行时进行(可用于调试/测试等特定场景);文本模式下设为 1 无效,会被压制并自动定义为 0。

这些定义与宏的联动逻辑集中在 components/log/include/esp_log_config.h 的 ESP_LOG_CONFIGS_DEFAULT 中:ESP_LOG_CONSTRAINED_ENV、ESP_LOG_COLOR_DISABLED、ESP_LOG_TIMESTAMP_DISABLED、ESP_LOG_MODE_BINARY_EN、ESP_LOG_FORMATTING_DISABLED 共同生成默认配置位,再经 ESP_LOG_CONFIG_INIT 组装成 32 位 esp_log_config_t(components/log/include/esp_log_config.h#L138-L151)。

按条日志自定义格式(Per-Log Formatting)

如果需要在运行期动态调整格式(比如根据温度值改变日志级别),可使用替代宏。注意:这类日志无法从二进制中剔除,因为它们绕过了编译期级别检查。

#include "esp_log.h"
esp_log_config_t configs = {
    .opts = {
        .log_level = ESP_LOG_INFO,                 // 设置日志级别
        .constrained_env = false,                  // 指定是否为受限环境
        .require_formatting = true,                // 启用格式化
        .dis_color = ESP_LOG_COLOR_DISABLED,       // 使用全局颜色设置
        .dis_timestamp = ESP_LOG_TIMESTAMP_DISABLED, // 使用全局时间戳设置
        .reserved = 0,                             // 保留位
    }
};
// ...
if (temperature > 55) {
    configs.opts.log_level = ESP_LOG_WARN;
}
// 与 ESP_LOGx 宏类似,但允许应用自定义配置
// 若 configs 为常量,编译器可在其低于 maximum log level 时于编译期剔除该日志,否则不能
ESP_LOG_LEVEL_LOCAL(configs, TAG, "Temp = %dC", temperature);

// 注意:以下调用绕过编译期级别检查,无法从二进制中剔除
esp_log(configs, TAG, "Temp = %dC", temperature);
ESP_LOG_LEVEL(configs, TAG, "Temp = %dC", temperature);

ESP_LOG_LEVEL_LOCAL 会先做 ESP_LOG_ENABLED(configs) 编译期检查,通过后才调用 ESP_LOG_LEVEL/esp_log(components/log/include/esp_log.h#L155-L167),因此当 configs 为编译期常量时可以省掉未启用级别的日志。

日志级别控制:三个关键配置

只有应用支持运行期改级别,bootloader 不支持。运行期按模块(tag)调整级别只适用于非受限环境的 ESP_LOGx 宏;受限环境(ESP_EARLY_LOGx、ESP_DRAM_LOGx)的 handler 无锁且追求轻量,不支持动态级别。

// 全局设为 ERROR
esp_log_level_set("*", ESP_LOG_ERROR);

// WiFi 组件设为 WARNING
esp_log_level_set("wifi", ESP_LOG_WARN);

// DHCP 客户端设为 INFO
esp_log_level_set("dhcpc", ESP_LOG_INFO);

控制运行期改级别能力的有三个设置:

1. 动态级别控制 CONFIG_LOG_DYNAMIC_LEVEL_CONTROL(默认开启)

启用后可通过 esp_log_level_set 在运行期改级别,灵活但增加内存与性能开销。若对体积敏感且不需要动态调整,建议在 CONFIG_LOG_TAG_LEVEL_IMPL 为 None 时关闭该选项以最小化程序体积。关闭后可节省:IRAM 约 260 字节、DRAM 约 264 字节、Flash 约 1 KB,并将日志操作性能提升最高约 10 倍。

2. 按 tag 级别检查 CONFIG_LOG_TAG_LEVEL_IMPL(默认 Cache + Linked List)

决定按 tag 检查级别的实现方式,影响内存与查找速度:

  • None:完全禁用按 tag 级别检查,开销最小但失去运行期灵活性。
  • Linked List:仅用链表(无缓存)实现。查找需遍历链表,tag 多时较慢,但比 Cache 省内存;做 tag 的全字符串比较,不依赖指针比较,适合动态定义的 tag。选择它会自动开启 Dynamic Log Level Control。链表项在 ESP_LOGx 执行期间遇到新 tag 时从堆上分配。
  • Cache + Linked List(默认):缓存 + 链表混合。缓存保存最近访问的 tag 及级别,通过指针比较加速常用 tag 查找;不常用 tag 回落到链表。动态定义 tag 时可能工作不正常(缓存依赖指针比较)。选择它也会自动开启 Dynamic Log Level Control。

其中缓存实现由 CONFIG_LOG_TAG_LEVEL_CACHE_IMPL 决定:

  • Array:无重排的简单实现,适合追求简单的低内存应用;
  • Binary Min-Heap(默认):自动重排、查找快,适合内存充裕的高性能应用。缓存容量由 CONFIG_LOG_TAG_LEVEL_IMPL_CACHE_SIZE 定义,默认 31 条(应为 2 的幂减 1,如 1/3/7/15/31/63/127/255…)。

更大的缓存提升常用 tag 的查找性能但增加内存;更小的缓存省内存但导致不常用 tag 更频繁被逐出。相关 Kconfig 定义见 components/log/Kconfig.level_settings。

3. 主日志级别 CONFIG_LOG_MASTER_LEVEL(默认关闭)

可选的全局"master"级别检查,发生在时间戳与 tag 缓存查找之前,适用于"编译大量日志、运行期选择性开关、同时在不需要输出时把性能影响降到最低"的调试场景。典型用途:在时间关键或 CPU 密集操作期间临时关闭日志、之后再打开。

注意:Log V1 下该特性会按编译日志数量显著增大程序体积;Log V2 下检查集成在 handler 内,影响很小。

开启后默认值为 CONFIG_LOG_DEFAULT_LEVEL,可用 esp_log_set_level_master 运行期调整,且该全局检查优先于 esp_log_get_default_level。示例:

// Master 日志级别启动时为 CONFIG_LOG_DEFAULT_LEVEL = ESP_LOG_INFO
ESP_LOGI("lib_name", "Message for print");          // 打印 INFO 消息
esp_log_level_set("lib_name", ESP_LOG_WARN);        // 为 lib_name 启用 WARN 日志

// 全局禁用所有日志,此刻 esp_log_level_set 不生效
esp_log_set_level_master(ESP_LOG_NONE);

ESP_LOGW("lib_name", "Message for print");          // 不打印,被 Master 级别拦截
esp_log_level_set("lib_name", ESP_LOG_INFO);        // 为 lib_name 启用 INFO 日志
ESP_LOGI("lib_name", "Message for print");          // 不打印,被 Master 级别拦截

// 全局启用所有 INFO 日志
esp_log_set_level_master(ESP_LOG_INFO);

ESP_LOGI("lib_name", "Message for print");          // 打印 INFO 消息

即使日志被 tag 禁用,处理开销仍约为 10.9 微秒。要降低此开销,可考虑使用 Master Log Level 或关闭 Tag-Level Checks。

esp_log_set_level_master/esp_log_get_level_master 仅在 CONFIG_LOG_MASTER_LEVEL 开启时可用(components/log/include/esp_log_level.h#L122-L146)。

缓冲区日志(Logging of Buffers)

日志系统提供打印缓冲区数据的宏,bootloader 与应用均可用,且与日志版本无关(定义于 components/log/include/esp_log_buffer.h,实现见 components/log/src/buffer/log_buffers.c):

  • ESP_LOG_BUFFER_HEX / ESP_LOG_BUFFER_HEX_LEVEL:以十六进制字节打印缓冲区,每行 16 字节。ESP_LOG_BUFFER_HEX 仅用于 Info 级别。
#include "esp_log_buffer.h"
uint8_t buffer[] = {
    0x54, 0x68, 0x65, 0x20, 0x77, 0x61, 0x79, 0x20,
    0x74, 0x6f, 0x20, 0x67, 0x65, 0x74, 0x20, 0x73,
    0x74, 0x61, 0x72, 0x74, 0x65, 0x64, 0x20, 0x69,
    0x73, 0x20, 0x61, 0x6e, 0x64, 0x20, 0x66
};
ESP_LOG_BUFFER_HEX_LEVEL(TAG, buffer, sizeof(buffer), ESP_LOG_DEBUG);
I (954) MyModule: 54 68 65 20 77 61 79 20 74 6f 20 67 65 74 20 73
I (964) MyModule: 74 61 72 74 65 64 20 69 73 20 61 6e 64 20 66
  • ESP_LOG_BUFFER_CHAR / ESP_LOG_BUFFER_CHAR_LEVEL:以可打印字符打印缓冲区,每行最多 16 字符。ESP_LOG_BUFFER_CHAR 仅用于 Info 级别。
#include "esp_log_buffer.h"
char buffer[] = "The quick brown fox jumps over the lazy dog.";
ESP_LOG_BUFFER_CHAR_LEVEL(TAG, buffer, sizeof(buffer), ESP_LOG_WARN);
I (980) MyModule: The quick brown
I (985) MyModule: fox jumps over
I (990) MyModule: the lazy dog.
  • ESP_LOG_BUFFER_HEXDUMP:以十六进制转储(hex dump)风格打印,同时显示内存地址与对应 ASCII 值,非常适合调试原始内存内容。
#include "esp_log_buffer.h"
uint8_t buffer[] = {
    0x54, 0x68, 0x65, 0x20, 0x77, 0x61, 0x79, 0x20,
    0x74, 0x6f, 0x20, 0x67, 0x65, 0x74, 0x20, 0x73,
    0x74, 0x61, 0x72, 0x74, 0x65, 0x64, 0x20, 0x69
};
ESP_LOG_BUFFER_HEXDUMP(TAG, buffer, sizeof(buffer), ESP_LOG_INFO);
I (1013) MyModule: 0x3ffb5bc0   54 68 65 20 77 61 79 20  74 6f 20 67 65 74 20 73  |The way to get s|
I (1024) MyModule: 0x3ffb5bd0   74 61 72 74 65 64 20 69  73 20 74 6f 20 71 75 69  |tarted is to qui|

输出行数取决于缓冲区大小。

二进制日志(Binary Logging)

二进制日志是 Log V2 专属特性,日志以二进制而非文本传输,bootloader(CONFIG_BOOTLOADER_LOG_MODE_BINARY)与应用(CONFIG_LOG_MODE_BINARY)分开配置。默认启用 V2 时使用文本模式(见 components/log/Kconfig.settings)。

开启二进制日志后:

  • 格式串从 flash 中移除(只发送其地址),节省 flash 占用;
  • 不使用 printf 类函数,降低栈占用与 flash 消耗;
  • 引入 ESP_LOG_ATTR_STR 宏,把格式串放到 .noload 段,从最终镜像中移除;该机制也可用于断言或自定义日志消息以进一步省 flash。

收益总结:

  • flash 体积减少约 10% – 35%(取决于应用;日志越多节省越大);
  • 免除 vprintf 类格式化函数,栈占用最小化;
  • 传输紧凑二进制数据,降低日志传输开销。

在 flash 优化与高效日志都关键的资源受限环境中,二进制日志尤其有价值。

二进制日志工作流

二进制日志由两大部件组成:

  1. 芯片侧(Chip Side):编码并传输日志数据(编码过程、参数类型编码、运行期参数类型编码)。
  2. 主机侧(Host Side):用 esp-idf-monitor 工具接收并解码,idf.py monitor 命令自动解码二进制日志(检测二进制包、提取包字段(级别/格式/tag/时间戳/参数)、判断地址指向 ELF 文件还是内嵌字符串、按格式串与参数数组解码、重建日志消息、应用终端配色)。

芯片侧:编码过程

二进制日志以结构化数据包传输。字符串若存在于 ELF 文件中则以地址发送;运行期生成的字符串使用内嵌字符串格式发送给主机。

数据包结构(多字节字段均为大端序):

[0]  - 消息类型(1: bootloader, 2: application, ...)
[1]  - 控制字节(日志级别、版本、time_64bits 标志)
[2]  - 长度(10 bit,最大 1023 字节)
[3-6]  - 格式地址(若存在于 ELF)或内嵌字符串
[7-10] - Tag 地址(若存在于 ELF)或内嵌字符串
[11-14] - 时间戳(32 bit;若超过 32 bit 则占 [11-18],并在控制字节置 time_64bits 标志)
[...] - 参数(可选):32-bit、64-bit、指针、内嵌字符串/数据的数组
[15] - CRC8 校验和

内嵌字符串格式(字符串不在 ELF 中时使用):

[0] - 内嵌标识符(0xFF - 0xFC)
[0,1] - (10 bit)字符串的负长度 = 1 - len(str)
[...] - 字符串内容

参数类型编码

格式串从二进制移除后,芯片仍需识别参数类型以正确传输。ESP_LOG_ARGS_TYPE 宏利用 C11 _Generic 特性在编译期把用户参数分为三类:32 位、64 位、指针,运行期生成参数类型数组并传给 esp_log,保证:

  • 芯片按正确的大小与偏移传输数据;
  • 主机工具准确重建日志消息。

运行期行为

esp_log 首先检查给定配置是否启用了二进制日志。若启用,则从 va_list 中提取参数类型数组;若未设置二进制日志标志(无预处理参数类型数组),二进制日志 handler 会在运行期从格式串中提取参数类型。这种运行期提取比显式使用 ESP_LOG_ATTR_STR(format) ESP_LOG_ARGS(__VA_ARGS__)(编译期生成参数类型数组并从 flash 移除格式串)低效,但保证了即使第三方库不支持二进制日志,日志仍能正确输出。

缓冲区日志的特殊处理

二进制日志支持缓冲区日志函数(ESP_LOG_BUFFER_HEX_LEVEL、ESP_LOG_BUFFER_CHAR_LEVEL、ESP_LOG_BUFFER_HEXDUMP)。此时二进制日志 handler 检查格式地址是否匹配预定义常量(如 __ESP_BUFFER_HEX_FORMAT__,见 components/log/src/log_format_binary.c),匹配则跳过格式串发送、直接传输原始缓冲区数据。

主机侧(Monitor 工具)

主机侧由 esp-idf-monitor 自动解码二进制日志。重要的是 monitor 必须使用正确版本的 ELF 文件——bootloader 与应用各有自己的 ELF,idf.py monitor 会自动选择。收到 ELF 地址时,monitor 依据对应消息类型字节从 ELF 文件中取回字符串;地址以 0xFF 开头(范围 0xFF - 0xFC)则代表内嵌字符串,长度编码在 10 bit 中。全部组件取回后格式化输出到终端。

性能与测量数据

在任务中使用日志时,任务栈至少应配置 2 KB 空间以确保日志操作有足够内存。

以下测量来自 log 组件内的测试(默认设置:maximum 与 default 日志级别为 INFO、关闭颜色支持、无 master log、开启时间戳),覆盖不同芯片。esp_rom_printf 与 esp_rom_vprintf 结果相近,vprintf 与 printf 结果相近,故下表各取其一。

栈占用(字节)

函数 ESP32 ESP32C2 ESP32C3
esp_rom_printf 128 192 192
ESP_EARLY_LOGI V1 128 192 192
ESP_EARLY_LOGI V2 336 324 324
ESP_DRAM_LOGI V1 128 192 192
ESP_DRAM_LOGI V2 336 324 324
vprintf 1168 384 1344
ESP_LOGI V1 1184 384 1344
ESP_LOGI V2 1152 592 1504

Log V1 与 Log V2 的栈占用差异可忽略。

性能(无输出,微秒)

函数 ESP32 ESP32C2 ESP32C3
esp_rom_printf 1 2 1
ESP_EARLY_LOGI V1 15 24 14
ESP_EARLY_LOGI V2 28 36 25
ESP_DRAM_LOGI V1 6 9 5
ESP_DRAM_LOGI V2 19 22 14
vprintf 15 9 7
ESP_LOGI V1 27 16 12
ESP_LOGI V2 77 54 40

若测量的是输出到 UART 的整体性能,V1 与 V2 几乎相同——V2 引入的少量处理开销相对 UART 发送耗时可忽略,因此多数实际场景下切到 V2 的性能影响不易察觉。

内存占用(字节)——基于 esp_timer 示例、ESP32 默认设置(maximum 与 default 级别为 INFO、关闭颜色、开启时间戳),启用 Log V2 后重新构建并对比:

idf.py size --diff ~/esp/logv2/build_v1
版本 IRAM DRAM Flash Code Flash Data App binary size
Log V2 +1772 –36 –956 –1172 181104 (–384)
版本 Bootloader binary size
Log V2 26272 (+160)

可见启用 Log V2 增加了 IRAM 占用,但减小了应用二进制总体积、Flash 代码与数据占用。

降低 Log V2 的 IRAM 占用

Log V2 的 IRAM 增加主要由 esp_rom_vprintf 引起——在部分芯片上该函数被编译进 IRAM(约 1.2 KB),作为受限环境(ISR、cache 关闭)的 fallback 格式化器被 esp_log_vprintf() 内联函数引用;在 IRAM 与 DRAM 共享内存池的芯片上,这会等量减少约 1.2 KB 的可用堆。

关闭 CONFIG_LOG_API_CONSTRAINED_ENV_SAFE(默认开启)即可消除该开销。关闭后:

  • ESP_DRAM_LOGx 与 ESP_EARLY_LOGx 直接展开为 esp_rom_printf()(真正的 ROM 函数,零 IRAM 开销),完全绕过 esp_log() 流水线;
  • 受限环境中的普通 ESP_LOGx 调用将使用标准 vprintf;若 vprintf 位于 flash,此类调用可能崩溃——凡必须在 cache 关闭或 ISR 中工作的日志都应使用 ESP_DRAM_LOGx;
  • esp_rom_vprintf 不再被引用,链接器将其从二进制中排除。

开启时保持 V2 原始行为:所有受限环境日志都经 esp_log() 路由,并以 esp_rom_vprintf 作为 early/DRAM 日志的格式化器。该选项的完整说明见 components/log/Kconfig#L55-L78。

通过 JTAG 向主机输出日志

默认情况下日志库使用 vprintf 类函数把格式化输出写到专用 UART。通过简单 API 调用,所有日志输出可改路由到 JTAG,使日志输出快数倍。详情参见 docs/en/api-reference/system/app_trace.rst 中的 "Logging to Host" 一节。

线程安全

受限环境日志(ESP_EARLY_LOGx、ESP_DRAM_LOGx)不加锁,若其他任务并行打日志,可能出现罕见的日志损坏;为把风险降到最低,应尽量使用通用宏。通用宏(ESP_LOGx)在输出时获取锁以保证线程安全;Log V2 在多次 vprintf 格式化期间还额外用 flockfile 提供保护。日志先写入内存缓冲再发送到 UART,从而保证跨任务操作线程安全;除非必要,应避免在受限环境打日志以保证输出可靠。

应用示例

日志库被 ESP-IDF 绝大多数组件与示例使用。演示日志功能最相关的示例包括:

若想深入验证本文所述的级别控制、tag 检查与性能行为,可直接查看 log 组件的单元测试(components/log/test_apps/main/test_log.c、components/log/test_apps/main/test_log_level.c、components/log/test_apps/main/test_log_perf.c)及 Linux 主机端测试(components/log/host_test/log_test/main/log_test.cpp),它们与文档描述的行为相互印证。

小结

选择日志版本时:Log V1 适合栈空间紧张或追求极致简单/性能的项目;Log V2 适合追求更小二进制、需要灵活格式化配置(颜色/时间戳/标签按需开关)或高级特性(如二进制日志)的项目。日常开发建议遵循"常规日志用 ESP_LOGx、启动早期用 ESP_EARLY_LOGx、cache 关闭/ISR 场景才用 ESP_DRAM_LOGx"的分层原则,并善用 LOG_LOCAL_LEVEL、esp_log_level_set 与 CONFIG_LOG_MASTER_LEVEL 在体积、性能与可调试性之间取得平衡。

登录后查看全文
esp-idf