ESP-IDF 日志库(Logging Library)完全指南:Log V1/V2、日志级别控制、格式化与二进制日志
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时,强制日志 handleresp_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 优化与高效日志都关键的资源受限环境中,二进制日志尤其有价值。
二进制日志工作流
二进制日志由两大部件组成:
- 芯片侧(Chip Side):编码并传输日志数据(编码过程、参数类型编码、运行期参数类型编码)。
- 主机侧(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 在体积、性能与可调试性之间取得平衡。