【OpenHarmony】日志服务hilog_lite

HiLog_Lite 模块

目录

1. 模块概述
2. 模块结构
3. 模块间交互
4. 状态机转换图
5. 接口设计

1. 模块概述

源码：https://gitee.com/openharmony/hiviewdfx_hilog_lite

1.1 功能与目标

HiLog_Lite 是 OpenHarmony 操作系统 DFX（Design For X）子系统中的轻量级流水日志组件，主要功能包括：

核心功能：

• 提供轻量系统（LiteOS-M）和小型系统（LiteOS-A）的流水日志功能
• 支持多级别日志输出：DEBUG、INFO、WARN、ERROR、FATAL
• 支持模块化日志管理，最多支持64个模块
• 支持日志隐私保护（{public}/{private}标识符）
• 支持日志流量控制和限流机制
• 支持多种输出方式：UART实时输出、文件存储（文本/二进制）

设计目标：

• 低资源占用：ROM约500KB，RAM约500KB
• 高性能：支持异步日志处理，减少对主业务的影响
• 可配置性：支持编译时和运行时配置日志级别、输出模块等
• 隐私保护：支持日志参数隐私标记，商业版本自动脱敏

1.2 系统位置

┌─────────────────────────────────────────────────────────────────┐ │ OpenHarmony 系统 │ ├─────────────────────────────────────────────────────────────────┤ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ 应用层 │ │ 框架层 │ │ 服务层 │ │ │ │ (APP) │ │ (ACE) │ │ (SAMGR) │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ └────────────────┼────────────────┘ │ │ ▼ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ DFX 子系统 (hiviewdfx) │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ │ │ hilog_lite (本模块) │ │ │ │ │ │ ┌───────────┐ ┌───────────┐ ┌───────────────────┐ │ │ │ │ │ │ │frameworks │ │ services │ │ command │ │ │ │ │ │ │ │ mini/ │ │hilogcat │ │ │ │ │ │ │ │ │ │ featured │ │apphilogcat│ │ │ │ │ │ │ │ │ └───────────┘ └───────────┘ └───────────────────┘ │ │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ │ │ │ │ ┌───────────────────────┼───────────────────────────┐ │ │ │ │ │ hiview_lite │ hievent_lite │ │ │ │ │ └───────────────────────┴───────────────────────────┘ │ │ │ └───────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌───────────────────────────────────────────────────────────┐ │ │ │ 内核层 (Kernel) │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │ │ │ │ │ hilogtask │ │ /dev/hilog │ │ Ring Buffer │ │ │ │ │ │ (内核任务) │ │ (驱动节点) │ │ (环形缓冲区) │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────────┘ │ │ │ └───────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘

模块定位：

• 核心模块：作为DFX子系统的核心组件，为整个系统提供日志服务
• 基础服务：被系统中几乎所有模块依赖，是系统调试和问题定位的基础设施

与其他模块的关系：

1.3 设计思路与模式

设计思路

1. 分层架构：

   • 接口层：提供统一的日志API（C/C++/JS）
   • 框架层：实现日志格式化、缓存、输出逻辑
   • 服务层：提供日志查看和落盘服务
   • 驱动层：内核态日志处理

2. 双系统支持：

   • mini系统：针对资源受限的LiteOS-M，使用纯C实现
   • featured系统：针对LiteOS-A，支持C++接口和更多特性

3. 异步处理：

   • 日志先写入缓存，异步刷新到文件/UART
   • 减少日志操作对主业务的阻塞

设计模式

1. 单例模式（Singleton）：

   • 全局配置对象g_hiviewConfig
   • 日志缓存对象g_logCache

2. 观察者模式（Observer）：

   • 日志文件监控：HiLogFileAddWatcher/HiLogFileRemoveWatcher
   • 支持注册回调函数处理日志事件

3. 策略模式（Strategy）：

   • 多种输出策略：DEBUG输出、FLOW输出、TEXT_FILE、BIN_FILE
   • 通过配置选择不同的输出策略

4. 生产者-消费者模式：

   • 日志产生方（各模块）作为生产者
   • hilogcat/apphilogcat作为消费者
   • 通过Ring Buffer解耦

1.4 系统框图

