仓颉应用 HiLog 日志打印实战:ohos.hilog 接口详解与 hilog 命令行排查指南

原创2026-10-15 13:42:041,920 阅读
文章标签:文档知识库

仓颉应用 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打印日志(仓颉) 中的"参数解析"一节,还有三条实战要点值得强调:

  1. domain 与 tag 的搭配:domain 用于划分业务领域,取值范围 0x0000~0xFFFF,建议按模块或功能自定义,如 0xFF00 代表某个业务域;tag 建议标识调用所在的类或业务行为。二者组合后可以在日志工具中被精确过滤(见下文 hilog -D/-T 命令)。
  2. 隐私标识是强制规范:凡是需要输出的动态内容都应显式给出隐私标识。{public} 修饰的内容在日志中明文输出;{private}(或缺省)修饰的内容会以 <private> 过滤回显,防止用户隐私数据落盘。例如 "Failed to open file, uri: ${uri}" 中若 uri 属于敏感数据,应写成 "Failed to open file, uri: {private}s" 并传入对应参数,保证真机日志不泄露明文。
  3. 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 仓颉工程中通过按钮触发日志输出的完整流程:

  1. 新建一个工程,选择 "[Cangjie] Empty Ability"。
  2. 在 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)
    }
}
  1. 在真机上运行该工程,单击应用/服务界面上的按钮。
  2. 在 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(换行时新行不增加时间戳前缀)等选项,便于在脚本化分析或长时间观察时选择合适的时间精度。

常见问题与最佳实践小结

  1. 日志打不出来,先检查级别:DEBUG 默认不打印;全局/domain/tag 级别可通过 hilog -b 调整。若日志仍未出现,检查 domain 是否超出 0x0~0xFFFF 范围。
  2. tag 超长被截断、中文乱码:tag 最多 31 字节,超出截断;不建议使用中文字符,避免乱码或对齐问题。
  3. 单条日志超过 4096 字节被截断:需要精简 format 或拆分为多条日志输出。
  4. 敏感信息务必加 {private}:format 中缺省即为 {private},动态内容会以 <private> 回显;确需明文的业务数据才使用 {public},并确保 args 的参数数目、类型与格式字符串标识一一对应。
  5. isLoggable 与打印方法参数保持一致:domain、tag、level 三要素对齐,才能正确判断日志是否会被输出;将日志构造放入 isLoggable 为 true 的分支可避免无谓开销。
  6. 合理划分 domain 与 tag:建议按业务领域自定义 domain(如 0xFF00),tag 标识类或业务行为,这样既能配合 hilog -D/-T 精准过滤,也能在 HiAppEvent 崩溃事件 等 DFX 场景中快速定位到相关日志上下文。

围绕上述要点,本文涉及的完整接口签名、参数表格与示例代码均可回查 cj-apis-hilog.md,命令行细节可查阅 hilog 工具说明 与 使用HiLog打印日志(仓颉),以便在实际工程中按需取用。

登录后查看全文
CangjieCorpus