仓颉应用 HiLog 日志打印实战:ohos.hilog 接口详解与 hilog 命令行排查指南
仓颉应用 HiLog 日志打印实战:ohos.hilog 接口详解与 hilog 命令行排查指南
本文以 OpenHarmony 仓颉 API 参考文档 cj-apis-hilog.md 为骨架,系统讲解仓颉应用通过 Hilog 类按照指定级别、标识和格式字符串输出日志的方法,并结合 使用HiLog打印日志(仓颉) 与 hilog 命令行工具 给出可复制的开发与排查方案。读完本文,你将掌握 Hilog 五个日志级别接口的参数语义、隐私标识 {public}/{private} 的使用规则、isLoggable 预检查技巧,以及如何用 DevEco Studio Log 窗口和 hdc shell hilogcat/hilog 命令过滤、导出、统计日志。
HiLog 是什么:仓颉应用/服务的日志系统
ohos.hilog 模块(位于 Performance Analysis Kit,即性能分析服务)使应用/服务可以按照指定级别、标识和格式字符串输出日志内容,帮助开发者了解应用/服务的运行状态,更好地调试程序。它是 HiviewDFX(分布式 DFX 框架)提供的日志子系统面向仓颉开发者的接口封装,所依赖的系统能力为 SystemCapability.HiviewDFX.HiLog,接口起始版本为 22。
在仓颉 API 中,日志能力统一由 kit.PerformanceAnalysisKit 提供,该 Kit 下还包含应用事件打点 ohos.hiviewdfx.hi_app_event 与性能打点 ohos.hi_tracemeter(见 PerformanceAnalysisKit 目录索引)。本篇文章聚焦其中面向日志打印的 ohos.hilog 模块。
导入模块与示例工程约定
在仓颉代码中使用 HiLog,首先导入 Kit 模块:
import kit.PerformanceAnalysisKit.*
参考文档中的 API 示例并非完整程序,而是对应 API 的核心代码。理解示例需要两条约定(详见 仓颉示例代码说明):
- 若示例代码首行有
// index.cj注释,表示该示例可在仓颉模板工程的index.cj文件中编译运行; - 若示例需获取 Context 应用上下文,需在仓颉模板工程的
main_ability.cj文件中进行配置。
一个可运行的模板工程会生成 index.cj、main_ability.cj、ability_stage.cj 三个文件;其中 main_ability.cj 中通常会在 onCreate/onWindowStageCreate 生命周期回调里直接使用 Hilog.info 输出日志(如 Hilog.info(0, "system", "MainAbility OnCreated.${want.abilityName}")),这本身就是 HiLog 在真实工程中最典型的使用场景。
class Hilog:核心日志对象
public class Hilog {}
Hilog 是日志系统对象,使应用/服务可以按照指定级别、标识和格式字符串输出日志内容,提供 DEBUG、INFO、WARNING、ERROR、FATAL 不同级别的日志打印方法。全部方法均为 static func,可直接以 Hilog.xxx(...) 形式调用。
日志打印方法的统一参数模型
debug、info、warn、error、fatal 五个打印方法的签名结构完全一致,均接收四个参数:
public static func debug(domain: UInt32, tag: String, format: String, args: Array<String>): Unit
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|---|---|---|---|---|
| domain | UInt32 | 是 | - | 日志对应的领域标识,范围是 0x0~0xFFFF,超出范围则日志无法打印。建议开发者在应用内根据需要自定义划分。 |
| tag | String | 是 | - | 指定日志标识,可以为任意字符串,建议用于标识调用所在的类或者业务行为。tag 最多为 31 字节,超出后会截断,不建议使用中文字符,可能出现乱码或者对齐问题。 |
| format | String | 是 | - | 格式字符串,用于日志的格式化输出。格式字符串中可以设置多个参数,参数需要包含参数类型、隐私标识。隐私标识分为 {public} 和 {private},缺省为 {private}。标识 {public} 的内容明文输出,标识 {private} 的内容以 <private> 过滤回显。 |
| args | Array<String> | 是 | - | 与格式字符串 format 对应的可变长度参数列表。参数数目、参数类型必须与格式字符串中的标识一一对应。 |
关于这几个参数,结合 使用HiLog打印日志(仓颉) 中的"参数解析"一节,还有三条实战要点值得强调:
- domain 与 tag 的搭配:
domain用于划分业务领域,取值范围0x0000~0xFFFF,建议按模块或功能自定义,如0xFF00代表某个业务域;tag建议标识调用所在的类或业务行为。二者组合后可以在日志工具中被精确过滤(见下文hilog -D/-T命令)。 - 隐私标识是强制规范:凡是需要输出的动态内容都应显式给出隐私标识。
{public}修饰的内容在日志中明文输出;{private}(或缺省)修饰的内容会以<private>过滤回显,防止用户隐私数据落盘。例如"Failed to open file, uri: ${uri}"中若uri属于敏感数据,应写成"Failed to open file, uri: {private}s"并传入对应参数,保证真机日志不泄露明文。 - args 与 format 严格一一对应:参数数目、参数类型必须与格式字符串中的标识一一对应,否则格式解析会出现错位或异常。
debug:调试级别日志
public static func debug(domain: UInt32, tag: String, format: String, args: Array<String>): Unit
打印 DEBUG 级别的日志。DEBUG 级别的日志在正式发布版本中默认不被打印,只有在调试版本或打开调试开关的情况下才会打印。在 DevEco Studio 的 terminal 窗口或 cmd 里,可通过命令 hdc shell hilogcat 设置可打印日志的等级为 DEBUG(也可使用下文介绍的 hilog -b D 调整全局最低日志级别)。
示例(来自 API 参考文档,可编译运行):
// index.cj
import ohos.base.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
try {
Hilog.debug(0, "testTag", "Debug: Hello world!")
} catch (e: BusinessException) {
Hilog.info(0, "test", "${e.message}")
}
info / warn:常规信息与警告日志
public static func info(domain: UInt32, tag: String, format: String, args: Array<String>): Unit
public static func warn(domain: UInt32, tag: String, format: String, args: Array<String>): Unit
info 用于打印 INFO 级别日志(普通信息),warn 用于打印 WARN 级别日志(存在警告)。对应示例:
// index.cj
import ohos.base.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
try {
Hilog.info(0, "testTag", "Info: Hello world!")
} catch (e: BusinessException) {
Hilog.info(0, "test", "${e.message}")
}
// index.cj
import ohos.base.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
try {
Hilog.warn(0, "testTag", "Warn: Hello world!")
} catch (e: BusinessException) {
Hilog.info(0, "test", "${e.message}")
}
error / fatal:错误与致命日志
public static func error(domain: UInt32, tag: String, format: String, args: Array<String>): Unit
public static func fatal(domain: UInt32, tag: String, format: String, args: Array<String>): Unit
error 打印 ERROR 级别日志(存在错误),fatal 打印 FATAL 级别日志(致命错误、不可恢复错误)。对应示例:
// index.cj
import ohos.base.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
try {
Hilog.error(0, "testTag", "Error: Hello world!")
} catch (e: BusinessException) {
Hilog.info(0, "test", "${e.message}")
}
// index.cj
import ohos.base.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
try {
Hilog.fatal(0, "testTag", "Fatal: Hello world!")
} catch (e: BusinessException) {
Hilog.info(0, "test", "${e.message}")
}
在真实工程中,error 通常与异常处理配对使用。例如在 文件处理应用启动场景 中,startAbility 失败后通过 Hilog.error(1, "info", "Failed to invoke startAbility, code: ${e.code}, message: ${e.message}") 记录错误码与错误信息;在 UIAbility 交互场景 中同样使用 ${e.code}、${e.message} 插值记录异常细节。这种"异常分支必打 error、关键流程节点打 info"的写法是仓颉工程中的通用日志规范。
enum LogLevel:五级日志语义
isLoggable 接口以及日志级别过滤都依赖 LogLevel 枚举:
public enum LogLevel {
| Debug
| Info
| Warning
| Error
| Fatal
| ...
}
五个枚举值的官方语义如下(均起始版本 22,系统能力 SystemCapability.HiviewDFX.HiLog):
| 枚举值 | 功能 |
|---|---|
| Debug | 详细的流程记录,通过该级别的日志可以更详细地分析业务流程和定位分析问题。 |
| Info | 用于记录业务关键流程节点,可以还原业务的主要运行过程;同时用于记录可预料的非正常情况信息,如无网络信号、登录失败等。这些日志应该由该业务内处于支配地位的模块来记录,避免在多个被调用的模块或低级函数中重复记录。 |
| Warning | 用于记录较为严重的非预期情况,但对用户影响不大,应用可以自动恢复或通过简单的操作就可以恢复的问题。 |
| Error | 应用发生了错误,该错误会影响功能的正常运行或用户的正常使用,可以恢复但恢复代价较高,如重置数据等。 |
| Fatal | 重大致命异常,表明应用即将崩溃,故障无法恢复。 |
这里隐含了一条重要的日志规范:日志级别应当"上移"记录位置——Info 及以上的日志由业务内处于支配地位的模块统一记录,避免底层被调用模块、低级函数中重复打点;Debug 仅用于分析业务流程细节。
static func isLoggable:打印前的预检查
public static func isLoggable(domain: UInt32, tag: String, level: LogLevel): Bool
在打印日志前调用该接口,用于检查指定领域标识、日志标识和级别的日志是否可以打印。返回值类型 Bool:返回 true 表示该 domain、tag 和 level 组合的日志可以打印,否则不能打印。
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
| domain | UInt32 | 是 | 日志对应的领域标识,范围 0x0~0xFFFF,超出范围则日志无法打印。 |
| tag | String | 是 | 指定日志标识,建议标识调用所在的类或业务行为,最多 31 字节。 |
| level | LogLevel | 是 | 日志级别。 |
示例(来自 API 参考文档):
// index.cj
import ohos.base.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
try {
let result = Hilog.isLoggable(0, "testTag", LogLevel.Debug)
} catch (e: BusinessException) {
Hilog.info(0, "test", "${e.message}")
}
使用注意事项(依据 使用HiLog打印日志(仓颉)):
isLoggable()和具体日志打印接口使用的domain和tag应保持一致;isLoggable()使用的level应与具体日志打印接口的级别保持一致。
典型用法是把代价较高的日志构造逻辑放进 if 分支:先 isLoggable 判断该级别是否开启,再拼装参数调用对应打印方法,从而在日志被过滤掉时省去不必要的字符串构造开销。
完整开发示例:按钮点击打印日志
以下示例来自 使用HiLog打印日志(仓颉),展示在 ArkUI 仓颉工程中通过按钮触发日志输出的完整流程:
- 新建一个工程,选择 "[Cangjie] Empty Ability"。
- 在 Project 窗口单击
entry > src > main > cangjie,打开工程中的index.cj文件,添加一个按钮,单击按钮打印日志:
// index.cj
import kit.PerformanceAnalysisKit.*
@Entry
@Component
class EntryView {
@State
var message: String = "Hello World"
func build() {
Row {
Column {
Button(this.message)
.fontSize(50)
.fontWeight(FontWeight.Bold)
.onClick ({
evt => this.message = "Hello Cangjie"
Hilog.isLoggable(0xFF00, "testTag", LogLevel.Info)
Hilog.info(0xFF00, "testTag", "hello world")
// 设置应用日志最低打印级别,设置完成后,低于Warn级别的日志将无法打印
Hilog.info(0x0000, 'testTag', 'this is an info level log')
Hilog.error(0x0000, 'testTag', 'this is an error level log')
})
}.width(100.percent)
}.height(100.percent)
}
}
- 在真机上运行该工程,单击应用/服务界面上的按钮。
- 在 DevEco Studio 的底部,切换到 "Log" 窗口,设置日志的过滤条件:选择当前的设备及进程,日志级别选择 Verbose,搜索内容设置为
testTag。此时窗口仅显示符合条件的日志。
打印日志结果为:
01-02 08:18:24.947 30988-30988 A0ff00/testTag com.example.hilogemo I hello World
01-02 08:18:24.947 30988-30988 A00000/testTag com.example.hilogemo E this is an error level log
从输出可以看到 HiLog 行的典型字段:时间戳、进程-线程号、A + domain(如 A0ff00、A00000)、tag、所属 bundle 名、级别字母(I/E 等)以及日志正文。
约束与限制:日志最多打印 4096 字节,超出限制的文本将被截断。因此超长日志应拆分输出或精简内容,避免关键信息被截断丢失。
日志查看与排查:hilog 命令行工具
运行应用后,除了 DevEco Studio 的 Log 窗口,还可以通过 hdc shell 进入设备后使用 hilog 命令行查询、过滤、导出日志(完整命令说明见 hilog 命令行工具)。环境要求是:根据 hdc 命令行工具指导完成环境准备,并确保设备已正常连接、执行 hdc shell。
核心查询选项速查
| 短选项 | 长选项 | 参数 | 说明 |
|---|---|---|---|
| -h | --help | - | 帮助命令。 |
| 缺省 | 缺省 | - | 阻塞读日志,不退出。 |
| -x | --exit | - | 非阻塞读日志,读完退出。 |
| -L | --level | <level> | 指定级别的日志,示例:-L D/I/W/E/F。 |
| -t | --type | <type> | 指定类型的日志,示例:-t app/core/init/only_prerelease。app 为应用日志,core 为系统日志,init 为启动日志。 |
| -D | --domain | <domain> | 指定 domain。 |
| -T | --tag | <tag> | 指定 tag。 |
| -P | --pid | <pid> | 标识不同的 pid。 |
| -e | --regex | <expr> | 只打印日志消息与正则表达式匹配的行。 |
| -a | --head | <n> | 只显示前 n 行日志。 |
| -z | --tail | <n> | 只显示后 n 行日志。 |
| -b | --baselevel | <loglevel> | 设置可打印日志的最低等级:D(Debug)/I(Info)/W(Warn)/E(Error)/F(Fatal)。 |
| -g | - | - | 查询 buffer 的大小,配合 -t 指定某一类型使用,默认 app 和 core。 |
| -G | --buffer-size | <size> | 设置日志类型缓冲区的大小,配合 -t 指定某一类型,默认 app 和 core,可使用 B/K/M 为单位,范围为 64K-16M。 |
| -r | - | - | 清除 buffer 日志,配合 -t 指定某一类型,默认 app 和 core。 |
| -s | --statistics | - | 查询统计信息,需配合 -t 或 -D 使用。 |
| -S | - | - | 清除统计信息,需配合 -t 或 -D 使用。 |
| -Q | - | <control-type> | 流控缺省配额开关控制:pidon/pidoff 为进程流控开关,domainon/domainoff 为 domain 流控开关。 |
| -f / -l / -n / -j | --filename / --length / --number / --jobid | - | 落盘相关:设置落盘文件名、单文件大小(需大于等于 64K)、文件个数、任务 ID。 |
| -w | --write | <control> | 落盘任务控制:query 查询、start 开始、stop 停止、refresh 刷新、clear 删除。 |
| -m | --stream | <algorithm> | 落盘方式:none 无压缩、zlib 压缩为 .gz、zstd 压缩为 .zst。 |
| -v | --format | <format> | 显示格式控制:time/color/epoch/monotonic/usec/nsec/year/zone/wrap。 |
与仓颉 HiLog 参数一一对应的过滤用法
结合上方 API 中的 domain、tag、level 三个核心维度,hilog 命令可以这样精确过滤:
# 查看指定级别日志(对应 LogLevel)
hilog -L E
# 查看指定类型日志(应用日志)
hilog -t app
# 查看指定 domain 日志(对应 debug/info 中的 domain 参数)
hilog -D 01B06
# 查看指定 TAG 日志(对应 debug/info 中的 tag 参数)
hilog -T testTag
# 查看指定进程日志
hilog -P 618
# 查看符合正则匹配关键字的日志
hilog -e start
设置日志最低级别
仓颉侧通过 isLoggable 判断"能否打印",而设备侧则通过 hilog -b 设置可打印日志的最低等级:
# 全局日志级别默认为 Info,查询全局日志级别
param get hilog.loggable.global
# 设置全局日志级别
hilog -b D/I/W/E/F
# 设置[DOMAINID]可打印的日志级别
hilog -b D/I/W/E/F -D [DOMAINID]
# 设置[TAG]可打印的日志级别
hilog -b D/I/W/E/F -T [TAG]
# 设置全局日志级别,重启仍生效
hilog -b D/I/W/E/F --persist
使用样例:
$ param get hilog.loggable.global
I
$ hilog -b E
Set global log level to E successfully
$ hilog -b D -D 0x2d00
Set domain 0x2d00 log level to D successfully
$ hilog -b E -T testTag
Set tag testTag log level to E successfully
这也解释了前文"DEBUG 日志默认不打印"的机制:全局最低级别默认是 Info,只有通过 hilog -b D(或调试版本)把级别调低后,DEBUG 日志才会输出。
缓冲区管理、落盘与统计
开发调试中还常用到以下能力:
# 查询缓冲区大小
hilog -g
# 修改日志缓冲区大小(B/K/M 为单位,范围 64K-16M)
hilog -G 16M
# 清除缓冲区日志
hilog -r
# 查询统计信息(需先在系统参数中开启统计并重启设备)
hilog -s
# 清除统计信息
hilog -S
# 进程流控/domain 流控开关
hilog -Q pidon / hilog -Q pidoff
hilog -Q domainon / hilog -Q domainoff
统计信息(hilog -s)输出中的关键字段含义为:MAX_FREQ(日志打印频率最高的每秒行数)、MAX_TP(日志打印频率最高的每秒字节数)、LINES(统计周期内的总行数)、LENGTH(统计周期内的总字节数)、DROPPED(统计周期内丢失的行数)。当怀疑日志被流控丢弃时,可通过这些字段量化排查。
日志落盘任务控制示例如下(适合长时间后台运行、需要留存日志的场景):
# 查询当前任务
hilog -w query
# 开启落盘任务,设置落盘文件数量为 1000 个
hilog -w start -n 1000
# 开启 kmsglog 落盘任务,文件数量 100 个
hilog -w start -n 100 -t kmsg
# 停止当前落盘任务
hilog -w stop
# 开启 kmsglog 落盘任务:文件名为 kmsglog,大小 2M,数量 100 个,zlib 压缩
hilog -w start -t kmsg -f kmsglog -l 2M -n 100 -m zlib
显示格式控制(hilog -v)支持 time(本地时间)、color(不同级别不同颜色)、epoch(相对 1970 时间)、monotonic(相对启动时间)、usec/nsec(微秒/纳秒精度)、year、zone、wrap(换行时新行不增加时间戳前缀)等选项,便于在脚本化分析或长时间观察时选择合适的时间精度。
常见问题与最佳实践小结
- 日志打不出来,先检查级别:DEBUG 默认不打印;全局/domain/tag 级别可通过
hilog -b调整。若日志仍未出现,检查 domain 是否超出0x0~0xFFFF范围。 - tag 超长被截断、中文乱码:tag 最多 31 字节,超出截断;不建议使用中文字符,避免乱码或对齐问题。
- 单条日志超过 4096 字节被截断:需要精简 format 或拆分为多条日志输出。
- 敏感信息务必加
{private}:format 中缺省即为{private},动态内容会以<private>回显;确需明文的业务数据才使用{public},并确保args的参数数目、类型与格式字符串标识一一对应。 isLoggable与打印方法参数保持一致:domain、tag、level 三要素对齐,才能正确判断日志是否会被输出;将日志构造放入isLoggable为 true 的分支可避免无谓开销。- 合理划分 domain 与 tag:建议按业务领域自定义 domain(如
0xFF00),tag 标识类或业务行为,这样既能配合hilog -D/-T精准过滤,也能在 HiAppEvent 崩溃事件 等 DFX 场景中快速定位到相关日志上下文。
围绕上述要点,本文涉及的完整接口签名、参数表格与示例代码均可回查 cj-apis-hilog.md,命令行细节可查阅 hilog 工具说明 与 使用HiLog打印日志(仓颉),以便在实际工程中按需取用。