┌─────────────────────────────────────────────────────────────────────────┐ │ 应用/服务层 │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ SAMGR │ │ ACE │ │ AAFWK │ │ MEDIA │ │ APP │ ... │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ │ │ └────────────┴────────────┼────────────┴────────────┘ │ │ ▼ │ ├─────────────────────────────────────────────────────────────────────────┤ │ HiLog_Lite 接口层 │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ HILOG_DEBUG/INFO/WARN/ERROR/FATAL (C Macro) │ │ │ │ HiLog::Debug/Info/Warn/Error/Fatal (C++ Class) │ │ │ │ console.debug/info/warn/error (JS API) │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ ├─────────────────────────────────────────────────────────────────────────┤ │ HiLog_Lite 框架层 │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ │ │ hiview_log.c │ │ hiview_output │ │ hiview_log_limit │ │ │ │ (日志核心) │ │ _log.c │ │ .c (限流控制) │ │ │ │ - 模块注册 │ │ - 格式化输出 │ │ - 频率限制 │ │ │ │ - 参数解析 │ │ - 缓存管理 │ │ - 阈值配置 │ │ │ │ - 日志打印 │ │ - 文件写入 │ │ │ │ │ └────────┬────────┘ └────────┬────────┘ └──────────┬──────────┘ │ │ │ │ │ │ │ └────────────────────┼──────────────────────┘ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ HiviewCache (环形缓冲区) │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ │ │ ├────────────────────────────────┼────────────────────────────────────────┤ │ 服务层│ │ │ ┌────────────────────┼────────────────────┐ │ │ ▼ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ hilogcat │ │ apphilogcat │ │ hilog_command │ │ │ │ (日志查看) │ │ (日志落盘) │ │ (命令行工具) │ │ │ └────────┬────────┘ └────────┬────────┘ └─────────────────┘ │ │ │ │ │ │ └────────────────────┼────────────────────────────────────────┤ │ ▼ │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ /dev/hilog (设备驱动) │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ │ │ ├────────────────────────────────┼────────────────────────────────────────┤ │ 内核层│ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ hilogtask (内核日志任务) │ │ │ │ Ring Buffer (内核环形缓冲区) │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ UART │ │ Log Files │ │ │ │ (串口输出) │ │ (日志文件) │ │ │ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────────────┘

2. 模块结构

2.1 源文件与头文件

2.1.1 目录结构

hiviewdfx_hilog_lite/ ├── interfaces/ # 接口定义 │ └── native/ │ ├── innerkits/hilog/ # 内部接口（小型系统） │ │ ├── log.h # 日志API入口 │ │ ├── hilog_cp.h # C++接口定义 │ │ ├── hiview_log.h # 核心日志接口 │ │ └── hilog_trace.h # 追踪接口 │ └── kits/ │ ├── hilog/log.h # 小型系统外部接口 │ └── hilog_lite/ # 轻量系统外部接口 │ ├── log.h │ └── hiview_log.h ├── frameworks/ # 框架实现 │ ├── mini/ # 轻量系统实现 │ │ ├── hiview_log.c # 日志核心实现 │ │ ├── hiview_output_log.c # 日志输出实现 │ │ ├── hiview_output_log.h │ │ ├── hiview_log_limit.c # 日志限流实现 │ │ └── hiview_log_limit.h │ ├── featured/ # 小型系统实现 │ │ ├── hilog.cpp # C++接口实现 │ │ └── hiview_log.c # 日志核心实现 │ └── js/ # JS接口实现 │ └── builtin/ │ ├── include/ │ │ ├── hilog_module.h │ │ ├── hilog_string.h │ │ ├── hilog_vector.h │ │ └── hilog_wrapper.h │ └── src/ │ ├── hilog_module.cpp │ ├── hilog_string.cpp │ └── hilog_vector.cpp ├── services/ # 服务实现 │ ├── hilogcat/ # 日志查看服务 │ │ └── hiview_logcat.c │ └── apphilogcat/ # 日志落盘服务 │ └── hiview_applogcat.c ├── command/ # 命令行工具 │ ├── hilog_command.c │ └── hilog_command.h └── test/ # 测试代码 └── unittest/ ├── hilog_lite_test.cpp └── hilog_lite_test.h

2.1.2 文件功能说明

2.2 类、结构体、函数与方法

2.2.1 核心枚举类型

