仓颉应用 Performance Analysis Kit(性能分析服务)开发指南:HiAppEvent、HiLog 与 HiTraceMeter 全解析
仓颉应用 Performance Analysis Kit(性能分析服务)开发指南:HiAppEvent、HiLog 与 HiTraceMeter 全解析
Performance Analysis Kit(性能分析服务)是鸿蒙系统中面向应用运行可观测性的服务能力集,在仓颉(Cangjie)语言侧通过 kit.PerformanceAnalysisKit.* 模块对外提供统一 API,涵盖应用事件打点(HiAppEvent)、流水日志打印(HiLog)与性能打点跟踪(HiTraceMeter)三大能力。本文以本仓库中 PerformanceAnalysisKit API 参考文档 为主体,结合 dfx 能力介绍与开发指南,系统讲解在仓颉工程中如何完成事件设计、打点写入、事件订阅、数据处理者上报、日志打印与性能跟踪,帮助开发者快速构建应用调试、问题定位与线上监控能力。
一、能力全景:Performance Analysis Kit 是什么
根据 Performance Analysis Kit 简介,该 Kit 为开发者提供应用事件、日志、跟踪三类分析工具,可观测应用运行时状态,用于行为分析、故障分析、安全分析、统计分析,主要覆盖以下使用场景:
- 应用调试:提供流水日志功能,帮助开发者记录和获取日志,进行问题分析;
- 问题定位:提供各类场景的故障现场,包含可靠性、性能、功耗、分布式故障相关的日志、事件、跟踪;
- 线上监控:提供应用构建线上观测所需的日志、事件、跟踪接口,方便开发者记录、分析应用线上运行情况。
其能力范围对应三个 API 模块:
| 能力 | 模块 | 用途 |
|---|---|---|
| HiLog 流水日志 | ohos.hilog |
按级别、标识和格式字符串输出日志,辅助调试 |
| HiTraceMeter 与 HiTraceChain 跟踪 | ohos.hi_trace_meter |
Trace 度量与跨线程跨进程分布式跟踪 |
| HiAppEvent 应用事件 | ohos.hiviewdfx.hi_app_event |
记录故障、行为、安全、统计事件,订阅系统事件,设置数据处理者完成数据上传 |
从 Kit 特性来看,开发者可以基于 HiAppEvent、HiLog 接口自建端侧 APM SDK,与厂商自研 APM 对接;也可以利用自定义事件与系统事件订阅能力,快捷记录和收集运营、运维所需事件。所有这些接口在仓颉侧统一通过 import kit.PerformanceAnalysisKit.* 导入。
二、HiAppEvent 应用事件打点
ohos.hiviewdfx.hi_app_event(应用事件打点) 模块提供应用打点和事件订阅能力,包括事件存储、事件订阅、事件清理、打点配置等功能。HiAppEvent 将应用运行过程中触发的事件信息统一归纳到 AppEventInfo 中,并将事件分为两类:
- 系统事件:来源于系统服务,是系统预先定义的事件,其参数对象
params包含的字段由各系统事件定义; - 应用事件:来源于应用,由开发者自行定义,可通过
write打点接口配置写入。
根据 HiAppEvent 介绍,打点 即记录由用户操作引起的变化,提供业务数据信息供开发、产品、运维分析。
2.1 事件设计规范
在设计应用事件时,需遵循以下要素:
- 事件领域(domain):标识事件的领域,建议设置为业务模块名称,以便区分不同的业务模块;
- 事件名称(name):指定事件的名称,建议设置为具体的业务名称,描述实际业务意义;
- 事件类型(eventType):支持四种类型——行为事件(记录按钮点击、界面跳转等用户行为)、故障事件(定位界面卡顿、掉网掉话等异常)、统计事件(统计使用时长、访问数等关键行为)、安全事件(记录密码修改、用户授权等安全行为);
- 事件参数(params):每个事件可包含一组参数,建议设置为事件属性或事件发生上下文信息。
2.2 核心数据类型
事件打点相关的核心数据结构均在 cj-apis-hiappevent.md 中定义:
AppEventInfo:事件信息载体,字段包括:
domain:事件领域,名称支持数字、字母、下划线字符,需以字母开头且不能以下划线结尾,长度非空且不超过 32 个字符;name:事件名称,首字符必须为字母或$,中间字符为数字、字母或下划线,结尾为数字或字母,长度非空且不超过 48 个字符;eventType:事件类型(EventType枚举);params:事件参数对象,类型为HashMap<String, EventValueType>。
EventType 枚举:Fault(故障)、Statistic(统计)、Security(安全)、Behavior(行为)。
EventValueType 枚举:事件参数值的统一封装类型,<: ToString,成员包括 IntValue(Int32)、Int64Value(Int64)、FloatValue(Float64)、StringValue(String)、BoolValue(Bool) 以及 ArrString(Array<String>)、ArrInt32(Array<Int32>)、ArrInt64(Array<Int64>)、ArrFloat64(Array<Float64>)、ArrBool(Array<Bool>) 等数组类型,并提供 toString() 方法返回数据的字符串表示。
事件参数的规格限制(写入时会校验,超出部分按规则丢弃):
- 参数名为
StringValue类型,首字符为字母或$,长度非空且不超过 32 个字符; - 参数值支持 String、Int、Float、Bool 及数组类型。字符串参数长度需在 8*1024 字符以内,超出后与参数名一同丢弃;Int、Float 取值需在
-(2^53 - 1) ~ 2^53 - 1范围内,超出可能产生不确定值;数组参数元素类型必须统一为 String/Int/Float/Bool 中的一种,且元素个数在 100 以内,第 101 个元素起被丢弃; - 参数个数需在 32 个以内,超出的参数做丢弃处理。
Domain 与 Event 常量类:Domain.OS 为系统领域常量;Event 类提供事件名称常量,其中 APP_CRASH(应用崩溃)、APP_FREEZE(应用冻屏)为系统事件名称常量,USER_LOGIN、USER_LOGOUT、DISTRIBUTED_SERVICE_START 为预留的应用事件名称常量。调用 write 写入应用事件时,建议避免与这些系统事件名称常量产生冲突混淆。
2.3 打点写入:write
HiAppEvent.write(info: AppEventInfo): Unit 是应用事件打点方法,将 AppEventInfo 类型的事件进行存储。通过此接口写入的事件对象是开发者自定义的对象,写入后可通过事件观察者(addWatcher)订阅获取。
一个完整的打点示例(对应 API 文档中的编译运行示例):
// index.cj
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
import std.collection.HashMap
try {
let params = HashMap<String, EventValueType>()
params.add("cangjie", IntValue(1001))
params.add("cangjie2", StringValue("1001"))
var appInfo: AppEventInfo = AppEventInfo("cangjie1", "test_event", EventType.Fault, params)
HiAppEvent.write(appInfo)
HiAppEvent.clearData()
} catch (e: BusinessException) {
Hilog.info(0, "test", "${e.message}")
}
write 可能抛出的 BusinessException 错误码如下(完整说明见 应用事件打点错误码):
| 错误码 | 错误信息 | 含义 |
|---|---|---|
| 11100001 | Function is disabled. | 打点功能被关闭(ConfigOption.disable 为 true) |
| 11101001 | Invalid event domain. | 非法的事件领域名称 |
| 11101002 | Invalid event name. | 非法的事件名称 |
| 11101003 | Invalid number of event parameters. | 事件参数数量超过 32 个 |
| 11101004 | Invalid string length of the event parameter. | 参数字符串长度超过 8*1024 字符 |
| 11101005 | Invalid event parameter name. | 非法的事件参数名称 |
| 11101006 | Invalid array length of a event parameter. | 参数数组长度超过 100 |
2.4 打点配置:configure 与 ConfigOption
HiAppEvent.configure(config: ConfigOption): Unit 是应用事件打点配置方法,支持配置打点开关和目录存储配额大小。ConfigOption 结构如下:
public class ConfigOption {
public var disable: Bool
public var maxStorage: String
public init(disable!: Bool = false, maxStorage!: String = "10M")
}
disable:打点功能开关,默认false。true表示关闭打点功能,false表示开启;maxStorage:打点数据存放目录的配额大小,默认"10M"。建议配额不超过 10M,配额过大会影响接口效率。在目录大小超出配额后,下次打点会触发清理操作:按从旧到新的顺序逐个删除打点数据文件,直到目录大小不超出配额为止。配额值字符串只由数字字符和大小单位字符构成,单位支持b、k、kb、m、mb、g、gb、t、tb(不区分大小写);必须以数字开头,可省略单位(默认 byte)。
配置示例:
var config : ConfigOption = ConfigOption(maxStorage: "100M", disable: true)
HiAppEvent.configure(config)
若配额值字符串格式非法,将抛出错误码 11103001(Invalid max storage quota value)。
2.5 数据清理:clearData
HiAppEvent.clearData(): Unit 将当前应用存储在本地的打点数据进行清除,适用于测试或清理场景。
三、事件订阅:Watcher、AppEventFilter 与 AppEventPackageHolder
HiAppEvent 提供事件订阅接口,用于本地获取应用事件(打点写入的数据)。
3.1 订阅接口概览
根据 订阅应用事件(仓颉) 指南:
| 接口名 | 描述 |
|---|---|
write(info: AppEventInfo): Unit |
应用事件打点方法 |
addWatcher(watcher: Watcher): Option<AppEventPackageHolder> |
添加应用事件观察者,订阅应用事件 |
removeWatcher(watcher: Watcher): Unit |
移除应用事件观察者,取消订阅 |
3.2 Watcher 观察者
Watcher 类用于配置和管理事件的观察者,实现对特定事件的监听和处理:
public class Watcher {
public var name: String
public var triggerCondition: TriggerCondition
public var appEventFilters: Array<AppEventFilter>
public var onTrigger: Option <(Int32, Int32, AppEventPackageHolder) -> Unit>
public var onReceive: Option <(String, Array<AppEventGroup>) -> Unit>
public init(name: String, triggerCondition!: TriggerCondition = TriggerCondition(),
appEventFilters!: Array<AppEventFilter> = [],
onTrigger!: Option<(Int32, Int32, AppEventPackageHolder) -> Unit> = None,
onReceive!: Option<(String, Array<AppEventGroup>) -> Unit> = None)
}
关键字段说明:
name:观察者名称,用于唯一标识观察者。首字符必须为字母,中间为数字、字母或下划线,结尾为数字或字母,长度非空且不超过 32 个字符(如testName1、crash_Watcher);triggerCondition:订阅回调触发条件,需与回调函数onTrigger一同传入才会生效,默认不触发;appEventFilters:订阅过滤条件,需要对订阅事件进行过滤时传入,默认不过滤;onTrigger:订阅回调函数,入参curRow(本次回调触发时的订阅事件总数量)、curSize(事件总大小,byte)、holder(订阅数据持有者对象,可通过其处理订阅事件);onReceive:订阅实时回调函数,入参domain(回调事件领域名称)、appEventGroups(回调事件集合)。与onTrigger同时存在时,只触发onReceive。
AppEventFilter 用于设置订阅过滤条件,构造参数 domain(订阅的事件领域,可以是系统领域 hiAppEvent.domain.OS 或自定义 AppEventInfo 中的领域)、命名参数 eventTypes(事件类型集合,默认不过滤)、names(事件名称集合,默认不过滤)。
TriggerCondition 用于设置 onTrigger 回调触发条件:row(满足触发回调的事件总数量)、size(事件总大小,byte)、timeOut(超时时长,单位为 30s),默认值均为 0 即不触发,传入负值会被置为默认值。
3.3 AppEventPackageHolder 订阅数据持有者
AppEventPackageHolder 是订阅数据持有者类,用于对订阅事件进行处理。构造时传入 watcherName,需先通过 addWatcher 添加观察者,再通过观察者名称关联到已添加的观察者对象;若未添加则默认无数据。其方法包括:
setSize(size: Int32): Unit:设置每次取出的事件包数据大小阈值,单位 byte,取值范围[0, 2^31-1],超出范围抛错误码11104001(Invalid size value);takeNext(): Option<AppEventPackage>:获取订阅事件。系统根据setSize设置的大小阈值或setRow设置的条数取出订阅事件数据,默认取 1 条;当订阅事件数据全部取出时返回None;当setRow和setSize同时调用时仅setRow生效。
AppEventPackage 事件包字段:packageId(事件包 ID,从 0 开始自动递增)、row(事件数量)、size(事件大小,byte)、data(事件信息数组)。AppEventGroup 事件组字段:name(事件名称)、appEventInfos(事件对象集合)。
3.4 三种订阅处理方式示例
API 文档给出了三种典型的订阅处理方式(完整可编译示例见 cj-apis-hiappevent.md 中 addWatcher 一节):
方式一:在 onTrigger 自动回调中处理
var condition = TriggerCondition(row: 1)
var appEventFilter = [AppEventFilter("button")]
var watcher = Watcher(
"watcher1",
triggerCondition: condition,
onTrigger: Some(
{
row, size, holder =>
Hilog.info(0, "AppLogCj", "HiAppEvent onTrigger: curRow=${row}, curSize=${size}", "")
while (let Some(v) <- holder.takeNext()) {
let eventPkg = v
Hilog.info(0, "AppLogCj", "HiAppEvent packageId=${eventPkg.packageId}", "")
Hilog.info(0, "AppLogCj", "HiAppEvent row=${eventPkg.row}", "")
Hilog.info(0, "AppLogCj", "HiAppEvent size=${eventPkg.size}", "")
for (i in 0..eventPkg.data.size) {
Hilog.info(0, "AppLogCj", "HiAppEvent info=${eventPkg.data[i]}", "")
}
}
}
)
)
HiAppEvent.addWatcher(watcher)
方式二:通过 addWatcher 返回的 holder 手动处理
let watcher = Watcher("watcher2")
let holder = HiAppEvent.addWatcher(watcher)
if (let Some(v1) <- holder) {
while (let Some(v2) <- v1.takeNext()) {
let eventPkg = v2
// 处理 eventPkg.packageId / row / size / data
}
}
方式三:在实时回调 onReceive 中处理
var condition = TriggerCondition(row: 1, size: 100)
let watcher = Watcher(
"watcher",
triggerCondition: condition,
onTrigger: {
row, size, holder => Hilog.info(0, "AppLogCj", "HiAppEvent onTrigger: curRow=${row}, curSize=${size}", "")
},
onReceive: {
domain, AppEventGroups =>
// 遍历 AppEventGroups[i].name 与 .appEventInfos[j].params 等字段
}
)
HiAppEvent.addWatcher(watcher)
addWatcher 的异常错误码(详见 cj-errorcode-hiappevent.md)包括:11102001(非法的观察者名称)、11102002(非法的过滤事件领域)、11102003(条数值为负)、11102004(大小值为负)、11102005(超时值为负)。
3.5 订阅打点的完整开发步骤
依据 订阅应用事件(仓颉) 指南的完整流程:
- 新建 Cangjie 应用工程,在
entry > src > main > cangjie > main_ability.cj中导入依赖模块:
import kit.PerformanceAnalysisKit.*
import kit.PerformanceAnalysisKit.{Watcher as hiWatcher}
import ohos.base.*
- 在
onCreate函数中添加对用户点击按钮事件的订阅:
var condition = TriggerCondition(row: 1, size: 120, timeOut: 0)
var appEventFilter = [AppEventFilter("cangjie_watcher")]
var watcher = hiWatcher(
"watcher1",
triggerCondition: condition,
appEventFilters: appEventFilter,
onTrigger: Some(
{
row, size, holder =>
Hilog.info(0, "test_hiAppEvent_addWatcher_01",
"HiAppEvent onTrigger: curRow=${row},curSize=${size}")
while (let Some(v) <- holder.takeNext()) {
let eventPkg = v
Hilog.info(0, "test_hiAppEvent_addWatcher_01", "HiAppEvent packageId=${eventPkg.packageId}")
Hilog.info(0, "test_hiAppEvent_addWatcher_01", "HiAppEvent row=${eventPkg.row}")
Hilog.info(0, "test_hiAppEvent_addWatcher_01", "HiAppEvent size=${eventPkg.size}")
for (i in 0..eventPkg.data.size) {
Hilog.info(0, "test_hiAppEvent_addWatcher_01", "HiAppEvent info=${eventPkg.data[i]}")
}
}
}
)
)
- 在
entry > src > main > cangjie > index.cj中添加按钮,并在其onClick函数中进行事件打点:
Button("writeTest").onClick({ evt =>
let eventParams = HashMap<String, EventValueType>([("click_time", IntValue(100))])
let eventInfo: AppEventInfo = AppEventInfo(
"button", // 事件领域
"click", // 事件名称
EventType.Behavior, // 事件类型
eventParams) // 事件参数
HiAppEvent.write(eventInfo)
})
- 运行应用并点击按钮后,可在 Log 窗口看到打点成功日志及订阅回调处理日志:
HiAppEvent success to write event
HiAppEvent eventPkg.packageId=0
HiAppEvent eventPkg.row=1
HiAppEvent eventPkg.size=124
HiAppEvent eventPkg.info={"domain_":"button","name_":"click","type_":4,"time_":1670268234523,"tz_":"+0800","pid_":3295,"tid_":3309,"click_time":100}
从日志可见,订阅到的事件包数据实际是一条 JSON 结构的事件记录,包含领域、名称、类型、时间戳、时区、进程/线程 ID 以及开发者自定义的参数。
四、事件上报:Processor 数据处理者与用户维度数据
HiAppEvent 不仅支持本地订阅,还提供用于处理并上报事件的接口(详见 事件上报)。
4.1 接口概览
数据处理者接口:
| 接口名 | 描述 |
|---|---|
addProcessor(processor: Processor): Int64 |
添加数据处理者,通过预置处理者进行事件上报;返回处理者 ID(添加失败返回 -1,成功返回大于 0 的值),可用于移除 |
removeProcessor(id: Int64): Unit |
移除数据处理者,取消预置处理者 |
用户 ID 接口:
| 接口名 | 描述 |
|---|---|
setUserId(name: String, value: String): Unit |
设置用户 ID,数据处理者上报事件时可携带用户 ID |
getUserId(name: String): String |
获取已设置的用户 ID |
用户属性接口:
| 接口名 | 描述 |
|---|---|
setUserProperty(name: String, value: String): Unit |
设置用户属性,数据处理者上报事件时可携带用户属性 |
getUserProperty(name: String): String |
获取已设置的用户属性 |
4.2 Processor 数据处理者详解
Processor 是可以上报事件的数据处理者对象,用于事件的上报和管理,开发者可自定义数据处理配置以满足不同的数据处理需求:
public class Processor {
public var name: String
public var debugMode: Bool
public var routeInfo: String
public var appId: String
public var onStartReport: Bool
public var onBackgroundReport: Bool
public var periodReport: Int32
public var batchReport: Int32
public var userIds: Array<String>
public var userProperties: Array<String>
public var eventConfigs: Array<AppEventReportConfig>
public init(name: String, debugMode!: Bool = false, routeInfo!: String = "", appId!: String = "",
onStartReport!: Bool = false, onBackgroundReport!: Bool = false, periodReport!: Int32 = 0,
batchReport!: Int32 = 0, userIds!: Array<String> = [], userProperties!: Array<String> = [],
eventConfigs!: Array<AppEventReportConfig> = [])
}
字段与参数约束:
name(必填):数据处理者名称,只能包含大小写字母、数字、下划线和$,不能以数字开头,长度非空且不超过 256 个字符;debugMode:是否开启 debug 模式,默认false;routeInfo:服务器位置信息,默认空字符串,长度不能超过 8KB,超过会被置为默认值;appId:应用 id,默认空字符串,长度不能超过 8KB;onStartReport:处理者启动时是否上报事件,默认false;onBackgroundReport:应用进入后台时是否上报事件,默认false;periodReport:事件定时上报时间周期(秒),必须大于等于 0,小于 0 会被置为默认值 0 而不进行定时上报;batchReport:事件上报阈值,事件条数达到阈值时上报;数值必须大于 0 且小于 1000,不在范围内会被置为默认值 0;userIds/userProperties:可上报的用户 ID / 用户属性的 name 数组,分别对应setUserId/setUserProperty接口的 name 参数;eventConfigs:AppEventReportConfig数组,用于描述可上报事件的领域、名称与是否实时上报。
AppEventReportConfig 字段:domain(事件领域,默认空字符串)、name(事件名称,默认空字符串)、isRealTime(是否实时上报,默认 false)。命名规则与事件领域、名称的通用规则一致。
4.3 事件上报完整开发步骤
以实现对用户点击按钮行为的事件打点并由处理者上报为例(完整工程代码见 cj-hiappevent-event-reporting.md):
- 在
index.cj中添加按钮,在其onClick函数中添加数据处理者(analytics_demo为预置在设备里的数据处理者 lib 库):
let eventConfig = AppEventReportConfig(
domain: "button", // 事件领域
name: "click", // 事件名称
isRealTime: true // 是否实时上报
)
let processor = Processor(
'analytics_demo',
debugMode: true,
routeInfo: 'CN',
appId: '111',
onStartReport: true,
onBackgroundReport: true,
periodReport: 10,
batchReport: 5,
userIds: ['testUserIdName'],
userProperties: ['testUserPropertyName'],
eventConfigs: [eventConfig]
)
this.processorId = HiAppEvent.addProcessor(processor)
- 在按钮点击函数中设置并查看用户 ID:
HiAppEvent.setUserId('testUserIdName', '123456')
let userId = HiAppEvent.getUserId('testUserIdName')
Hilog.info(0x0000, 'testTag', 'userId: ${userId}')
- 在按钮点击函数中设置并查看用户属性:
HiAppEvent.setUserProperty('testUserPropertyName', '123456')
let userProperty = HiAppEvent.getUserProperty('testUserPropertyName')
Hilog.info(0x0000, 'testTag', 'userProperty: ${userProperty}')
- 添加按钮进行事件打点(记录按钮点击事件):
Button("writeTest").onClick ({
evt =>
let eventParams = HashMap<String, EventValueType>([("click_time", IntValue(100))])
let eventInfo: AppEventInfo = AppEventInfo(
"button", "click", EventType.Behavior, eventParams)
HiAppEvent.write(eventInfo)
})
- 添加按钮,在其
onClick函数中移除数据处理者:
HiAppEvent.removeProcessor(this.processorId)
- 运行应用,依次点击按钮后,事件处理者成功接收到事件数据,并在 Log 窗口看到打点成功日志:
HiAppEvent success to write event
4.4 用户 ID 与用户属性的取值约束
setUserId(name, value):name 只能包含大小写字母、数字、下划线和$,不能以数字开头,长度非空且不超过 256 个字符;value 长度不超过 256,当值为 null 或空字符串时清除用户 ID。getUserId未查到返回空字符串;setUserProperty(name, value):name 规则同上;value 长度不超过 1024,值为 null 或空字符串时清除用户属性。getUserProperty未查到返回空字符串。
五、HiLog 流水日志打印
ohos.hilog(HiLog 日志打印) 模块使应用/服务可以按照指定级别、标识和格式字符串输出日志内容,帮助开发者了解应用/服务的运行状态,更好地调试程序。
5.1 日志级别与接口
Hilog 类提供 DEBUG、INFO、WARNING、ERROR、FATAL 五个级别的日志打印方法,全部为静态方法,统一签名:
public static func debug(domain: UInt32, tag: String, format: String, args: Array<String>): Unit
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
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
public static func isLoggable(domain: UInt32, tag: String, level: LogLevel): Bool
各级别含义(LogLevel 枚举,系统能力 SystemCapability.HiviewDFX.HiLog):
- Debug:详细的流程记录,通过该级别日志可更详细地分析业务流程和定位分析问题。DEBUG 级别日志在正式发布版本中默认不被打印,只有在调试版本或打开调试开关的情况下才会打印;
- Info:记录业务关键流程节点,可还原业务的主要运行过程;也用于记录可预料的非正常情况(如无网络信号、登录失败)。建议由业务内处于支配地位的模块记录,避免在多个被调用的模块或低级函数中重复记录;
- Warning:记录较为严重的非预期情况,但对用户影响不大,应用可自动恢复或通过简单操作恢复;
- Error:应用发生了错误,影响功能正常运行或用户正常使用,可以恢复但恢复代价较高(如重置数据);
- Fatal:重大致命异常,表明应用即将崩溃,故障无法恢复。
5.2 参数说明与隐私过滤
- domain:日志对应的领域标识,范围
0x0 ~ 0xFFFF,超出范围日志无法打印,建议开发者在应用内根据需要自定义划分; - tag:指定日志标识,可以为任意字符串,建议用于标识调用所在的类或业务行为。tag 最多为 31 字节,超出后截断,不建议使用中文字符(可能出现乱码或对齐问题);
- format:格式字符串,用于日志的格式化输出。格式字符串中可以设置多个参数,参数需包含参数类型、隐私标识。隐私标识分为
{public}和{private},缺省为{private}。标识{public}的内容明文输出,标识{private}的内容以<private>过滤回显; - args:与 format 对应的可变长度参数列表,参数数目、参数类型必须与格式字符串中的标识一一对应。
isLoggable 用于在打印日志前检查指定领域标识、日志标识和级别的日志是否可以打印,返回 true 表示可以打印。根据 使用 HiLog 打印日志(仓颉) 的说明,isLoggable() 与具体日志打印接口使用的 domain 和 tag 应保持一致,使用的 level 也应与具体日志打印接口级别保持一致。
5.3 日志打印示例
API 参考中的基础示例:
// index.cj
import ohos.base.*
import kit.PerformanceAnalysisKit.*
import ohos.business_exception.BusinessException
try {
Hilog.debug(0, "testTag", "Debug: Hello world!")
Hilog.info(0, "testTag", "Info: Hello world!")
Hilog.warn(0, "testTag", "Warn: Hello world!")
Hilog.error(0, "testTag", "Error: Hello world!")
Hilog.fatal(0, "testTag", "Fatal: Hello world!")
let result = Hilog.isLoggable(0, "testTag", LogLevel.Debug)
} catch (e: BusinessException) {
Hilog.info(0, "test", "${e.message}")
}
UI 工程中的实际开发示例(来自 cj-hilog-guidelines.md):新建 [Cangjie] Empty Ability 工程,在 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")
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
约束与限制:日志最多打印 4096 字节,超出限制文本将被截断。
六、HiTraceMeter 性能打点
ohos.hi_trace_meter(性能打点) 模块提供跟踪进程轨迹、度量程序执行性能的打点能力,打点数据供 hiTraceMeter 工具分析使用。
6.1 使用约束
- 性能打点接口
startTrace、finishTrace、traceByValue无法指定跟踪输出级别,默认均为 COMMERCIAL 级别性能打点; - 用户态 trace 格式使用竖线
|作为分隔符,通过性能打点接口传递的字符串类型参数应避免包含该字符,防止 trace 解析异常; - 用户态 trace 总长度限制 512 字符,超过的部分将被截断。
6.2 startTrace 与 finishTrace
public static func startTrace(name: String, taskId: Int32): Unit
public static func finishTrace(name: String, taskId: Int32): Unit
startTrace:标记一个异步跟踪耗时任务的开始。如果有多个相同 name 的任务需要跟踪或对同一任务跟踪多次且任务同时被执行,则每次调用startTrace传入的taskId需不同;如果相同 name 的任务串行执行,则taskId可以相同;finishTrace:标记一个预跟踪耗时任务的结束,其name和taskId必须与流程开始的startTrace()对应参数值一致。
并行与串行同名任务的典型用法(来自 API 文档示例):
func f2(){
// 跟踪并行执行的同名任务:taskId 需不同
HiTraceMeter.startTrace("myTestFunc", 1)
// 业务流程代码
HiTraceMeter.startTrace("myTestFunc", 2) // 第二个跟踪任务开始,与第一个同名任务并行,taskId 需不同
// 业务流程代码
HiTraceMeter.finishTrace("myTestFunc", 1)
// 业务流程代码
HiTraceMeter.finishTrace("myTestFunc", 2)
}
func f3(){
// 跟踪串行执行的同名任务:taskId 可以相同
HiTraceMeter.startTrace("myTestFunc", 1)
// 业务流程代码
HiTraceMeter.finishTrace("myTestFunc", 1) // 第一个任务结束
// 业务流程代码
HiTraceMeter.startTrace("myTestFunc", 1) // 第二个同名任务开始,串行执行
// 业务流程代码
HiTraceMeter.finishTrace("myTestFunc", 1)
}
6.3 查看 HiTraceMeter 日志
根据 查看 HiTraceMeter 日志,有两种查看方式:
通过 DevEco Studio 可视化界面查看:使用 DevEco Studio Profiler 的 CPU Insight 功能,可视化展示 HiTraceMeter 日志内容,分析应用/服务的 CPU 使用率和线程运行状态,查看指定时间段内程序在 CPU 上的执行耗时情况。
通过命令行工具查看(基于 hdc 连接设备):
- 完成环境准备后使用
hdc shell连接设备; - 在设备上执行 hitrace 命令开启 HiTraceMeter 日志抓取服务:
hdc shell
# hitrace --trace_begin app
- 在设备上运行包含 HiTraceMeter 打点的相关程序;
- 转储 HiTraceMeter 文本日志(默认打印在窗口中,也可指定文件名保存至
/data/local/tmp/,其他路径无权限):
# hitrace --trace_dump
# hitrace --trace_dump -o /data/local/tmp/trace.ftrace
- 结束抓取服务:
# hitrace --trace_finish
- 将设备中的日志导出到主机:
# exit
hdc file recv /data/local/tmp/trace.ftrace ./
- 在文本日志中搜索打点名称等关键字,查看打点是否成功;如需可视化分析,可将日志导入 DevEco Studio Profiler 或使用 HiSmartPerf 工具进行分析。
七、错误码速查
本文涉及的错误码文档位于 PerformanceAnalysisKit 目录,其中通用错误码参考 通用错误码说明文档。整理如下:
7.1 应用事件打点错误码(cj-errorcode-hiappevent.md)
| 错误码 | 错误信息 | 触发场景与处理建议 |
|---|---|---|
| 11100001 | Function is disabled. | 打点功能被关闭,调用 configure 开启打点功能 |
| 11101001 | Invalid event domain. | 事件领域名称非法(只含数字、小写字母、下划线,小写字母开头,不以下划线结尾,非空且不超过 16 字符) |
| 11101002 | Invalid event name. | 事件名称非法(首字符为字母或 $,不超过 48 字符) |
| 11101003 | Invalid number of event parameters. | 事件参数数量超过 32 个,额外参数被丢弃 |
| 11101004 | Invalid string length of the event parameter. | 参数字符串超过 8*1024 字符,相关参数被忽略 |
| 11101005 | Invalid event parameter name. | 事件参数名称非法(不超过 16 字符) |
| 11101006 | Invalid array length of the event parameter. | 参数数组长度超过 100,额外元素被丢弃 |
| 11101007 | The number of parameter keys exceeds the limit. | setEventParam 设置的事件自定义参数超过 64 个 |
| 11102001 | Invalid watcher name. | 观察者名称非法(小写字母开头、不超过 32 字符) |
| 11102002 | Invalid filtering event domain. | 过滤事件领域名称非法(不超过 32 字符) |
| 11102003 | Invalid row value. | 触发条件条数值为负数 |
| 11102004 | Invalid size value. | 触发条件大小值为负数 |
| 11102005 | Invalid timeout value. | 触发条件超时值为负数 |
| 11103001 | Invalid max storage quota value. | 最大存储配额值字符串格式非法 |
| 11104001 | Invalid size value. | setSize 传入的事件包大小值为负数 |
7.2 Hidebug CpuUsage 错误码(cj-errorcode-hidebug-cpuusage.md)
| 错误码 | 错误信息 | 触发场景与处理建议 |
|---|---|---|
| 11400104 | The status of the system CPU usage is abnormal. | 当前 cpuUsage 状态异常,可能因 hiview 服务进程未正常启动;可检查 hiview 进程运行状态,重启 hiview 服务或重启系统 |
八、结语
Performance Analysis Kit 在仓颉侧通过 kit.PerformanceAnalysisKit.* 统一暴露了 HiAppEvent、HiLog、HiTraceMeter 三组能力:HiAppEvent 负责事件打点、本地订阅与数据处理者上报,构成行为/故障/安全/统计分析的完整闭环;HiLog 提供带隐私过滤与级别控制的结构化日志输出,支撑调试与线上问题回溯;HiTraceMeter 提供轻量的耗时任务打点,配合 hitrace 工具与 DevEco Studio Profiler 完成性能分析。开发者可参考本仓库中 API 参考文档 与 dfx 开发指南 中的完整示例,将这些能力组合进自己的仓颉应用,构建面向调试、定位与线上监控的可观测体系。