仓颉应用 Performance Analysis Kit(性能分析服务)开发指南:HiAppEvent、HiLog 与 HiTraceMeter 全解析

原创2026-10-15 13:36:341,823 阅读
文章标签:文档知识库

仓颉应用 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 订阅打点的完整开发步骤

依据 订阅应用事件(仓颉) 指南的完整流程:

  1. 新建 Cangjie 应用工程,在 entry > src > main > cangjie > main_ability.cj 中导入依赖模块:
import kit.PerformanceAnalysisKit.*
import kit.PerformanceAnalysisKit.{Watcher as hiWatcher}
import ohos.base.*
  1. 在 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]}")
                }
            }
        }
    )
)
  1. 在 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)
})
  1. 运行应用并点击按钮后,可在 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):

  1. 在 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)
  1. 在按钮点击函数中设置并查看用户 ID:
HiAppEvent.setUserId('testUserIdName', '123456')
let userId = HiAppEvent.getUserId('testUserIdName')
Hilog.info(0x0000, 'testTag', 'userId: ${userId}')
  1. 在按钮点击函数中设置并查看用户属性:
HiAppEvent.setUserProperty('testUserPropertyName', '123456')
let userProperty = HiAppEvent.getUserProperty('testUserPropertyName')
Hilog.info(0x0000, 'testTag', 'userProperty: ${userProperty}')
  1. 添加按钮进行事件打点(记录按钮点击事件):
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)
})
  1. 添加按钮,在其 onClick 函数中移除数据处理者:
HiAppEvent.removeProcessor(this.processorId)
  1. 运行应用,依次点击按钮后,事件处理者成功接收到事件数据,并在 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 连接设备):

  1. 完成环境准备后使用 hdc shell 连接设备;
  2. 在设备上执行 hitrace 命令开启 HiTraceMeter 日志抓取服务:
hdc shell
# hitrace --trace_begin app
  1. 在设备上运行包含 HiTraceMeter 打点的相关程序;
  2. 转储 HiTraceMeter 文本日志(默认打印在窗口中,也可指定文件名保存至 /data/local/tmp/,其他路径无权限):
# hitrace --trace_dump
# hitrace --trace_dump -o /data/local/tmp/trace.ftrace
  1. 结束抓取服务:
# hitrace --trace_finish
  1. 将设备中的日志导出到主机:
# exit
hdc file recv /data/local/tmp/trace.ftrace ./
  1. 在文本日志中搜索打点名称等关键字,查看打点是否成功;如需可视化分析,可将日志导入 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 开发指南 中的完整示例,将这些能力组合进自己的仓颉应用,构建面向调试、定位与线上监控的可观测体系。

登录后查看全文
CangjieCorpus