js-apis-hidebug.md 10.1 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采集等操作。

## 导入模块

J
j30012456 已提交
11
```js
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

J
j30012456 已提交
22
本接口在OpenHarmony 3.1 Release版本仅为接口定义,暂不支持使用。
J
j30012456 已提交
23

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

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

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


Z
zengyawen 已提交
33
**示例:**
J
j30012456 已提交
34
  ```js
J
j30012456 已提交
35 36 37 38 39 40 41 42
  let nativeHeapSize = hidebug.getNativeHeapSize();
  ```


## hidebug.getNativeHeapAllocatedSize

getNativeHeapAllocatedSize(): bigint

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

J
j30012456 已提交
45
本接口在OpenHarmony 3.1 Release版本仅为接口定义,暂不支持使用。
J
j30012456 已提交
46

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

Z
zengyawen 已提交
49
**返回值:**
50

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

Z
zengyawen 已提交
55 56

**示例:**
J
j30012456 已提交
57
  ```js
J
j30012456 已提交
58 59 60 61 62 63 64 65
  let nativeHeapAllocatedSize = hidebug.getNativeHeapAllocatedSize();
  ```


## hidebug.getNativeHeapFreeSize

getNativeHeapFreeSize(): bigint

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

J
j30012456 已提交
68
本接口在OpenHarmony 3.1 Release版本仅为接口定义,暂不支持使用。
J
j30012456 已提交
69

Z
zengyawen 已提交
70 71 72
**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**返回值:**
73

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

Z
zengyawen 已提交
78
**示例:**
J
j30012456 已提交
79
  ```js
J
j30012456 已提交
80 81 82 83 84 85 86 87
  let nativeHeapFreeSize = hidebug.getNativeHeapFreeSize();
  ```


## hidebug.getPss

getPss(): bigint

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

Z
zengyawen 已提交
90 91 92
**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**返回值:**
93

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

Z
zengyawen 已提交
98
**示例:**
J
j30012456 已提交
99
  ```js
J
j30012456 已提交
100 101 102 103 104 105 106 107 108 109
  let pss = hidebug.getPss();
  ```


## hidebug.getSharedDirty

getSharedDirty(): bigint

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

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

Z
zengyawen 已提交
112
**返回值:**
113

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

Z
zengyawen 已提交
118 119

**示例:**
J
j30012456 已提交
120
  ```js
J
j30012456 已提交
121
  let sharedDirty = hidebug.getSharedDirty();
