# 功耗检测

## 简介

功耗检测主要提供CPU高负载检测，可以通过订阅相关事件实现检测。

如需了解如何使用HiAppEvent提供订阅CPU高负载事件，请参考以下文档。目前仅提供ArkTS接口。

* [订阅CPU高负载事件（ArkTS）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hiappevent-watcher-cpu-usage-high-arkts)

## 实现原理

系统会周期性及在特定条件（如前后台切换）下，采集三方应用在CPU上的运行时间，并每5分钟统计一次前5分钟的平均负载。若负载超过设定门限，将触发HiAppEvent预警事件。

应用触发CPU高负载事件，其中负载是根据CPU核数归一化后的运行时间。例如：在5分钟内，应用进程在10核CPU上运行了5分钟，其平均负载为：5（CPU上运行时间） / 5（统计周期分钟）/ 10（核数） = 10%。

CPU高负载事件存在以下场景：

1. 应用在前台时触发CPU高负载事件：5分钟内平均负载大于30%。

2. 应用在后台时触发CPU高负载事件：5分钟内平均负载大于10%。

3. 应用线程高负载异常事件：单线程1分钟内平均负载大于70%。

此外，CPU后台高负载场景还支持以下3档规格：

1. 应用在后台时触发CPU高负载事件：10分钟内平均负载大于7%。

2. 应用在后台时触发CPU高负载事件：30分钟内平均负载大于2%。

3. 应用在后台时触发CPU高负载事件：60分钟内平均负载大于1%。

## 约束和限制

前台CPU高负载异常：单应用默认一天只抓取1次调用栈，1次采样栈。

后台CPU高负载异常：单应用默认一天只抓取1次调用栈，1次采样栈。

线程CPU高负载异常：单应用默认一天只抓取1次采样栈。

相关配置可自定义，详见[自定义参数](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hiappevent-watcher-cpu-usage-high-event#自定义参数)。

## 日志规格

在订阅事件开发步骤的最后一步中，获取到系统事件数据的处理日志后（详细流程见：[订阅CPU高负载事件（ArkTS）](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hiappevent-watcher-cpu-usage-high-arkts)），可通过查找日志中"external_log"记录的故障日志文件路径，得到故障日志。例如：

```text
HiAppEvent eventInfo={"domain":"OS","name":"CPU_USAGE_HIGH","eventType":1,"params":{"begin_time":1765959898079,"bundle_name":"com.xpower.test","bundle_version":"1.0.0","end_time":1765959958079,"external_log":["/data/storage/el2/log/hiappevent/CPU_USAGE_HIGH_1765959959260_0.log"],"fault_type":3,"foreground":true,"log_over_limit":false,"threads":[{"name":"WorkerThread","tid":29164,"usage":72}],"time":1765959959257,"usage":72}}
```

上述eventInfo中的各字段详细说明见：[事件字段说明](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/hiappevent-watcher-cpu-usage-high-event#事件字段说明)。

其中external_log记录故障日志的路径，在路径下可获取到故障日志。

调用栈故障日志是触发故障时当前故障线程的调用链堆栈信息。调用栈故障日志格式及说明详见：[一般故障场景日志规格](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/cppcrash-guidelines#一般故障场景日志规格)中的"调用栈帧内容说明"。

采样栈故障日志是主动采集的perf日志。采样栈故障日志格式及说明详见：[日志规格](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/apptask-timeout-guidelines#日志规格)中的"采样栈规格"。