@ohos.arkui.performanceMonitor (Performance Monitoring) (System API)

The performanceMonitor module provides APIs for monitoring performance metrics related to user scenes. By calling the begin and end APIs at the start and end of a scene respectively, you can obtain relevant performance metrics such as response latency, completion latency, and frame drops.

NOTE

The APIs of this module are supported since API version 10. Updates will be marked with a superscript to indicate their earliest API version.

The APIs provided by this module are system APIs.

Modules to Import

import { performanceMonitor } from '@kit.ArkUI';

ActionType

Enumerates the trigger modes for user scenes (typically scenes involving animations).

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Value	Description
LAST_DOWN	0	Pressing against the screen.
LAST_UP	1	Lifting a finger off the screen.
FIRST_MOVE	2	First swiping on the screen.

SourceType¹²⁺

Enumerates the trigger source types of user scenes.

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Name	Value	Description
PERF_TOUCH_EVENT	0	Touchscreen event.
PERF_MOUSE_EVENT	1	Mouse event.
PERF_TOUCHPAD_EVENT	2	Touchpad event.
PERF_JOYSTICK_EVENT	3	Joystick event.
PERF_KEY_EVENT	4	Keyboard event.

performanceMonitor.begin

begin(scene: string, startInputType: ActionType, note?: string): void

Marks the start of a user scene. Call this API when the scene begins.

System API: This is a system API.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
scene	string	Yes	User scene ID. The string length is unlimited, but it is recommended that you keep it within 255 characters. The format is recommended to use uppercase letters connected by underscores, for example, LAUNCHER_APP_LAUNCH_FROM_ICON.
startInputType	ActionType	Yes	Trigger mode of the user scene.
note	string	No	Remarks for the user scene. The string length is unlimited, but it is recommended that you keep it within 255 characters. This field is optional. If provided, the performance metrics report will include the remark information; if not provided, there is no impact.

Example

Start point of the user scene where the user taps an icon to launch an application, triggered by a release event (LAST_UP).

performanceMonitor.begin("LAUNCHER_APP_LAUNCH_FROM_ICON", performanceMonitor.ActionType.LAST_UP, "APP_START_BEGIN");

performanceMonitor.end

end(scene: string): void

Marks the end of a user scene. Call this API when the scene ends.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
scene	string	Yes	User scene ID, which must be strictly consistent with that in begin; otherwise, the monitoring will be invalid.

Example

End point of the user scene where the user taps an icon to launch an application.

performanceMonitor.end("LAUNCHER_APP_LAUNCH_FROM_ICON");

performanceMonitor.recordInputEventTime¹²⁺

recordInputEventTime(type: ActionType, sourceType: SourceType, time: number): void

Records the trigger event type and time before the start of the animation scene.

System capability: SystemCapability.ArkUI.ArkUI.Full

Parameters

Name	Type	Mandatory	Description
type	ActionType	Yes	Trigger mode of the user scene.
sourceType	SourceType	Yes	Trigger source of the user scene.
time	number	Yes	Scenario trigger timestamp (in ms), for example, 1751508570794. Values equal to or less than 0 will be automatically converted to the current system time, while positive values will be used as-is. Incorrect parameters may cause abnormal response latency metrics.

Error codes

For details about the error codes, see Universal Error Codes.

ID	Error Message
202	not system application.

Example

import { systemDateTime, BusinessError } from '@kit.BasicServicesKit';
import { performanceMonitor } from '@kit.ArkUI';

// Obtain the current system time.
let time = systemDateTime.getTime(false);
// Update the user trigger event type and time.
performanceMonitor.recordInputEventTime(performanceMonitor.ActionType.LAST_UP, performanceMonitor.SourceType.PERF_MOUSE_EVENT, time);