js-apis-hidebug.md 10.5 KB
Newer Older
1
# @ohos.hidebug (Debug调试)
J
j30012456 已提交
2

3 4
> **说明:**
>
J
j30012456 已提交
5 6 7 8 9 10
> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

使用hidebug,可以获取应用内存的使用情况,包括应用进程的静态堆内存(native heap)信息、应用进程内存占用PSS(Proportional Set Size)信息等;可以完成虚拟机内存切片导出,虚拟机CPU Profiling采集等操作。

## 导入模块

W
wenlong_12 已提交
11
```ts
J
j30012456 已提交
12 13 14 15 16 17 18 19
import hidebug from '@ohos.hidebug';
```


## hidebug.getNativeHeapSize

getNativeHeapSize(): bigint

J
jiangyuan0000 已提交
20
获取本应用堆内存的总大小。
J
j30012456 已提交
21

Z
zengyawen 已提交
22 23 24
**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**返回值:**
J
j30012456 已提交
25

Z
zengyawen 已提交
26 27
| 类型   | 说明                        |
| ------ | --------------------------- |
J
jiangyuan0000 已提交
28
| bigint | 返回本应用堆内存总大小,单位为kB。 |
J
j30012456 已提交
29

Z
zengyawen 已提交
30
**示例:**
W
wenlong_12 已提交
31 32
  ```ts
  let nativeHeapSize : bigint = hidebug.getNativeHeapSize();
J
j30012456 已提交
33 34 35 36 37 38
  ```

## hidebug.getNativeHeapAllocatedSize

getNativeHeapAllocatedSize(): bigint

J
jiangyuan0000 已提交
39
获取本应用堆内存的已分配内存大小。
J
j30012456 已提交
40

Z
zengyawen 已提交
41
**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug
J
j30012456 已提交
42

Z
zengyawen 已提交
43
**返回值:**
44

Z
zengyawen 已提交
45 46
| 类型   | 说明                              |
| ------ | --------------------------------- |
J
jiangyuan0000 已提交
47
| bigint | 返回本应用堆内存的已分配内存,单位为kB。 |
J
j30012456 已提交
48

Z
zengyawen 已提交
49 50

**示例:**
W
wenlong_12 已提交
51 52
  ```ts
  let nativeHeapAllocatedSize : bigint = hidebug.getNativeHeapAllocatedSize();
J
j30012456 已提交
53 54 55 56 57 58
  ```

## hidebug.getNativeHeapFreeSize

getNativeHeapFreeSize(): bigint

J
jiangyuan0000 已提交
59
获取本应用堆内存的空闲内存大小。
J
j30012456 已提交
60

Z
zengyawen 已提交
61 62 63
**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**返回值:**
64

Z
zengyawen 已提交
65 66
| 类型   | 说明                            |
| ------ | ------------------------------- |
J
jiangyuan0000 已提交
67
| bigint | 返回本应用堆内存的空闲内存,单位为kB。 |
J
j30012456 已提交
68

Z
zengyawen 已提交
69
**示例:**
W
wenlong_12 已提交
70 71
  ```ts
  let nativeHeapFreeSize : bigint = hidebug.getNativeHeapFreeSize();
J
j30012456 已提交
72 73 74 75 76 77
  ```

## hidebug.getPss

getPss(): bigint

J
jiangyuan0000 已提交
78
获取应用进程实际使用的物理内存大小。
J
j30012456 已提交
79

Z
zengyawen 已提交
80 81 82
**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**返回值:**
83

Z
zengyawen 已提交
84 85
| 类型   | 说明                      |
| ------ | ------------------------- |
J
jiangyuan0000 已提交
86
| bigint | 返回应用进程实际使用的物理内存大小,单位为kB。 |
J
j30012456 已提交
87

Z
zengyawen 已提交
88
**示例:**
W
wenlong_12 已提交
89 90
  ```ts
  let pss : bigint = hidebug.getPss();
J
j30012456 已提交
91 92 93 94 95 96 97 98
  ```

## hidebug.getSharedDirty

getSharedDirty(): bigint

获取进程的共享脏内存大小。

Z
zengyawen 已提交
99
**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug
J
j30012456 已提交
100

Z
zengyawen 已提交
101
**返回值:**
102

Z
zengyawen 已提交
103 104
| 类型   | 说明                       |
| ------ | -------------------------- |
J
jiangyuan0000 已提交
105
| bigint | 返回进程的共享脏内存大小,单位为kB。 |
J
j30012456 已提交
106

Z
zengyawen 已提交
107 108

**示例:**
W
wenlong_12 已提交
109 110
  ```ts
  let sharedDirty : bigint = hidebug.getSharedDirty();
J
j30012456 已提交
111 112
  ```

J
j30012456 已提交
113
## hidebug.getPrivateDirty<sup>9+<sup>
J
j30012456 已提交
114 115 116 117 118 119 120 121

getPrivateDirty(): bigint

获取进程的私有脏内存大小。

**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**返回值:**
122