// 日志模块类型（轻量系统）typedefenum{HILOG_MODULE_HIVIEW=0,// DFX模块HILOG_MODULE_SAMGR,// 系统服务管理HILOG_MODULE_UPDATE,// 升级模块HILOG_MODULE_ACE,// 应用框架HILOG_MODULE_APP,// 第三方应用HILOG_MODULE_AAFWK,// 原子化服务框架HILOG_MODULE_GRAPHIC,// 图形模块HILOG_MODULE_MEDIA,// 多媒体模块HILOG_MODULE_DMS,// 分布式调度HILOG_MODULE_SEN,// 传感器HILOG_MODULE_SCY,// 安全模块HILOG_MODULE_SOFTBUS,// 软总线HILOG_MODULE_POWERMGR,// 电源管理HILOG_MODULE_UIKIT,// UI框架HILOG_MODULE_GLOBAL,// 全局子系统HILOG_MODULE_DATAMGR,// 数据管理HILOG_MODULE_INIT,// 初始化HILOG_MODULE_MAX=64// 最大模块数}HiLogModuleType;// 日志级别（小型系统）typedefenum{LOG_DEBUG=3,// 调试级别LOG_INFO=4,// 信息级别LOG_WARN=5,// 警告级别LOG_ERROR=6,// 错误级别LOG_FATAL=7,// 致命级别}LogLevel;// 日志类型typedefenum{LOG_TYPE_MIN=0,LOG_INIT=1,// 初始化阶段日志LOG_CORE=3,// 核心服务日志LOG_TYPE_MAX}LogType;

2.2.2 核心结构体

// 日志通用头信息（轻量系统）#pragmapack(1)typedefstruct{uint8 head;// 日志头标识uint8 module;// 模块IDuint8 level:4;// 日志级别uint8 valueNumber:4;// 参数个数uint8 task;// 任务IDuint32 time;// 时间戳（秒）uint16 milli;// 毫秒constchar*fmt;// 格式化字符串}HiLogCommon;// 日志内容typedefstruct{HiLogCommon commonContent;uint32 values[LOG_MULTI_PARA_MAX];// 参数值（最多6个）}HiLogContent;#pragmapack()// 日志条目（小型系统）structHiLogEntry{unsignedintlen;// 日志长度unsignedinthdrSize;// 头部大小unsignedintpid:16;// 进程IDunsignedinttaskId:16;// 任务IDunsignedintsec;// 时间戳（秒）unsignedintnsec;// 纳秒unsignedintreserved;// 保留字段charmsg[0];// 日志消息（柔性数组）};// 日志限流规则typedefstruct{uint8 maxNum;// 最大日志行数限制uint8 logNum;// 当前日志计数uint16 baseTime;// 基准时间uint32 totalLogNum;// 总日志数uint32 totalDropLogNum;// 丢弃日志数}HiLogLimitRule;// 配置结构体typedefstruct{constunsignedcharoutputOption:4;// 输出选项unsignedcharhiviewInited:1;// 初始化标志unsignedcharlevel:3;// 日志级别unsignedcharlogSwitch:1;// 日志开关unsignedchareventSwitch:1;// 事件开关unsignedchardumpSwitch:1;// dump开关unsignedcharsilenceMod:1;// 静默模式charlogOutputModule[6];// 输出模块过滤unsignedshortwriteFailureCount;// 写入失败计数}HiviewConfig;

2.2.3 C++ 类定义

