EasyLogger核心API详解：从入门到精通
2025-07-09 01:44:45作者：宗隆裙
引言
EasyLogger是一款轻量级、高性能的嵌入式日志系统，其核心API提供了丰富的日志功能和控制选项。本文将全面解析EasyLogger的核心API，帮助开发者更好地理解和使用这一强大的日志工具。
1. 基础API
1.1 初始化与启动
EasyLogger使用前必须进行初始化和启动操作：
ElogErrCode elog_init(void); // 初始化EasyLogger核心功能
void elog_start(void); // 启动日志输出
技术要点：
- 初始化操作只需执行一次，通常在程序启动时调用
- 启动操作必须在初始化后调用，否则日志不会输出
- 初始化函数返回错误码，可用于检查初始化是否成功
1.2 日志级别系统
EasyLogger采用6级日志级别体系：
| 级别 | 标识 | 描述 | 典型用途 |
|---|---|---|---|
| 0 | [A] | 断言(Assert) | 严重错误，程序无法继续运行时 |
| 1 | [E] | 错误(Error) | 错误情况，但程序仍可运行 |
| 2 | [W] | 警告(Warn) | 潜在问题警告 |
| 3 | [I] | 信息(Info) | 重要运行信息 |
| 4 | [D] | 调试(Debug) | 调试信息 |
| 5 | [V] | 详细(Verbose) | 非常详细的调试信息 |
1.3 日志输出API
EasyLogger为每个级别提供了三种输出方式：
// 完整形式
#define elog_assert(tag, ...)
#define elog_error(tag, ...)
// ...其他级别类似
// 简化形式1（需指定TAG）
#define elog_a(tag, ...)
#define elog_e(tag, ...)
// ...其他级别类似
// 简化形式2（使用预定义TAG）
#define log_a(...)
#define log_e(...)
// ...其他级别类似
最佳实践：
- 在每个源文件顶部定义LOG_TAG：
#define LOG_TAG "module.submodule" #include <elog.h> - 使用log_x系列宏简化代码：
log_i("System initialized"); log_d("Received packet, len=%d", pkt_len);
2. 高级功能API
2.1 断言系统
EasyLogger提供了强大的断言功能：
#define ELOG_ASSERT(EXPR) // 完整形式
#define assert(EXPR) // 简化形式
// 设置断言钩子函数
void elog_assert_set_hook(void (*hook)(const char* expr, const char* func, size_t line));
应用场景：
- 参数校验
- 关键状态检查
- 内存分配验证
2.2 输出控制
// 全局输出控制
void elog_set_output_enabled(bool enabled);
bool elog_get_output_enabled(void);
// 输出锁控制（用于异常处理）
void elog_output_lock_enabled(bool enabled);
异常处理示例：
static void assert_hook(const char* ex, const char* func, size_t line) {
elog_output_lock_enabled(false); // 禁用输出锁
elog_a("system", "Assert failed: %s at %s:%d", ex, func, line);
while(1);
}
2.3 日志格式定制
// 设置日志格式
void elog_set_fmt(uint8_t level, size_t set);
// 日志颜色控制
void elog_set_text_color_enabled(bool enabled);
格式选项：
ELOG_FMT_LVL- 日志级别ELOG_FMT_TAG- 标签ELOG_FMT_TIME- 时间ELOG_FMT_P_INFO- 进程信息ELOG_FMT_T_INFO- 线程信息ELOG_FMT_FILE- 文件路径ELOG_FMT_LINE- 行号ELOG_FMT_FUNC- 函数名
配置示例：
// 错误日志：显示级别、标签和时间
elog_set_fmt(ELOG_LVL_ERROR, ELOG_FMT_LVL | ELOG_FMT_TAG | ELOG_FMT_TIME);
// 调试日志：显示除函数名外的所有信息
elog_set_fmt(ELOG_LVL_DEBUG, ELOG_FMT_ALL & ~ELOG_FMT_FUNC);
3. 过滤系统
3.1 基本过滤
// 级别过滤
void elog_set_filter_lvl(uint8_t level);
// 标签过滤
void elog_set_filter_tag(const char *tag);
// 关键词过滤
void elog_set_filter_kw(const char *keyword);
// 综合过滤
void elog_set_filter(uint8_t level, const char *tag, const char *keyword);
过滤规则：
- 级别过滤：只显示等于或高于设定级别的日志
- 标签过滤：日志标签必须包含过滤标签
- 关键词过滤：日志内容必须包含关键词
3.2 模块级过滤
void elog_set_filter_tag_lvl(const char *tag, uint8_t level);
特殊级别：
ELOG_FILTER_LVL_SILENT- 静默（不输出）ELOG_FILTER_LVL_ALL- 输出所有级别
使用示例：
// 关闭wifi模块所有日志
elog_set_filter_tag_lvl("wifi", ELOG_FILTER_LVL_SILENT);
// 设置wifi模块只输出警告及以上级别
elog_set_filter_tag_lvl("wifi", ELOG_LVL_WARNING);
4. 输出模式
4.1 缓冲输出模式
void elog_buf_enabled(bool enabled); // 启用/禁用
void elog_flush(void); // 刷新缓冲区
特点：
- 减少I/O操作次数
- 提高日志输出效率
- 需要手动刷新确保及时输出
4.2 异步输出模式
void elog_async_enabled(bool enabled); // 启用/禁用
// 获取日志
size_t elog_async_get_log(char *log, size_t size);
size_t elog_async_get_line_log(char *log, size_t size);
应用场景：
- 实时性要求高的系统
- 需要减少日志输出对主程序影响的场景
- 多线程环境
结语
EasyLogger通过这套精心设计的API，为嵌入式系统提供了强大而灵活的日志功能。从基本的日志输出到高级的过滤和控制功能，EasyLogger能够满足各种复杂的日志需求。合理利用这些API，可以显著提高嵌入式系统的可调试性和可维护性。
在实际项目中，建议根据具体需求选择合适的日志级别、输出格式和过滤策略，在保证调试便利性的同时，避免日志系统对性能造成过大影响。