J
j30012456 已提交
122 123
  ```

J
j30012456 已提交
124
## hidebug.getPrivateDirty<sup>9+<sup>
J
j30012456 已提交
125 126 127 128 129 130 131 132

getPrivateDirty(): bigint

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

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

**返回值:**
133

J
j30012456 已提交
134 135
| 类型   | 说明                       |
| ------ | -------------------------- |
J
jiangyuan0000 已提交
136
| bigint | 返回进程的私有脏内存大小,单位为kB。 |
J
j30012456 已提交
137 138 139 140 141 142 143


**示例:**
  ```js
  let privateDirty = hidebug.getPrivateDirty();
  ```

J
j30012456 已提交
144
## hidebug.getCpuUsage<sup>9+<sup>
J
j30012456 已提交
145 146 147

getCpuUsage(): number

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

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

J
j30012456 已提交
152 153 154
**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**返回值:**
155

J
j30012456 已提交
156 157
| 类型   | 说明                       |
| ------ | -------------------------- |
Z
zengyawen 已提交
158
| number | 获取进程的CPU使用率。 |
J
j30012456 已提交
159 160 161 162 163 164


**示例:**
  ```js
  let cpuUsage = hidebug.getCpuUsage();
  ```
J
j30012456 已提交
165

J
jiangyuan0000 已提交
166
## hidebug.startProfiling<sup>(deprecated)</sup>
J
j30012456 已提交
167 168 169

startProfiling(filename : string) : void

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

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

Z
zengyawen 已提交
174 175 176
**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**参数:**
J
j30012456 已提交
177 178 179 180 181

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

Z
zengyawen 已提交
182
**示例:**
J
j30012456 已提交
183

J
j30012456 已提交
184
```js
J
j30012456 已提交
185 186 187 188 189 190 191 192 193
hidebug.startProfiling("cpuprofiler-20220216");
// code block
// ...
// code block
hidebug.stopProfiling();
```



J
jiangyuan0000 已提交
194
## hidebug.stopProfiling<sup>(deprecated)</sup>
J
j30012456 已提交
195 196 197

stopProfiling() : void

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

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

Z
zengyawen 已提交
202 203 204
**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**示例:**
J
j30012456 已提交
205

J
j30012456 已提交
206
```js
J
j30012456 已提交
207 208 209 210 211 212 213
hidebug.startProfiling("cpuprofiler-20220216");
// code block
// ...
// code block
hidebug.stopProfiling();
```

J
jiangyuan0000 已提交
214
## hidebug.dumpHeapData<sup>(deprecated)</sup>
J
j30012456 已提交
215 216 217

dumpHeapData(filename : string) : void

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

J
j30012456 已提交
220 221
虚拟机堆导出。

Z
zengyawen 已提交
222 223 224
**系统能力:** SystemCapability.HiviewDFX.HiProfiler.HiDebug

**参数:**
J
j30012456 已提交
225 226 227 228 229

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

Z
zengyawen 已提交
230
**示例:**
J
j30012456 已提交
231

J
j30012456 已提交
232
```js
J
j30012456 已提交
233
hidebug.dumpHeapData("heap-20220216");
J
j30012456 已提交
234 235
```

J
j30012456 已提交
236
## hidebug.getServiceDump<sup>9+<sup>
J
j30012456 已提交
237

Z
zengyawen 已提交
238
getServiceDump(serviceid : number, fd : number, args : Array\<string>) : void
J
j30012456 已提交
239 240

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

J
jiangyuan0000 已提交
242
**需要权限**: ohos.permission.DUMP
J
j30012456 已提交
243 244 245 246 247 248 249 250

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

**参数:**

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

254

J
jiangyuan0000 已提交
255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349
**示例:**

```js
import fileio from '@ohos.fileio'
import hidebug from '@ohos.hidebug'
import featureAbility from '@ohos.ability.featureAbility'

let context = featureAbility.getContext();
context.getFilesDir().then((data) => {
  var path = data + "/serviceInfo.txt"
  console.info("output path: " + path)
  let fd = fileio.openSync(path, 0o102, 0o666)
  var serviceId = 10
  var args = new Array("allInfo")
  try {
    hidebug.getServiceDump(serviceId, fd, args)
  } catch (error) {
    console.info(error.code)
    console.info(error.message)
  }
  fileio.closeSync(fd);
})
```

## 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`文件。 |

**示例:**

```js
import hidebug from '@ohos.hidebug'

try {
  hidebug.startJsCpuProfiling("cpu_profiling");
  ...
  hidebug.stopJsCpuProfiling();
} catch (error) {
  console.info(error.code)
  console.info(error.message)
}
```

## 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`文件。 |

**示例:**

```js
import hidebug from '@ohos.hidebug'

try {
  hidebug.startJsCpuProfiling("cpu_profiling");
  ...
  hidebug.stopJsCpuProfiling();
} catch (error) {
  console.info(error.code)
  console.info(error.message)
}
```

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

dumpJsHeapData(filename : string) : void

虚拟机堆导出。

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

**参数:**

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

**示例:**

```js
J
jiangyuan0000 已提交
354 355 356 357 358 359 360 361
import hidebug from '@ohos.hidebug'

try {
  hidebug.dumpJsHeapData("heapData");
} catch (error) {
  console.info(error.code)
  console.info(error.message)
}
Z
zengyawen 已提交
362
```