1# @ohos.hichecker (检测模式)
2
3HiChecker可以作为应用开发阶段使用的检测工具,用于检测代码运行过程中部分易忽略的问题,如应用线程出现耗时调用、应用进程中Ability资源泄露等问题。开发者可以通过日志记录或进程crash等形式查看具体问题并进行修改,提升应用的使用体验。
4
5> **说明:**
6>
7> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。
8
9## 导入模块
10
11```ts
12import { hichecker } from '@kit.PerformanceAnalysisKit';
13```
14
15
16## 常量
17
18提供了所有规则类型的常量。
19
20**系统能力:** SystemCapability.HiviewDFX.HiChecker
21
22| 名称                                             | 类型      | 值         | 说明                                                   |
23| ------------------------------------------------ | -------- | -----------| ------------------------------------------------------ |
24| RULE_CAUTION_PRINT_LOG                           | bigint   | 1ULL << 63 | 告警规则,当有告警时记录日志。                            |
25| RULE_CAUTION_TRIGGER_CRASH                       | bigint   | 1ULL << 62 | 告警规则,当有告警时让应用退出。                          |
26| RULE_THREAD_CHECK_SLOW_PROCESS                   | bigint   | 1ULL       | 检测规则,检测是否有耗时函数被调用。                      |
27| RULE_CHECK_ABILITY_CONNECTION_LEAK               | bigint   | 1ULL << 33 | 检测规则,检测是否发生ability泄露。                      |
28| RULE_CHECK_ARKUI_PERFORMANCE<sup>11+</sup>       | bigint   | 1ULL << 34 | 检测规则,检测arkui性能。                               |
29## hichecker.addCheckRule<sup>9+</sup>
30
31addCheckRule(rule: bigint): void
32
33添加一条或多条规则到系统,系统根据添加的规则进行检测或反馈,当有相应规则触发时可在hilog中grep HiChecker查看运行信息。
34
35**系统能力:** SystemCapability.HiviewDFX.HiChecker
36
37**参数:**
38
39| 参数名 | 类型   | 必填 | 说明             |
40| ------ | ------ | ---- | ---------------- |
41| rule   | bigint | 是   | 需要添加的规则。 |
42
43**错误码:**
44
45| 错误码ID | 错误信息 |
46| ------- | ----------------------------------------------------------------- |
47| 401 | the parameter check failed, only one bigint type parameter is needed  |
48
49**示例:**
50
51```ts
52import { BusinessError } from '@kit.BasicServicesKit';
53
54try {
55    // 添加一条规则
56    hichecker.addCheckRule(hichecker.RULE_CAUTION_PRINT_LOG);
57    // 添加多条规则
58    // hichecker.addCheckRule(
59    //     hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH);
60} catch (err) {
61    console.error(`code: ${(err as BusinessError).code}, message: ${(err as BusinessError).message}`);
62}
63```
64
65## hichecker.removeCheckRule<sup>9+</sup>
66
67removeCheckRule(rule: bigint): void
68
69删除一条或多条规则,删除的规则后续将不再生效。
70
71**系统能力:** SystemCapability.HiviewDFX.HiChecker
72
73**参数:**
74
75| 参数名 | 类型   | 必填 | 说明             |
76| ------ | ------ | ---- | ---------------- |
77| rule   | bigint | 是   | 需要删除的规则。 |
78
79**错误码:**
80
81| 错误码ID | 错误信息 |
82| ------- | ----------------------------------------------------------------- |
83| 401 | the parameter check failed, only one bigint type parameter is needed  |
84
85**示例:**
86
87```ts
88import { BusinessError } from '@kit.BasicServicesKit';
89
90try {
91    // 删除一条规则
92    hichecker.removeCheckRule(hichecker.RULE_CAUTION_PRINT_LOG);
93    // 删除多条规则
94    // hichecker.removeCheckRule(
95    //     hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH);
96} catch (err) {
97    console.error(`code: ${(err as BusinessError).code}, message: ${(err as BusinessError).message}`);
98}
99```
100
101## hichecker.containsCheckRule<sup>9+</sup>
102
103containsCheckRule(rule: bigint): boolean
104
105当前已添加的规则集中是否包含了某一个特定的规则,如果传入的规则级别为线程级别,则仅在当前线程中进行查询。
106
107**系统能力:** SystemCapability.HiviewDFX.HiChecker
108
109**参数:**
110
111| 参数名 | 类型   | 必填 | 说明             |
112| ------ | ------ | ---- | ---------------- |
113| rule   | bigint | 是   | 需要查询的规则。 |
114
115**返回值:**
116
117| 类型    | 说明                                                       |
118| ------- | ---------------------------------------------------------- |
119| boolean | 查询结果,true&nbsp;表示规则已添加,false 表示规则未添加。 |
120
121**错误码:**
122
123| 错误码ID | 错误信息 |
124| ------- | ----------------------------------------------------------------- |
125| 401 | the parameter check failed, only one bigint type parameter is needed  |
126
127**示例:**
128
129```ts
130import { BusinessError } from '@kit.BasicServicesKit';
131
132try {
133    // 添加一条规则
134    hichecker.addCheckRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS);
135
136    // 查询是否包含
137    hichecker.containsCheckRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS); // return true;
138    hichecker.containsCheckRule(hichecker.RULE_CAUTION_PRINT_LOG); // return false;
139} catch (err) {
140    console.error(`code: ${(err as BusinessError).code}, message: ${(err as BusinessError).message}`);
141}
142```
143
144## hichecker.addRule<sup>(deprecated)</sup>
145
146addRule(rule: bigint): void
147
148> **说明:**
149>
150> 从 API Version 9 开始废弃,建议使用[hichecker.addCheckRule](#hicheckeraddcheckrule9)替代。
151
152添加一条或多条规则到系统,系统根据添加的规则进行检测或反馈。
153
154**系统能力:** SystemCapability.HiviewDFX.HiChecker
155
156**参数:**
157
158| 参数名 | 类型   | 必填 | 说明             |
159| ------ | ------ | ---- | ---------------- |
160| rule   | bigint | 是   | 需要添加的规则。 |
161
162**示例:**
163
164```ts
165// 添加一条规则
166hichecker.addRule(hichecker.RULE_CAUTION_PRINT_LOG);
167
168// 添加多条规则
169hichecker.addRule(
170          hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH);
171```
172
173## hichecker.removeRule<sup>(deprecated)</sup>
174
175removeRule(rule: bigint): void
176
177> **说明:**
178>
179> 从 API Version 9 开始废弃,建议使用[hichecker.removeCheckRule](#hicheckerremovecheckrule9)替代。
180
181删除一条或多条规则,删除的规则后续将不再生效。
182
183**系统能力:** SystemCapability.HiviewDFX.HiChecker
184
185**参数:**
186
187| 参数名 | 类型   | 必填 | 说明             |
188| ------ | ------ | ---- | ---------------- |
189| rule   | bigint | 是   | 需要删除的规则。 |
190
191**示例:**
192
193```ts
194// 删除一条规则
195hichecker.removeRule(hichecker.RULE_CAUTION_PRINT_LOG);
196
197// 删除多条规则
198hichecker.removeRule(
199          hichecker.RULE_CAUTION_PRINT_LOG | hichecker.RULE_CAUTION_TRIGGER_CRASH);
200```
201
202## hichecker.getRule
203
204getRule(): bigint
205
206获取当前线程规则、进程规则、告警规则的合集。
207
208**系统能力:** SystemCapability.HiviewDFX.HiChecker
209
210**返回值:**
211
212| 类型   | 说明                   |
213| ------ | ---------------------- |
214| bigint | 当前系统中添加的规则。 |
215
216**示例:**
217
218```ts
219// 添加一条规则
220hichecker.addRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS);
221
222// 获取已添加的规则
223hichecker.getRule();   // return 1n;
224```
225
226## hichecker.contains<sup>(deprecated)</sup>
227
228contains(rule: bigint): boolean
229
230> **说明:**
231>
232> 从 API Version 9 开始废弃,建议使用[hichecker.containsCheckRule](#hicheckercontainscheckrule9)替代。
233
234当前已添加的规则集中是否包含了某一个特定的规则,如果传入的规则级别为线程级别,则仅在当前线程中进行查询。
235
236**系统能力:** SystemCapability.HiviewDFX.HiChecker
237
238**参数:**
239
240| 参数名 | 类型   | 必填 | 说明             |
241| ------ | ------ | ---- | ---------------- |
242| rule   | bigint | 是   | 需要查询的规则。 |
243
244**返回值:**
245
246| 类型    | 说明                                                       |
247| ------- | ---------------------------------------------------------- |
248| boolean | 查询结果,true&nbsp;表示规则已添加,false 表示规则未添加。 |
249
250**示例:**
251
252```ts
253// 添加一条规则
254hichecker.addRule(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS);
255
256// 查询是否包含
257hichecker.contains(hichecker.RULE_THREAD_CHECK_SLOW_PROCESS); // return true;
258hichecker.contains(hichecker.RULE_CAUTION_PRINT_LOG); // return false;
259```
260