• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Using HiChecker (ArkTS)
2
3<!--Kit: Performance Analysis Kit-->
4<!--Subsystem: HiviewDFX-->
5<!--Owner: @lu-tao-->
6<!--Designer: @martin-duan-->
7<!--Tester: @gcw_KuLfPSbe-->
8<!--Adviser: @foryourself-->
9
10## Overview
11
12HiChecker is provided to check issues that may be easily ignored during application development. Such issues include time-consuming thread calling and ability resource leakage in application processes. The issues are recorded in logs or lead to process crashes explicitly so that you can find and rectify them.
13
14## Basic Concepts
15
16**Rule constants**: HiChecker uses constants to indicate existing alarm rules or check rules. A constant indicates a rule. You can add or delete rules using HiChecker APIs.
17
18## Working Principles
19
201. The application calls HiChecker APIs to add, remove, query, and modify rules.
21
222. When a time-consuming call or ability resource leakage occurs, HiChecker reports an event based on the rule triggered.
23
24## Constraints
25
26- Currently, the alarm rules support only logs (default) and application crashes.
27
28- HiChecker supports stack unwinding in C but not in JavaScript.
29
30## Available APIs
31
32The check APIs are provided by the HiChecker module. For details about the APIs, see [@ohos.hichecker (HiChecker)](../reference/apis-performance-analysis-kit/js-apis-hichecker.md).
33
34| API| Description|
35| -------- | -------- |
36| hichecker.addCheckRule(rule: bigint): void | Adds one or more rules. HiChecker detects unexpected operations or gives feedback based on the added rules.|
37| hichecker.removeCheckRule(rule: bigint): void | Removes one or more rules. The removed rules will become ineffective.|
38| hichecker.containsCheckRule(rule: bigint): boolean | Checks whether the specified rule exists in the collection of added rules.|
39| hichecker.getRule(): bigint | Obtains a collection of thread, process, and alarm rules that have been added.|
40
41## How to Develop
42
43After the application startup execution page is loaded, the check starts. After the service is complete, the check stops. When starting a check, you can configure different alarm rules and check rules as required. Currently, the check rules support the check of time-consuming function calls, ability leaks, and ArkUI performance. You can configure the behavior triggered by the detected problem through the alarm rule. Currently, the logging and application exit are supported.
44
45To detect time-consuming function calls and record them in logs, perform the following steps:
46
471. Create an ArkTS application project. In the **Project** window, click **entry > src > main > ets > entryability** to open the **EntryAbility.ets** file. After the page is loaded, call the HiChecker to add check rules. The sample code is as follows:
48
49   ```ts
50   import { window } from '@kit.ArkUI';
51   import { image } from '@kit.ImageKit';
52   import { UIAbility, Want, AbilityConstant } from '@kit.AbilityKit';
53   import { hichecker, hilog } from '@kit.PerformanceAnalysisKit';
54
55   export default class EntryAbility extends UIAbility {
56     onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
57       // Add a check rule. For details about the rule, see HiChecker.
58       hichecker.addCheckRule(hichecker.RULE_CAUTION_PRINT_LOG|hichecker.RULE_THREAD_CHECK_SLOW_PROCESS);
59       let filePath: string = this.context.cacheDir + '/test.JPG';
60       const imageSourceApi: image.ImageSource = image.createImageSource(filePath);
61       const imagePackerApi = image.createImagePacker();
62       let packOpts: image.PackingOption = { format:"image/jpeg", quality:98 };
63       imagePackerApi.packToData(imageSourceApi, packOpts);
64       // The preceding codes trigger the check rule through the image subsystem.
65       hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreateend');
66     }
67
68     onDestroy() {
69       hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onDestroy');
70     }
71
72     onWindowStageCreate(windowStage: window.WindowStage) {
73       // Main window is created, set main page for this ability
74       hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageCreate');
75
76       windowStage.loadContent('pages/Index', (err, data) => {
77         if (err.code) {
78           hilog.error(0x0000, 'testTag', 'Failed to load the content. Cause: %{public}s', JSON.stringify(err) ?? '');
79           return;
80         }
81         hilog.info(0x0000, 'testTag', 'Succeeded in loading the content. Data: %{public}s', JSON.stringify(data) ?? '');
82       });
83     }
84
85     onWindowStageDestroy() {
86       // Main window is destroyed, and UI related resources are released.
87       hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onWindowStageDestroy');
88     }
89
90     onForeground() {
91       // Ability is brought to foreground.
92       hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onForeground');
93     }
94
95     onBackground() {
96       // Ability is back to background.
97       hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onBackground');
98     }
99   }
100   ```
101
1022. Install and run the HAP. Use the Log plug-in of DevEco Studio to filter logs containing the keyword **HICHECKER** or run the **hdc shell "hilog | grep HICHECKER"** command. If the following call stack information is displayed, the check is successful (the call stack is the one that triggers the check rule).
103
104   ```shell
105   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: StackTrace:
106   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #00 pc 00003d33 /system/lib/chipset-pub-sdk/libbacktrace_local.so(OHOS::HiviewDFX::GetBacktrace(std::__h::basic_string<char, std::__h::char_traits<char>, std::__h::allocator<char>>&, bool, unsigned int)+90)(7c7c81050ce2a86bf0a22943c25773db)
107   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #01 pc 00003a57 /system/lib/chipset-pub-sdk/libdfx_dumpcatcher.z.so(OHOS::HiviewDFX::DfxDumpCatcher::DoDumpCurrTid(unsigned int, std::__h::basic_string<char, std::__h::char_traits<char>, std::__h::allocator<char>>&, unsigned int)+26)(8e2b59ecc6cc00dd2135f9d84c23a724)
108   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #02 pc 000042a1 /system/lib/chipset-pub-sdk/libdfx_dumpcatcher.z.so(OHOS::HiviewDFX::DfxDumpCatcher::DoDumpLocalLocked(int, int, std::__h::basic_string<char, std::__h::char_traits<char>, std::__h::allocator<char>>&, unsigned int)+40)(8e2b59ecc6cc00dd2135f9d84c23a724)
109   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #03 pc 0000452d /system/lib/chipset-pub-sdk/libdfx_dumpcatcher.z.so(OHOS::HiviewDFX::DfxDumpCatcher::DumpCatch(int, int, std::__h::basic_string<char, std::__h::char_traits<char>, std::__h::allocator<char>>&, unsigned int, bool)+188)(8e2b59ecc6cc00dd2135f9d84c23a724)
110   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #04 pc 00002cd7 /system/lib/platformsdk/libhichecker.so(OHOS::HiviewDFX::HiChecker::NotifySlowProcess(std::__h::basic_string<char, std::__h::char_traits<char>, std::__h::allocator<char>> const&)+90)(03f34822b1baca8c33fb87a2cd1817cd)
111   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #05 pc 0004045d /system/lib/platformsdk/libimage_napi.z.so(f765998ba1f5185405f9735d86b0c7b7)
112   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #06 pc 00040f43 /system/lib/platformsdk/libimage_napi.z.so(f765998ba1f5185405f9735d86b0c7b7)
113   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #07 pc 0002b0c5 /system/lib/platformsdk/libace_napi.z.so(panda::JSValueRef ArkNativeFunctionCallBack<true>(panda::JsiRuntimeCallInfo*)+448)(a84fbb767fd826946623779c608395bf)
114   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #08 pc 001e7597 /system/lib/platformsdk/libark_jsruntime.so(panda::ecmascript::EcmaInterpreter::RunInternal(panda::ecmascript::JSThread*, unsigned char const*, unsigned long long*)+14710)(106c552f6ce4420b9feac95e8b21b792)
115   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #09 pc 001e043b /system/lib/platformsdk/libark_jsruntime.so(panda::ecmascript::EcmaInterpreter::Execute(panda::ecmascript::EcmaRuntimeCallInfo*)+986)(106c552f6ce4420b9feac95e8b21b792)
116   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #10 pc 0029ec99 /system/lib/platformsdk/libark_jsruntime.so(panda::ecmascript::JSFunction::Call(panda::ecmascript::EcmaRuntimeCallInfo*)+388)(106c552f6ce4420b9feac95e8b21b792)
117   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #11 pc 0034b14b /system/lib/platformsdk/libark_jsruntime.so(panda::FunctionRef::CallForNapi(panda::ecmascript::EcmaVM const*, panda::JSValueRef*, panda::JSValueRef* const*, int)+918)(106c552f6ce4420b9feac95e8b21b792)
118   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #12 pc 0003d343 /system/lib/platformsdk/libace_napi.z.so(napi_call_function+198)(a84fbb767fd826946623779c608395bf)
119   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #13 pc 000283e1 /system/lib/platformsdk/libuiabilitykit_native.z.so(OHOS::AbilityRuntime::JsUIAbility::CallObjectMethod(char const*, napi_value__* const*, unsigned int, bool, bool)+648)(118b2c16051d37927837ed0ce7874f1d)
120   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #14 pc 00027c0d /system/lib/platformsdk/libuiabilitykit_native.z.so(OHOS::AbilityRuntime::JsUIAbility::OnStart(OHOS::AAFwk::Want const&, OHOS::sptr<OHOS::AAFwk::SessionInfo>)+616)(118b2c16051d37927837ed0ce7874f1d)
121   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #15 pc 000548fd /system/lib/platformsdk/libuiabilitykit_native.z.so(OHOS::AbilityRuntime::UIAbilityImpl::Start(OHOS::AAFwk::Want const&, OHOS::sptr<OHOS::AAFwk::SessionInfo>)+396)(118b2c16051d37927837ed0ce7874f1d)
122   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #16 pc 0005549d /system/lib/platformsdk/libuiabilitykit_native.z.so(OHOS::AbilityRuntime::UIAbilityImpl::HandleAbilityTransaction(OHOS::AAFwk::Want const&, OHOS::AAFwk::LifeCycleStateInfo const&, OHOS::sptr<OHOS::AAFwk::SessionInfo>)+764)(118b2c16051d37927837ed0ce7874f1d)
123   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #17 pc 000359b3 /system/lib/platformsdk/libability_thread.z.so(OHOS::AbilityRuntime::UIAbilityThread::HandleAbilityTransaction(OHOS::AAFwk::Want const&, OHOS::AAFwk::LifeCycleStateInfo const&, OHOS::sptr<OHOS::AAFwk::SessionInfo>)+466)(889aa126c2fb643cd2ec6dbd64adddd1)
124   08-05 23:11:07.206  1799  1799 I C02d0b/HICHECKER: #18 pc 00039c2d /system/lib/platformsdk/libability_thread.z.so(889aa126c2fb643cd2ec6dbd64adddd1)
125   ```
126