J
j30012456 已提交
123 124
| 类型   | 说明                       |
| ------ | -------------------------- |
J
jiangyuan0000 已提交
125
| bigint | 返回进程的私有脏内存大小,单位为kB。 |
J
j30012456 已提交
126 127

**示例:**
W
wenlong_12 已提交
128 129
  ```ts
  let privateDirty : bigint = hidebug.getPrivateDirty();
J
j30012456 已提交
130 131
  ```

J
j30012456 已提交
132
## hidebug.getCpuUsage<sup>9+<sup>
J
j30012456 已提交
133 134 135

getCpuUsage(): number

Z
zengyawen 已提交
136
获取进程的CPU使用率。
J
j30012456 已提交
137

J
j30012456 已提交
138 139
如占用率为50%,则返回0.5。

J
j30012456 已提交
140 141 142
**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**返回值:**
143

J
j30012456 已提交
144 145
| 类型   | 说明                       |
| ------ | -------------------------- |
Z
zengyawen 已提交
146
| number | 获取进程的CPU使用率。 |
J
j30012456 已提交
147 148 149


**示例:**
W
wenlong_12 已提交
150 151
  ```ts
  let cpuUsage : number = hidebug.getCpuUsage();
J
j30012456 已提交
152
  ```
J
j30012456 已提交
153

J
j30012456 已提交
154
## hidebug.getServiceDump<sup>9+<sup>
J
j30012456 已提交
155

Z
zengyawen 已提交
156
getServiceDump(serviceid : number, fd : number, args : Array\<string>) : void
J
j30012456 已提交
157 158

获取系统服务信息。
J
j30012456 已提交
159

J
jiangyuan0000 已提交
160
**需要权限**: ohos.permission.DUMP
J
j30012456 已提交
161 162 163 164 165 166 167 168

**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**参数:**

| 参数名   | 类型   | 必填 | 说明                                                         |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| serviceid | number | 是   | 基于该用户输入的service id获取系统服务信息。|
J
jiangyuan0000 已提交
169
| fd | number | 是   | 文件描述符,该接口会往该fd中写入数据。|
Z
zengyawen 已提交
170
| args | Array\<string> | 是   | 系统服务的Dump接口所对应的参数列表。|
J
j30012456 已提交
171

172

J
jiangyuan0000 已提交
173 174
**示例:**

W
wenlong_12 已提交
175
```ts
176
import fs from '@ohos.file.fs'
J
jiangyuan0000 已提交
177
import hidebug from '@ohos.hidebug'
卢韬 已提交
178
import common from '@ohos.app.ability.common'
W
wenlong_12 已提交
179
import { BusinessError } from '@ohos.base'
卢韬 已提交
180

W
wenlong_12 已提交
181
let applicationContext: common.Context | null = null;
卢韬 已提交
182 183 184
try {
  applicationContext = this.context.getApplicationContext();
} catch (error) {
W
wenlong_12 已提交
185 186
  console.info((error as BusinessError).code);
  console.info((error as BusinessError).message);
卢韬 已提交
187 188
}

W
wenlong_12 已提交
189 190 191 192
if (applicationContext) {
  let filesDir : string = applicationContext.filesDir;
}
let path : string = filesDir + "/serviceInfo.txt";
卢韬 已提交
193
console.info("output path: " + path);
W
wenlong_12 已提交
194 195 196
let file : file.fs = fs.openSync(path, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
let serviceId : number = 10;
let args : Array = new Array("allInfo");
卢韬 已提交
197 198 199 200

try {
  hidebug.getServiceDump(serviceId, file.fd, args);
} catch (error) {
W
wenlong_12 已提交
201 202
  console.info((error as BusinessError).code);
  console.info((error as BusinessError).message);
卢韬 已提交
203 204
}
fs.closeSync(file);
J
jiangyuan0000 已提交
205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222
```

## hidebug.startJsCpuProfiling<sup>9+</sup>

startJsCpuProfiling(filename : string) : void

启动虚拟机Profiling方法跟踪,`startJsCpuProfiling()`方法的调用需要与`stopJsCpuProfiling()`方法的调用一一对应,先开启后关闭,严禁使用`start->start->stop``start->stop->stop``start->start->stop->stop`等类似的顺序调用。

**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**参数:**

| 参数名   | 类型   | 必填 | 说明                                                         |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| filename | string | 是   | 用户自定义的profiling文件名,根据传入的`filename`,将在应用的`files`目录生成`filename.json`文件。 |

**示例:**

W
wenlong_12 已提交
223
```ts
J
jiangyuan0000 已提交
224
import hidebug from '@ohos.hidebug'
W
wenlong_12 已提交
225
import { BusinessError } from '@ohos.base'
J
jiangyuan0000 已提交
226 227 228

try {
  hidebug.startJsCpuProfiling("cpu_profiling");
229
  // ...
J
jiangyuan0000 已提交
230 231
  hidebug.stopJsCpuProfiling();
} catch (error) {
W
wenlong_12 已提交
232 233
  console.info((error as BusinessError).code)
  console.info((error as BusinessError).message)
J
jiangyuan0000 已提交
234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252
}
```