namespaceOHOS{namespaceHiviewDFX{// 日志标签结构structHiLogLabel{LogType type;// 日志类型unsignedintdomain;// 领域IDconstchar*tag;// 日志标签};// HiLog 类（静态方法类）classHiLogfinal{public:// 输出调试日志staticintDebug(constHiLogLabel&label,constchar*fmt,...)__attribute__((__format__(printf,2,3)));// 输出信息日志staticintInfo(constHiLogLabel&label,constchar*fmt,...)__attribute__((__format__(printf,2,3)));// 输出警告日志staticintWarn(constHiLogLabel&label,constchar*fmt,...)__attribute__((__format__(printf,2,3)));// 输出错误日志staticintError(constHiLogLabel&label,constchar*fmt,...)__attribute__((__format__(printf,2,3)));// 输出致命日志staticintFatal(constHiLogLabel&label,constchar*fmt,...)__attribute__((__format__(printf,2,3)));};}// namespace HiviewDFX}// namespace OHOS

2.2.4 核心函数

模块注册与管理：

// 注册模块信息booleanHiLogRegisterModule(uint16 id,constchar*name);// 获取模块名称constchar*HiLogGetModuleName(uint8 id);// 获取/设置日志级别uint32HiLogGetLogLevel(void);booleanHiLogSetLogLevel(uint8 level);

日志输出：

// 轻量系统日志打印voidHiLogPrintf(uint8 module,uint8 level,constchar*nums,constchar*fmt,...);// 小型系统日志打印intHiLogPrint(LogType type,LogLevel level,unsignedintdomain,constchar*tag,constchar*fmt,...);// 带参数列表的日志打印intHiLogPrintArgs(LogType bufID,LogLevel prio,unsignedintdomain,constchar*tag,constchar*fmt,va_list ap);

日志管理：

// 刷新日志缓冲区voidHiLogFlush(boolean syncFlag);intFlushHilog(void);// 日志输出到文件voidOutputLog(constuint8*data,uint32 len);// 日志格式化int32LogContentFmt(char*outStr,int32 outStrLen,constuint8*pLogContent);

回调注册：

// 日志处理回调类型typedefboolean(*HilogProc)(constHiLogContent*hilogContent,uint32 len);// 注册/注销日志处理器voidHiLogRegisterProc(HilogProc func);voidHiLogUnRegisterProc(HilogProc func);// 文件监控回调类型typedefvoid(*FileProc)(constchar*path,uint8 type,uint8 event);// 注册/注销文件监控voidHiLogFileAddWatcher(FileProc func,constchar*dest);voidHiLogFileRemoveWatcher(FileProc func);

2.3 类图

2.4 模块内部依赖框图

3. 模块间交互

3.1 交互描述

3.1.1 与外部模块的交互

3.1.2 异步处理机制

3.1.3 多线程处理

• 互斥锁保护：使用g_logFlushInfo.mutex和g_outputLogInfo.mutex保护关键资源
• 原子操作：使用atomic_int保护回调函数引用计数
• 消息队列：通过 SAMGR 消息机制实现线程间通信

3.2 外部依赖框图

4. 状态机转换图

4.1 状态机模型

HiLog_Lite 模块包含两个主要的状态机：

1. 日志系统状态机：管理整个日志系统的生命周期
2. 日志输出状态机：管理单条日志的处理流程

4.2 状态机树图

4.3 状态切换规则

4.3.1 系统状态转换

4.3.2 日志处理状态转换

4.4 状态机转换图

4.5 日志处理流程图

5. 接口设计

5.1 公共接口

5.1.1 C语言宏接口（轻量系统）

/** * @brief 输出调试级别日志 * @param mod 模块ID，类型为HiLogModuleType * @param fmt 格式化字符串，不支持%s，最多6个参数 * @return 无返回值 * @note 格式化后单条日志最大128字节 */#defineHILOG_DEBUG(mod,fmt,...)/** * @brief 输出信息级别日志 * @param mod 模块ID * @param fmt 格式化字符串 */#defineHILOG_INFO(mod,fmt,...)/** * @brief 输出警告级别日志 * @param mod 模块ID * @param fmt 格式化字符串 */#defineHILOG_WARN(mod,fmt,...)/** * @brief 输出错误级别日志 * @param mod 模块ID * @param fmt 格式化字符串 */#defineHILOG_ERROR(mod,fmt,...)/** * @brief 输出致命级别日志 * @param mod 模块ID * @param fmt 格式化字符串 */#defineHILOG_FATAL(mod,fmt,...)

5.1.2 C语言宏接口（小型系统）

/** * @brief 输出调试级别日志 * @param type 日志类型（LOG_CORE等） * @param fmt 格式化字符串，支持{public}/{private}隐私标记 * @return 成功返回>=0，失败返回<0 * @example HILOG_DEBUG(LOG_CORE, "value=%{public}d", value); */#defineHILOG_DEBUG(type,...)#defineHILOG_INFO(type,...)#defineHILOG_WARN(type,...)#defineHILOG_ERROR(type,...)#defineHILOG_FATAL(type,...)

5.1.3 C++类接口

namespaceOHOS{namespaceHiviewDFX{classHiLog{public:/** * @brief 输出调试日志 * @param label 日志标签，包含type、domain、tag * @param fmt 格式化字符串 * @return 成功返回写入字节数，失败返回<0 */staticintDebug(constHiLogLabel&label,constchar*fmt,...);staticintInfo(constHiLogLabel&label,constchar*fmt,...);staticintWarn(constHiLogLabel&label,constchar*fmt,...);staticintError(constHiLogLabel&label,constchar*fmt,...);staticintFatal(constHiLogLabel&label,constchar*fmt,...);};}// namespace HiviewDFX}// namespace OHOS

5.1.4 模块管理接口

/** * @brief 注册日志模块 * @param id 模块ID，范围0-63 * @param name 模块名称，最长15个字母 * @return TRUE成功，FALSE失败 * @note 未注册的模块无法输出日志 */booleanHiLogRegisterModule(uint16 id,constchar*name);/** * @brief 获取模块名称 * @param id 模块ID * @return 模块名称字符串，无效ID返回空字符串 */constchar*HiLogGetModuleName(uint8 id);/** * @brief 获取当前日志级别 * @return 当前配置的日志级别 */uint32HiLogGetLogLevel(void);/** * @brief 设置日志级别 * @param level 日志级别，HILOG_LV_DEBUG到HILOG_LV_FATAL * @return TRUE成功，FALSE失败 */booleanHiLogSetLogLevel(uint8 level);

5.1.5 日志控制接口

/** * @brief 刷新日志缓冲区 * @param syncFlag TRUE同步刷新，FALSE异步刷新 */voidHiLogFlush(boolean syncFlag);/** * @brief 刷新日志到驱动（小型系统） * @return 写入字节数 */intFlushHilog(void);/** * @brief 获取日志配置选项 * @return 输出选项值 */uint32HiLogGetConfigOption(void);

5.1.6 回调注册接口

/** * @brief 日志处理回调函数类型 * @param hilogContent 日志内容指针 * @param len 日志长度 * @return TRUE表示已处理，平台不再处理；FALSE继续处理 */typedefboolean(*HilogProc)(constHiLogContent*hilogContent,uint32 len);/** * @brief 注册日志处理器 * @param func 回调函数指针 */voidHiLogRegisterProc(HilogProc func);/** * @brief 注销日志处理器 * @param func 回调函数指针 */voidHiLogUnRegisterProc(HilogProc func);/** * @brief 文件处理回调函数类型 * @param path 文件路径 * @param type 文件类型 * @param event 事件类型，0表示文件满 */typedefvoid(*FileProc)(constchar*path,uint8 type,uint8 event);/** * @brief 添加日志文件监控 * @param func 回调函数 * @param dest 目标文件路径 */voidHiLogFileAddWatcher(FileProc func,constchar*dest);/** * @brief 移除日志文件监控 * @param func 回调函数 */voidHiLogFileRemoveWatcher(FileProc func);

5.2 数据交换接口

5.2.1 设备驱动接口

// 设备节点路径#defineHILOG_DRIVER"/dev/hilog"// 日志条目结构（与驱动交互）structHiLogEntry{unsignedintlen;// 总长度unsignedinthdrSize;// 头部大小unsignedintpid:16;// 进程IDunsignedinttaskId:16;// 任务IDunsignedintsec;// 时间戳（秒）unsignedintnsec;// 纳秒unsignedintreserved;// 保留charmsg[0];// 日志消息};// 读取日志intfd=open(HILOG_DRIVER,O_RDONLY);read(fd,buf,HILOG_LOGBUFFER);// 写入日志intfd=open(HILOG_DRIVER,O_WRONLY);write(fd,buf,strlen(buf)+1);

5.2.2 追踪ID接口

/** * @brief 追踪ID获取函数类型 * @param chainId 链路ID输出 * @param flag 标志位输出 * @param spanId SpanID输出 * @param parentSpanId 父SpanID输出 * @return 0成功，-1无效 */typedefint(*RegisterFunc)(uint64_t*,uint32_t*,uint64_t*,uint64_t*);/** * @brief 注册追踪ID获取函数 * @param registerFunc 回调函数 * @return 0成功，-1失败 */intHiLogRegisterGetIdFun(RegisterFunc registerFunc);/** * @brief 注销追踪ID获取函数 * @param registerFunc 回调函数 */voidHiLogUnregisterGetIdFun(RegisterFunc registerFunc);

5.3 接口调用时序图

5.3.1 日志输出时序图

5.3.2 日志查看时序图

5.4 异常处理

附录

A. 编译配置选项

B. 使用示例

B.1 轻量系统使用示例

#include"log.h"// 1. 注册模块（如果是新模块）HiLogRegisterModule(HILOG_MODULE_APP,"MYAPP");// 2. 输出日志HILOG_DEBUG(HILOG_MODULE_APP,"Debug message: %d",100);HILOG_INFO(HILOG_MODULE_APP,"Info message");HILOG_ERROR(HILOG_MODULE_APP,"Error code: %d",errno);

B.2 小型系统使用示例

#include<hilog/log.h>// 1. 定义日志标签#defineLOG_DOMAIN0x0001#defineLOG_TAG"MyModule"// 2. 输出日志（支持隐私标记）HILOG_INFO(LOG_CORE,"User name: %{private}s, age: %{public}d",name,age);

B.3 C++使用示例

#include"hilog/log.h"usingnamespaceOHOS::HiviewDFX;// 定义日志标签staticconstexprHiLogLabel LABEL={LOG_CORE,0x0001,"MyModule"};// 输出日志HiLog::Info(LABEL,"Info message: %{public}d",value);HiLog::Error(LABEL,"Error occurred: %{public}s",errorMsg);