From 511e21c2f2451b780d4a3f138285f7c987494a46 Mon Sep 17 00:00:00 2001 From: hhl Date: Tue, 1 Jul 2025 14:32:26 +0800 Subject: [PATCH] fix Signed-off-by: hhl --- ...iappevent-watcher-mainthreadjank-events.md | 157 ++++++++++-------- .../js-apis-hiviewdfx-hiappevent.md | 36 +--- 2 files changed, 91 insertions(+), 102 deletions(-) diff --git a/zh-cn/application-dev/dfx/hiappevent-watcher-mainthreadjank-events.md b/zh-cn/application-dev/dfx/hiappevent-watcher-mainthreadjank-events.md index c2b98a39153..99db4837a83 100644 --- a/zh-cn/application-dev/dfx/hiappevent-watcher-mainthreadjank-events.md +++ b/zh-cn/application-dev/dfx/hiappevent-watcher-mainthreadjank-events.md @@ -55,74 +55,6 @@ ![抓trace示例](figures/dump-trace2.PNG) -## 自定义采样栈参数介绍 - -系统提供了基础的主线程超时检测功能，一些应用主线程对检测事件的检测间隔、采集次数等有更高的要求，因此开放可配置参数的接口提供给开发者使用。 - -API接口的具体使用说明（参数使用限制、具体取值范围等）请参考[应用事件打点setEventConfig接口说明](../reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md#hiappeventseteventconfig15)。 - -### 接口说明 - -| 接口名 | 描述 | -| -------------------------------------------------------------------------------------| -------------------------------------------- | -| setEventConfig(name: string, config: Record): Promise\ | 设置主线程采样栈参数接口。 **现阶段仅提供MAIN_THREAD_JANK事件参数自定义，因此name为MAIN_THREAD_JANK。** | - -### 参数设置说明 - -开发者可以使用上述hiappevent提供的接口，在Record中自定义配置采集MAIN_THREAD_JANK事件的参数。 - -开发者通过设置log_type（采集MAIN_THREAD_JANK事件日志类型）的值，定制不同的MAIN_THREAD_JANK事件的规格，具体规格如下： - -1. log_type设置0：默认值，采集调用栈150ms~450ms，采集trace阈值450ms。如果之前使用log_type=1设置过抓采样栈参数，自定义参数无效。参数配置示例如下： - - ```text - let params: Record = { - "log_type": "0" - }; - ``` - -2. log_type设置1：采集调用栈，触发检测的阈值用户自定义。**log_type=1，必须配置采样栈相关的5个参数**，具体参数如下： - - （1）sample_interval：主线程超时采样检测间隔。系统根据开发者设置的interval进行超时检测判断，并使用该interval作为周期性任务检测的间隔。范围：[50, 500]，单位：ms。默认值：150ms。 - - （2）ignore_startup_time：线程启动一定时间内，不进行超时检测。一些进程启动时间较长，此时抓全的超时采样栈，分析意义不大。因此，在开发者定义启动时间间隔内，不进行超时检测。最小值：3s。默认值：10s。 - - （3）sample_count：主线程超时采样次数。系统检测到当前主线程执行任务超过采样限制后，开始周期性采集堆栈，每个间隔采集一次堆栈，共采集sample_count次。取值范围：最小值：1次，最大值需要结合自定义的sample_interval进行动态计算，计算公式：**sample_count <= (2500 / sample_interval - 4)**。开发者要结合需求场景，进行合理的设置。 - - > **说明：** - > - > 2500的含义：根据系统规定，主线程超时事件从检测到上报的时间不可以超过2.5s（即：2500ms）。因此sample_count的设置值不能超过系统按计算公式得出的最大值。 - > - > 4的含义：第一次超时间隔检测时间 + 第二次超时间隔（系统提供两次再次发生超时事件的检测机会）时间 + 收集并上报堆栈信息的时间。 - - （4）report_times_per_app：同一个应用的PID一个生命周期内，主线程超时采样上报次数。一个生命周期内只能设置一次。 - - > **说明：** - > - > 开发者选项打开，每小时范围：[1, 3]，单位：次。默认值：1次； - > - > 开发者选项关闭，每天上报次数范围：[1, 3]，单位：次。默认值：1次。 - - 参数配置示例如下: - - ```text - let params: Record = { - "log_type": "1", - "sample_interval": "100", - "ignore_startup_time": "11", - "sample_count": "21", - "report_times_per_app": "3" - }; - ``` - -3. log_type设置2：收集trace，触发检测的阈值450ms。参数配置示例如下: - - ```text - let params: Record = { - "log_type": "2" - }; - ``` - ## 主线程超时事件日志规格 1. 日志老化规格。 @@ -195,6 +127,95 @@ API接口的具体使用说明（参数使用限制、具体取值范围等） trace文件说明参考：[web端加载trace说明](https://gitee.com/openharmony/developtools_smartperf_host/blob/master/ide/src/doc/md/quickstart_systemtrace.md)。 +## 自定义主线程超时事件参数介绍 + +从API version 15开始，系统提供了基础的主线程超时检测功能，一些应用主线程对检测事件的检测间隔、采集次数等有更高的要求，因此开放可配置参数的接口提供给开发者使用。 + +#### 接口说明 + +| 接口名 | 描述 | +| -------------------------------------------------------------------------------------| -------------------------------------------- | +| setEventConfig(name: string, config: Record): Promise\ | 设置主线程采样栈参数接口。 **name为MAIN_THREAD_JANK。**
**说明**：从API version 15开始，支持该接口。 | + +#### 参数设置说明 + +开发者可以使用上述hiappevent提供的接口，在Record中配置崩溃日志打印规格的参数。具体参数说明如下： + +> **注意** +> +> log_type=0或2，无需设置其他参数。 +> +> log_type=1时，必须配置以下参数：sample_interval、ignore_startup_time、sample_count和report_times_per_app。 + +| 参数名 | 类型 | 必填 | 说明 | +| -----| ----- | ----- |----- | +| log_type | string | 是 |采集MAIN_THREAD_JANK事件日志类型。
log_type=0：默认值，主线程连续两次超时150ms~450ms，采集调用栈；主线程超时450ms，采集trace。
log_type=1：仅采集调用栈，触发检测的阈值由用户自定义。
log_type=2：仅采集trace。
| +| sample_interval | string | 否 | 主线程超时检测间隔和采样间隔。
单位为ms，取值范围为[50, 500]。
系统根据开发者设置的interval进行超时检测判断，并使用该interval作为周期性任务检测的间隔。
| +| ignore_startup_time | string | 否 | 忽略启动时间内的主线程超时检测。单位为s，最小值：3，默认值：10。
线程启动一定时间内，不进行超时检测。一些进程启动时间较长，此时抓全的超时采样栈，分析意义不大。因此，在开发者定义启动时间间隔内，不进行超时检测。
| +| sample_count | string | 否 |主线程超时采样次数。系统检测到当前主线程执行任务超过采样限制后，开始周期性采集堆栈，每个间隔采集一次堆栈，共采集sample_count次。
最小值：1次，最大值需要结合自定义的sample_interval进行动态计算，计算公式：**sample_count <= (2500 / sample_interval - 4)**。| +| report_times_per_app | string | 否 | 同一个应用的PID一个生命周期内，主线程超时采样上报次数。一个生命周期内只能设置一次。
默认值：1次，单位：次。
开发者选项打开，每小时范围：[1, 3]。
开发者选项关闭，每天上报次数范围：[1, 3]。
| + +**sample_count说明：** + +（1）2500的含义：根据系统规定，主线程超时事件从检测到上报的时间不可以超过2.5s（即：2500ms）。因此sample_count的设置值不能超过系统按计算公式得出的最大值。 + +（2）4的含义：第一次超时间隔检测时间 + 第二次超时间隔（系统提供两次再次发生超时事件的检测机会）时间 + 收集并上报堆栈信息的时间。 + +（3）开发者要结合需求场景，进行合理的设置。 + +#### 参数设置示例 + +以下示例用于模拟配置MAIN_THREAD_JANK事件的门限触发条件，以log_type的三种类型为例： + +log_type=0，用于采样栈或采样trace。 +```ts +import { BusinessError } from '@kit.BasicServicesKit'; +import { hilog } from '@kit.PerformanceAnalysisKit'; + +let params: Record = { +"log_type": "0" +}; +hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => { +hilog.info(0x0000, 'hiAppEvent', `Setting default value successfully.`); +}).catch((err: BusinessError) => { +hilog.error(0x0000, 'hiAppEvent', `Failed to set default value. Code: ${err.code}, message: ${err.message}`); +}); +``` + +log_type=1，仅用于采集调用栈。 +```ts +import { BusinessError } from '@kit.BasicServicesKit'; +import { hilog } from '@kit.PerformanceAnalysisKit'; + +let params: Record = { + "log_type": "1", + "sample_interval": "100", + "ignore_startup_time": "11", + "sample_count": "21", + "report_times_per_app": "3" +}; +hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => { + hilog.info(0x0000, 'hiAppEvent', `Successfully set sampling stack parameters.`); +}).catch((err: BusinessError) => { +hilog.error(0x0000, 'hiAppEvent', `Failed to set sample stack value. Code: ${err.code}, message: ${err.message}`); +}); +``` + +log_type=2，仅用于采集trace。 +```ts +import { BusinessError } from '@kit.BasicServicesKit'; +import { hilog } from '@kit.PerformanceAnalysisKit'; + +let params: Record = { + "log_type": "2" +}; +hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => { + hilog.info(0x0000, 'hiAppEvent', `Set to only collect trace successfully.`); +}).catch((err: BusinessError) => { + hilog.error(0x0000, 'hiAppEvent', `Failed to set only collect trace. code: ${err.code}, message: ${err.message}`); +}); +``` + ## 事件params属性描述 | 名称 | 类型 | 说明 | diff --git a/zh-cn/application-dev/reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md b/zh-cn/application-dev/reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md index 54da2c64aad..2a95cdab77d 100644 --- a/zh-cn/application-dev/reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md +++ b/zh-cn/application-dev/reference/apis-performance-analysis-kit/js-apis-hiviewdfx-hiappevent.md @@ -253,7 +253,7 @@ hiAppEvent.setEventParam(params, "test_domain", "test_event").then(() => { setEventConfig(name: string, config: Record<string, ParamType>): Promise<void> -事件自定义门限触发条件的参数设置方法，使用Promise方式作为异步回调。在同一生命周期中，可以通过事件名称，自定义事件门限触发条件相关的参数。**目前仅支持MAIN_THREAD_JANK事件。参数配置详见：[主线程超时事件检测](../../dfx/hiappevent-watcher-mainthreadjank-events.md#自定义采样栈参数介绍)**。 +事件相关的配置参数设置方法，使用Promise方式作为异步回调。在同一生命周期中，可以通过事件名称，设置事件相关的配置参数。
不同的事件有不同的配置项，目前仅支持MAIN_THREAD_JANK（参数配置详见[主线程超时事件检测](../../dfx/hiappevent-watcher-mainthreadjank-events.md#自定义主线程超时事件参数介绍)）事件。 **原子化服务API：** 从API version 15开始，该接口支持在原子化服务中使用。 @@ -282,24 +282,8 @@ setEventConfig(name: string, config: Record<string, ParamType>): Promise&l **示例：** -以下示例用于模拟配置MAIN_THREAD_JANK事件的门限触发条件，以log_type的三种类型为例： +以下示例用于模拟配置MAIN_THREAD_JANK事件的采集堆栈自定义参数： -log_type=0，用于采样栈或采样trace。 -```ts -import { BusinessError } from '@kit.BasicServicesKit'; -import { hilog } from '@kit.PerformanceAnalysisKit'; - -let params: Record = { - "log_type": "0" -}; -hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => { - hilog.info(0x0000, 'hiAppEvent', `success to set event config`); -}).catch((err: BusinessError) => { - hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); -}); -``` - -log_type=1，仅用于采集调用栈。 ```ts import { BusinessError } from '@kit.BasicServicesKit'; import { hilog } from '@kit.PerformanceAnalysisKit'; @@ -318,22 +302,6 @@ hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => }); ``` -log_type=2，仅用于采集trace。 -```ts -import { BusinessError } from '@kit.BasicServicesKit'; -import { hilog } from '@kit.PerformanceAnalysisKit'; - -let params: Record = { - "log_type": "2" -}; -hiAppEvent.setEventConfig(hiAppEvent.event.MAIN_THREAD_JANK, params).then(() => { - hilog.info(0x0000, 'hiAppEvent', `success to set event config`); -}).catch((err: BusinessError) => { - hilog.error(0x0000, 'hiAppEvent', `code: ${err.code}, message: ${err.message}`); -}); -``` - - ## Watcher 提供事件观察者的参数选项。用于配置和管理事件的观察者，实现对特定事件的监听和处理。 -- Gitee