3、日志系统基础：理解nRF Connect SDK中的日志模块

在nRF TinyML开发中，日志系统是调试的第一道防线。无论是传感器数据采集异常、模型推理结果偏差，还是系统随机重启，日志都是定位问题的首要线索。nRF Connect SDK（NCS）基于Zephyr RTOS，其日志子系统（Logging Subsystem）提供了从轻量级printf到多后端异步输出的完整能力。本章将深入剖析NCS日志模块的核心机制，帮助你在TinyML项目中建立高效、可诊断的日志体系。

上图展示了NCS日志系统的核心数据流：应用代码通过LOG_MODULE宏声明模块后，调用LOG_INF等宏产生日志消息；日志核心根据编译期和运行时的过滤规则决定是否处理该消息，并交由一个或多个后端输出。理解这条链路中的每个环节，是高效使用日志的前提。

3.1 核心原理：日志模块的声明与初始化

在NCS中，每个使用日志功能的源文件（.c）都必须先声明日志模块。这一声明不仅定义了模块名称，还确定了该模块的默认编译级别。其标准写法如下：

#include <zephyr/logging/log.h>
LOG_MODULE_REGISTER(my_tinyml_app, LOG_LEVEL_INF);
// 或者使用非注册方式（用于头文件或静态库）：
// LOG_MODULE_DECLARE(my_tinyml_app, LOG_LEVEL_INF);

LOG_MODULE_REGISTER会创建一个全局唯一的模块ID，并注册到日志子系统。第二个参数指定编译期默认日志级别。NCS定义了四个标准级别：LOG_LEVEL_ERR（0）、LOG_LEVEL_WRN（1）、LOG_LEVEL_INF（2）、LOG_LEVEL_DBG（3）。编译级别决定了哪些日志调用会被编译进固件——低于该级别的调用在编译时就被优化掉，不产生任何代码。

日志宏的使用遵循“级别+格式化字符串”的模式：

LOG_ERR("Sensor read failed, err=%d", err);
LOG_WRN("Battery low: %d mV", batt_mv);
LOG_INF("Inference result: class=%d, prob=%.3f", cls, prob);
LOG_DBG("Raw buffer: %02x %02x %02x", buf[0], buf[1], buf[2]);

这些宏最终会调用log_msg_v函数，将日志内容打包成一条消息。如果启用了CONFIG_LOG_MODE_IMMEDIATE，消息会立即同步输出；否则进入异步模式，由日志线程统一处理。对于TinyML应用，建议在调试阶段使用立即模式，以保留更多时序信息。

3.2 日志级别与过滤机制

日志级别不仅是编译期的概念，也存在于运行时。NCS的过滤机制分为两级：编译期过滤和运行时过滤。编译期过滤由LOG_MODULE_REGISTER中的级别决定，运行时过滤则通过log_filter_set()函数或Shell命令动态调整。

级别	宏	数值	典型用途	编译期影响
错误	LOG_ERR	0	不可恢复的故障	始终编译
警告	LOG_WRN	1	异常但可恢复	级别≥1时编译
信息	LOG_INF	2	关键运行状态	级别≥2时编译
调试	LOG_DBG	3	详细调试信息	级别≥3时编译

在prj.conf中，可以通过全局配置覆盖模块默认级别：

# 全局日志级别设为调试
CONFIG_LOG_DEFAULT_LEVEL=3
# 或者针对特定模块（需模块名匹配）
CONFIG_LOG_MY_TINYML_APP_LEVEL=3

运行时过滤则更为灵活。例如，在Shell中执行log enable dbg my_tinyml_app即可动态开启该模块的调试日志，无需重新编译。这在现场调试时非常有用——你可以先以INFO级别发布固件，遇到问题时再通过Shell提升到DEBUG级别。

3.3 后端配置：从UART到RTT

日志后端决定了日志消息的最终去向。NCS支持多种后端，最常用的是UART后端和RTT后端。对于TinyML开发，RTT（Real-Time Transfer）是首选，因为它不占用UART外设，且传输速度远高于串口。

在prj.conf中启用RTT后端：

CONFIG_LOG=y
CONFIG_LOG_MODE_IMMEDIATE=y
CONFIG_LOG_BACKEND_RTT=y
CONFIG_SEGGER_RTT=y
# 可选：设置RTT缓冲区大小
CONFIG_SEGGER_RTT_BUFFER_SIZE_UP=1024