## hidebug.stopJsCpuProfiling<sup>9+</sup>

stopJsCpuProfiling() : void

停止虚拟机Profiling方法跟踪,`startJsCpuProfiling()`方法的调用需要与`stopJsCpuProfiling()`方法的调用一一对应,先开启后关闭,严禁使用`start->start->stop``start->stop->stop``start->start->stop->stop`等类似的顺序调用。

**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**参数:**

| 参数名   | 类型   | 必填 | 说明                                                         |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| filename | string | 是   | 用户自定义的profiling文件名,根据传入的`filename`,将在应用的`files`目录生成`filename.json`文件。 |

**示例:**

W
wenlong_12 已提交
253
```ts
J
jiangyuan0000 已提交
254
import hidebug from '@ohos.hidebug'
W
wenlong_12 已提交
255
import { BusinessError } from '@ohos.base'
J
jiangyuan0000 已提交
256 257 258

try {
  hidebug.startJsCpuProfiling("cpu_profiling");
259
  // ...
J
jiangyuan0000 已提交
260 261
  hidebug.stopJsCpuProfiling();
} catch (error) {
W
wenlong_12 已提交
262 263
  console.info((error as BusinessError).code)
  console.info((error as BusinessError).message)
J
jiangyuan0000 已提交
264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279
}
```

## hidebug.dumpJsHeapData<sup>9+</sup>

dumpJsHeapData(filename : string) : void

虚拟机堆导出。

**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**参数:**

| 参数名   | 类型   | 必填 | 说明                                                         |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| filename | string | 是   | 用户自定义的虚拟机堆文件名,根据传入的`filename`,将在应用的`files`目录生成`filename.heapsnapshot`文件。 |
J
j30012456 已提交
280 281 282

**示例:**

W
wenlong_12 已提交
283
```ts
J
jiangyuan0000 已提交
284
import hidebug from '@ohos.hidebug'
W
wenlong_12 已提交
285
import { BusinessError } from '@ohos.base'
J
jiangyuan0000 已提交
286 287 288 289

try {
  hidebug.dumpJsHeapData("heapData");
} catch (error) {
W
wenlong_12 已提交
290 291
  console.info((error as BusinessError).code)
  console.info((error as BusinessError).message)
J
jiangyuan0000 已提交
292
}
Z
zengyawen 已提交
293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312
```

## hidebug.startProfiling<sup>(deprecated)</sup>

startProfiling(filename : string) : void

> **说明:** 从 API Version 9 开始废弃,建议使用[hidebug.startJsCpuProfiling](#hidebugstartjscpuprofiling9)替代。

启动虚拟机Profiling方法跟踪,`startProfiling()`方法的调用需要与`stopProfiling()`方法的调用一一对应,先开启后关闭,严禁使用`start->start->stop``start->stop->stop``start->start->stop->stop`等类似的顺序调用。

**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**参数:**

| 参数名   | 类型   | 必填 | 说明                                                         |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| filename | string | 是   | 用户自定义的profiling文件名,根据传入的`filename`,将在应用的`files`目录生成`filename.json`文件。 |

**示例:**

W
wenlong_12 已提交
313
```ts
Z
zengyawen 已提交
314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332
hidebug.startProfiling("cpuprofiler-20220216");
// code block
// ...
// code block
hidebug.stopProfiling();
```

## hidebug.stopProfiling<sup>(deprecated)</sup>

stopProfiling() : void

> **说明:** 从 API Version 9 开始废弃,建议使用[hidebug.stopJsCpuProfiling](#hidebugstopjscpuprofiling9)替代。

停止虚拟机Profiling方法跟踪,`stopProfiling()`方法的调用需要与`startProfiling()`方法的调用一一对应,先开启后关闭,严禁使用`start->start->stop``start->stop->stop``start->start->stop->stop`等类似的顺序调用。

**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**示例:**

W
wenlong_12 已提交
333
```ts
Z
zengyawen 已提交
334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358
hidebug.startProfiling("cpuprofiler-20220216");
// code block
// ...
// code block
hidebug.stopProfiling();
```

## hidebug.dumpHeapData<sup>(deprecated)</sup>

dumpHeapData(filename : string) : void

> **说明:** 从 API Version 9 开始废弃,建议使用[hidebug.dumpJsHeapData](#hidebugdumpjsheapdata9)替代。

虚拟机堆导出。

**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**参数:**

| 参数名   | 类型   | 必填 | 说明                                                         |
| -------- | ------ | ---- | ------------------------------------------------------------ |
| filename | string | 是   | 用户自定义的虚拟机堆文件名,根据传入的`filename`,将在应用的`files`目录生成`filename.heapsnapshot`文件。 |

**示例:**

W
wenlong_12 已提交
359
```ts
Z
zengyawen 已提交
360 361
hidebug.dumpHeapData("heap-20220216");
```