使用RTT时，需要搭配SEGGER J-Link调试器，并在PC端使用J-Link RTT Viewer或RTT Client查看日志。RTT的优势在于：不干扰串口通信（串口可留给AT指令或用户交互）、支持双向通信（可通过RTT输入命令）、延迟极低。

如果必须使用UART后端，配置如下：

CONFIG_LOG_BACKEND_UART=y
CONFIG_LOG_BACKEND_UART_OUTPUT_DEFAULT=y
# 指定UART设备（默认是console）
CONFIG_LOG_BACKEND_UART_PORT=0

对于需要离线分析的场景，还可以启用Flash后端（CONFIG_LOG_BACKEND_FLASH=y），将日志写入外部Flash，掉电不丢失。但注意Flash写入速度慢，且会损耗Flash寿命，不适合高频日志。

3.4 格式化输出与时间戳

默认的日志输出格式为：[时间] [级别] [模块] 消息内容。例如：

[00:00:01.234,000] <inf> my_tinyml_app: Inference result: class=2, prob=0.876

时间戳默认使用系统启动后的毫秒计数。如果启用了CONFIG_TIMER_HAS_64BIT，可以显示更精确的时间。对于TinyML应用，时间戳至关重要——它帮助你判断推理耗时、传感器采样间隔是否准确。

NCS还支持自定义日志输出格式。通过实现log_output的回调函数，你可以完全控制输出内容。例如，添加CPU负载、内存余量或电池电压等系统状态：

static uint8_t output_buf[256];
static int custom_output(uint8_t *buf, size_t len, void *ctx) {
    // 自定义输出逻辑，例如添加系统状态
    return uart_send(buf, len);
}
LOG_OUTPUT_DEFINE(custom_output, output_buf, sizeof(output_buf), NULL);

但自定义输出会增加复杂度，建议在标准格式满足需求时优先使用默认配置。

3.5 实战案例：TinyML推理日志系统搭建

假设你正在开发一个基于nRF52840的语音关键词识别（KWS）设备，需要调试模型推理结果和传感器数据。初始现象是：设备偶尔输出错误分类结果，但无法复现。你决定搭建一套完整的日志系统来捕获现场数据。

第一步：配置日志系统。在prj.conf中启用RTT后端和DEBUG级别：

CONFIG_LOG=y
CONFIG_LOG_MODE_IMMEDIATE=y
CONFIG_LOG_BACKEND_RTT=y
CONFIG_LOG_DEFAULT_LEVEL=3
CONFIG_SEGGER_RTT_BUFFER_SIZE_UP=2048

第二步：在代码中分层记录。在音频采集、特征提取、推理三个关键节点添加日志：

LOG_MODULE_REGISTER(kws_app, LOG_LEVEL_DBG);
// 音频采集回调
static void audio_callback(int16_t *buf, size_t len) {
    LOG_DBG("Audio captured: %d samples, peak=%d", len, find_peak(buf, len));
    // 特征提取
    extract_features(buf, len, features);
    LOG_DBG("Features: mean=%.2f, std=%.2f", features[0], features[1]);
    // 推理
    int result = run_inference(features);
    LOG_INF("Inference: class=%d, confidence=%.3f", result, confidence);
    if (result != expected) {
        LOG_WRN("Unexpected result! expected=%d, got=%d", expected, result);
    }
}

第三步：现场复现与日志分析。连接J-Link，打开RTT Viewer，运行设备。当错误分类发生时，RTT输出如下：

[00:12:34.567,000] <dbg> kws_app: Audio captured: 320 samples, peak=1245
[00:12:34.568,000] <dbg> kws_app: Features: mean=0.23, std=0.45
[00:12:34.569,000] <inf> kws_app: Inference: class=3, confidence=0.412
[00:12:34.570,000] <wrn> kws_app: Unexpected result! expected=2, got=3

第四步：定位问题。通过对比正常与异常时的特征值，发现异常时std=0.45明显偏高（正常为0.2左右）。进一步检查音频缓冲区，发现DMA配置错误导致部分采样数据丢失。修复DMA后，日志恢复正常。

这个案例展示了日志系统的核心价值：可追溯性。没有日志，你只能猜测问题原因；有了日志，你可以精确回放故障现场。

3.6 常见误区与最佳实践