1# @ohos.hidebug (Debug调试) 2 3为应用提供多种以供调试、调优的方法。包括但不限于内存、CPU、GPU、GC等相关数据的获取，进程trace、profiler采集，VM堆快照转储等。由于该模块的接口大多比较耗费性能，接口调用较为耗时，且基于HiDebug模块定义，该模块内的接口仅建议在应用调试，调优阶段使用。若需要在其他场景使用时，请认真评估所需调用的接口对应用性能的影响。 4 5> **说明：** 6> 7> 本模块首批接口从API version 8开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 8 9## 导入模块 10 11```ts 12import { hidebug } from '@kit.PerformanceAnalysisKit'; 13``` 14 15## hidebug.getNativeHeapSize 16 17getNativeHeapSize(): bigint 18 19获取内存分配器统计的进程持有的普通块所占用的总字节数。 20 21**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 22 23**返回值：** 24 25| 类型 | 说明 | 26| ------ |--------------------------------------------| 27| bigint | 内存分配器统计的进程持有的普通块所占用内存的大小（含分配器元数据），单位为Byte。 | 28 29**示例：** 30 31```ts 32import { hidebug } from '@kit.PerformanceAnalysisKit'; 33 34let nativeHeapSize: bigint = hidebug.getNativeHeapSize(); 35``` 36 37## hidebug.getNativeHeapAllocatedSize 38 39getNativeHeapAllocatedSize(): bigint 40 41获取内存分配器统计的进程持有的已使用的普通块所占用的总字节数。 42 43**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 44 45**返回值：** 46 47| 类型 | 说明 | 48| ------ | --------------------------------- | 49| bigint | 返回内存分配器统计的进程持有的已使用的普通块所占用内存大小，单位为Byte。 | 50 51 52**示例：** 53```ts 54import { hidebug } from '@kit.PerformanceAnalysisKit'; 55 56let nativeHeapAllocatedSize: bigint = hidebug.getNativeHeapAllocatedSize(); 57``` 58 59## hidebug.getNativeHeapFreeSize 60 61getNativeHeapFreeSize(): bigint 62 63获取内存分配器统计的进程持有的空闲的普通块所占用的总字节数。 64 65**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 66 67**返回值：** 68 69| 类型 | 说明 | 70| ------ | ----------------------------- | 71| bigint | 返回内存分配器持有的空闲的普通块所占用内存大小，单位为Byte。 | 72 73**示例：** 74```ts 75import { hidebug } from '@kit.PerformanceAnalysisKit'; 76 77let nativeHeapFreeSize: bigint = hidebug.getNativeHeapFreeSize(); 78``` 79 80## hidebug.getPss 81 82getPss(): bigint 83 84获取应用进程实际使用的物理内存大小。接口实现方式：读取/proc/{pid}/smaps_rollup节点中的Pss与SwapPss值并求和。 85 86> **注意：** 87> 88> 由于/proc/{pid}/smaps_rollup的读取比较耗时，建议不要在主线程中使用该接口，可通过[@ohos.taskpool](../apis-arkts/js-apis-taskpool.md)或[@ohos.worker](../apis-arkts/js-apis-worker.md)开启异步线程以避免应用出现卡顿。 89 90**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 91 92**返回值：** 93 94| 类型 | 说明 | 95| ------ | ------------------------- | 96| bigint | 返回应用进程实际使用的物理内存大小，单位为KB。 | 97 98**示例：** 99```ts 100import { hidebug } from '@kit.PerformanceAnalysisKit'; 101 102let pss: bigint = hidebug.getPss(); 103``` 104 105## hidebug.getVss<sup>11+</sup> 106 107getVss(): bigint 108 109获取应用进程虚拟耗用内存大小。接口实现方式：读取/proc/{pid}/statm节点中的size值（内存页数），vss = size * 页大小（4K/页）。 110 111**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 112 113**返回值：** 114 115| 类型 | 说明 | 116| ------ | ---------------------------------------- | 117| bigint | 返回应用进程虚拟耗用内存大小，单位为KB。 | 118 119**示例：** 120 121```ts 122import { hidebug } from '@kit.PerformanceAnalysisKit'; 123 124let vss: bigint = hidebug.getVss(); 125``` 126 127## hidebug.getSharedDirty 128 129getSharedDirty(): bigint 130 131获取进程的共享脏内存大小。接口实现方式：读取/proc/{pid}/smaps_rollup节点中的Shared_Dirty值。 132 133> **注意：** 134> 135> 由于/proc/{pid}/smaps_rollup的读取比较耗时，建议不要在主线程中使用该接口，可通过[@ohos.taskpool](../apis-arkts/js-apis-taskpool.md)或[@ohos.worker](../apis-arkts/js-apis-worker.md)开启异步线程以避免应用出现卡顿。 136 137**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 138 139**返回值：** 140 141| 类型 | 说明 | 142| ------ | -------------------------- | 143| bigint | 返回进程的共享脏内存大小，单位为KB。 | 144 145 146**示例：** 147```ts 148import { hidebug } from '@kit.PerformanceAnalysisKit'; 149 150let sharedDirty: bigint = hidebug.getSharedDirty(); 151``` 152 153## hidebug.getPrivateDirty<sup>9+</sup> 154 155getPrivateDirty(): bigint 156 157获取进程的私有脏内存大小。读取/proc/{pid}/smaps_rollup中的Private_Dirty值。 158 159> **注意：** 160> 161> 由于/proc/{pid}/smaps_rollup的读取比较耗时，建议不要在主线程中使用该接口，可通过[@ohos.taskpool](../apis-arkts/js-apis-taskpool.md)或[@ohos.worker](../apis-arkts/js-apis-worker.md)开启异步线程以避免应用出现卡顿。 162 163**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 164 165**返回值：** 166 167| 类型 | 说明 | 168| ------ | -------------------------- | 169| bigint | 返回进程的私有脏内存大小，单位为KB。 | 170 171**示例：** 172```ts 173import { hidebug } from '@kit.PerformanceAnalysisKit'; 174 175let privateDirty: bigint = hidebug.getPrivateDirty(); 176``` 177 178## hidebug.getCpuUsage<sup>9+</sup> 179 180getCpuUsage(): number 181 182获取进程的CPU使用率。 183 184如占用率为50%，则返回0.5。 185 186**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 187 188**返回值：** 189 190| 类型 | 说明 | 191| ------ | -------------------------- | 192| number | 获取进程的CPU使用率。 | 193 194 195**示例：** 196```ts 197import { hidebug } from '@kit.PerformanceAnalysisKit'; 198 199let cpuUsage: number = hidebug.getCpuUsage(); 200``` 201 202## hidebug.getServiceDump<sup>9+</sup> 203 204getServiceDump(serviceid: number, fd: number, args: Array\<string>) : void 205 206获取系统服务信息。 207 208**需要权限**：ohos.permission.DUMP，仅系统应用可申请。 209 210**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 211 212**参数：** 213 214| 参数名 | 类型 | 必填 | 说明 | 215| -------- | ------ | ---- |----------------------------| 216| serviceid | number | 是 | 基于用户输入的service id获取系统服务信息。 | 217| fd | number | 是 | 文件描述符，接口会向该fd写入数据。 | 218| args | Array<string> | 是 | 系统服务的dump接口参数列表。 | 219 220**错误码：** 221 222以下错误码的详细介绍请参见[HiDebug错误码](errorcode-hiviewdfx-hidebug.md)。 223 224| 错误码ID | 错误信息 | 225| ------- | ----------------------------------------------------------------- | 226| 401 | the parameter check failed,Possible causes:1.the parameter type error 2.the args parameter is not string array. | 227| 11400101 | ServiceId invalid. The system ability does not exist. | 228 229**示例：** 230 231```ts 232import { fileIo } from '@kit.CoreFileKit'; 233import { hidebug } from '@kit.PerformanceAnalysisKit'; 234import { BusinessError } from '@kit.BasicServicesKit'; 235 236let fileFd = -1; 237try { 238 let path: string = this.getUIContext().getHostContext()!.filesDir + "/serviceInfo.txt"; 239 console.info("output path: " + path); 240 fileFd = fileIo.openSync(path, fileIo.OpenMode.READ_WRITE | fileIo.OpenMode.CREATE).fd; 241 let serviceId: number = 10; 242 let args: Array<string> = new Array("allInfo"); 243 hidebug.getServiceDump(serviceId, fileFd, args); 244} catch (error) { 245 console.error(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 246} 247 248if (fileFd >= 0) { 249 fileIo.closeSync(fileFd); 250} 251``` 252 253## hidebug.startJsCpuProfiling<sup>9+</sup> 254 255startJsCpuProfiling(filename: string) : void 256 257启动虚拟机Profiling方法跟踪，`startJsCpuProfiling(filename: string)`方法的调用需要与`stopJsCpuProfiling()`方法的调用一一对应，先开启后关闭，请避免重复开启或重复关闭的调用方式，否则会接口调用异常。 258 259**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 260 261**参数：** 262 263| 参数名 | 类型 | 必填 | 说明 | 264| -------- | ------ | ---- |--------------------------------------------------| 265| filename | string | 是 | 用户自定义的采样结果输出的文件名，将在应用的`files`目录下生成以该参数命名的json文件。 | 266 267**错误码：** 268 269以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 270 271| 错误码ID | 错误信息 | 272| ------- | ----------------------------------------------------------------- | 273| 401 | the parameter check failed,Parameter type error. | 274 275**示例：** 276 277```ts 278import { hidebug } from '@kit.PerformanceAnalysisKit'; 279import { BusinessError } from '@kit.BasicServicesKit'; 280 281try { 282 hidebug.startJsCpuProfiling("cpu_profiling"); 283 // ... 284 hidebug.stopJsCpuProfiling(); 285} catch (error) { 286 console.error(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 287} 288``` 289 290## hidebug.stopJsCpuProfiling<sup>9+</sup> 291 292stopJsCpuProfiling() : void 293 294停止虚拟机Profiling方法跟踪，`stopJsCpuProfiling()`方法的调用需要与`startJsCpuProfiling(filename: string)`方法的调用一一对应，先开启后关闭，请避免重复开启或重复关闭的调用方式，否则会接口调用异常。 295 296**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 297 298**示例：** 299 300```ts 301import { hidebug } from '@kit.PerformanceAnalysisKit'; 302import { BusinessError } from '@kit.BasicServicesKit'; 303 304try { 305 hidebug.startJsCpuProfiling("cpu_profiling"); 306 // ... 307 hidebug.stopJsCpuProfiling(); 308} catch (error) { 309 console.error(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 310} 311``` 312 313## hidebug.dumpJsHeapData<sup>9+</sup> 314 315dumpJsHeapData(filename: string) : void 316 317虚拟机堆导出。 318 319**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 320 321**参数：** 322 323| 参数名 | 类型 | 必填 | 说明 | 324| -------- | ------ | ---- | ----------------------------------------------- | 325| filename | string | 是 | 用户自定义的采样结果输出的文件名，将在应用的`files`目录下生成以该参数命名的heapsnapshot文件。 | 326 327**错误码：** 328 329以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 330 331| 错误码ID | 错误信息 | 332| ------- | ----------------------------------------------------------------- | 333| 401 | the parameter check failed, Parameter type error. | 334 335**示例：** 336 337```ts 338import { hidebug } from '@kit.PerformanceAnalysisKit'; 339import { BusinessError } from '@kit.BasicServicesKit'; 340 341try { 342 hidebug.dumpJsHeapData("heapData"); 343} catch (error) { 344 console.error(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 345} 346``` 347 348## hidebug.startProfiling<sup>(deprecated)</sup> 349 350startProfiling(filename: string) : void 351 352> **说明：** 353> 354> 从 API Version 9 开始废弃，建议使用[hidebug.startJsCpuProfiling](#hidebugstartjscpuprofiling9)替代。 355 356启动虚拟机Profiling方法跟踪，`startProfiling(filename: string)`方法的调用需要与`stopProfiling()`方法的调用一一对应，先开启后关闭，请避免重复开启或重复关闭的调用方式，否则会接口调用异常。 357 358**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 359 360**参数：** 361 362| 参数名 | 类型 | 必填 | 说明 | 363| -------- | ------ | ---- | ------------------------------------------------ | 364| filename | string | 是 | 用户自定义的采样结果输出的文件名，将在应用的`files`目录下生成以该参数命名的json文件。 | 365 366**示例：** 367 368```ts 369import { hidebug } from '@kit.PerformanceAnalysisKit'; 370 371hidebug.startProfiling("cpuprofiler-20220216"); 372// code block 373// ... 374// code block 375hidebug.stopProfiling(); 376``` 377 378## hidebug.stopProfiling<sup>(deprecated)</sup> 379 380stopProfiling() : void 381 382> **说明：** 383> 384> 从 API Version 9 开始废弃，建议使用[hidebug.stopJsCpuProfiling](#hidebugstopjscpuprofiling9)替代。 385 386停止虚拟机Profiling方法跟踪，`stopProfiling()`方法的调用需要与`startProfiling(filename: string)`方法的调用一一对应，先开启后关闭，请避免重复开启或重复关闭的调用方式，否则会接口调用异常。 387 388**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 389 390**示例：** 391 392```ts 393import { hidebug } from '@kit.PerformanceAnalysisKit'; 394 395hidebug.startProfiling("cpuprofiler-20220216"); 396// code block 397// ... 398// code block 399hidebug.stopProfiling(); 400``` 401 402## hidebug.dumpHeapData<sup>(deprecated)</sup> 403 404dumpHeapData(filename: string) : void 405 406> **说明：** 407> 408> 从 API Version 9 开始废弃，建议使用[hidebug.dumpJsHeapData](#hidebugdumpjsheapdata9)替代。 409 410虚拟机堆导出，生成`filename.heapsnapshot`文件。 411 412**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 413 414**参数：** 415 416| 参数名 | 类型 | 必填 | 说明 | 417| -------- | ------ | ---- |---------------------------------------------------------| 418| filename | string | 是 | 用户自定义的虚拟机堆转储文件名，将在应用的`files`目录下生成以该参数命名的heapsnapshot文件。 | 419 420**示例：** 421 422```ts 423import { hidebug } from '@kit.PerformanceAnalysisKit'; 424 425hidebug.dumpHeapData("heap-20220216"); 426``` 427 428## hidebug.getAppVMMemoryInfo<sup>12+</sup> 429 430getAppVMMemoryInfo(): VMMemoryInfo 431 432获取VM内存相关信息。 433 434**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 435 436**返回值：** 437 438| 类型 | 说明 | 439| -------------| --------------------------------------- | 440| [VMMemoryInfo](#vmmemoryinfo12) | 返回VM内存信息。 | 441 442**示例：** 443 444```ts 445import { hidebug } from '@kit.PerformanceAnalysisKit'; 446 447let vmMemory: hidebug.VMMemoryInfo = hidebug.getAppVMMemoryInfo(); 448console.info(`totalHeap = ${vmMemory.totalHeap}, heapUsed = ${vmMemory.heapUsed},` + 449 `allArraySize = ${vmMemory.allArraySize}` ); 450``` 451 452## hidebug.getAppThreadCpuUsage<sup>12+</sup> 453 454getAppThreadCpuUsage(): ThreadCpuUsage[] 455 456获取应用线程CPU使用情况。 457 458**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 459 460**返回值：** 461 462| 类型 | 说明 | 463| -----------------| ------------------------------------------------------------| 464| [ThreadCpuUsage](#threadcpuusage12)[] | 返回当前应用进程下所有ThreadCpuUsage数组。 | 465 466 467 468**示例：** 469 470```ts 471import { hidebug } from '@kit.PerformanceAnalysisKit'; 472 473let appThreadCpuUsage: hidebug.ThreadCpuUsage[] = hidebug.getAppThreadCpuUsage(); 474for (let i = 0; i < appThreadCpuUsage.length; i++) { 475 console.info(`threadId=${appThreadCpuUsage[i].threadId}, cpuUsage=${appThreadCpuUsage[i].cpuUsage}`); 476} 477``` 478 479## hidebug.startAppTraceCapture<sup>12+</sup> 480 481startAppTraceCapture(tags: number[], flag: TraceFlag, limitSize: number) : string 482 483该接口补充了[hitrace](../../dfx/hitrace.md)功能，开发者可通过该接口完成指定范围的trace自动化采集。由于该接口中trace采集过程中消耗的性能与需要采集的范围成正相关，建议开发者在使用该接口前，通过hitrace命令抓取应用的trace日志，从中筛选出所需trace采集的关键范围，以提高该接口性能。 484 485`startAppTraceCapture()`方法的调用需要与`[stopAppTraceCapture()](#hidebugstopapptracecapture12)`方法的调用一一对应，重复开启trace采集将导致接口调用异常，由于trace采集过程中会消耗较多性能，开发者应在完成采集后及时关闭。 486 487应用调用startAppTraceCapture接口启动采集trace，当采集的trace大小超过了limitSize，系统将自动调用stopAppTraceCapture接口停止采集。因此limitSize大小设置不当，将导致生成trace数据不足，无法满足故障分析。所以要求开发者根据实际情况，评估limitSize大小。 488 489评估方法：limitSize = 预期trace采集时长 * trace单位流量。 490 491预期trace采集时长：开发者根据分析的故障场景自行决定，单位秒。 492 493trace单位流量：应用每秒产生的trace大小，系统推荐值为300Kb/s，建议开发者采用自身应用的实测值，单位Kb/s。 494 495trace单位流量实测方法：limitSize设置为最大值500M，调用startAppTraceCapture接口，在应用上操作N秒后，调用stopAppTraceCapture停止采集，然后查看trace大小S（Kb）。那么trace单位流量 = S/N（Kb/s）。 496 497**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 498 499**参数：** 500 501| 参数名 | 类型 | 必填 | 说明 | 502| -------- | ------ | ---- |------------------------------------| 503| tags | number[] | 是 | trace范围，详情请见[tags](#hidebugtags12)。 | 504| flag | TraceFlag| 是 | 详情请见[TraceFlag](#traceflag12)。 | 505| limitSize| number | 是 | 开启trace文件大小限制，单位为Byte，单个文件大小上限为500MB。 | 506 507**返回值：** 508 509| 类型 | 说明 | 510| -----------------|---------------| 511| string | 返回trace文件名路径。 | 512 513**错误码：** 514 515以下错误码的详细介绍请参见[HiDebug错误码](errorcode-hiviewdfx-hidebug.md)。 516 517| 错误码ID | 错误信息 | 518| ------- | ----------------------------------------------------------------- | 519| 401 | Invalid argument, Possible causes:1.The limit parameter is too small 2.The parameter is not within the enumeration type 3.The parameter type error or parameter order error. | 520| 11400102 | Capture trace already enabled. | 521| 11400103 | No write permission on the file. | 522| 11400104 | Abnormal trace status. | 523 524**示例：** 525 526```ts 527import { hidebug } from '@kit.PerformanceAnalysisKit'; 528import { BusinessError } from '@kit.BasicServicesKit'; 529 530let tags: number[] = [hidebug.tags.ABILITY_MANAGER, hidebug.tags.ARKUI]; 531let flag: hidebug.TraceFlag = hidebug.TraceFlag.MAIN_THREAD; 532let limitSize: number = 1024 * 1024; 533 534try { 535 let fileName: string = hidebug.startAppTraceCapture(tags, flag, limitSize); 536 // code block 537 // ... 538 // code block 539 hidebug.stopAppTraceCapture(); 540} catch (error) { 541 console.error(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 542} 543``` 544 545## hidebug.stopAppTraceCapture<sup>12+</sup> 546 547stopAppTraceCapture() : void 548 549停止应用trace采集。调用前，需先调用'[startAppTraceCapture()](#hidebugstartapptracecapture12)'方法开始采集。关闭前未开启或重复关闭会导致接口异常。 550 551调用startAppTraceCapture接口，如果没有合理传入limitSize参数，生成trace的大小大于传入的limitSize大小，系统内部会自动调用stopAppTraceCapture，再次手动调用stopAppTraceCapture就会抛出错误码11400105。 552 553**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 554 555**错误码：** 556 557以下错误码的详细介绍请参见[HiDebug错误码](errorcode-hiviewdfx-hidebug.md)。 558 559| 错误码ID | 错误信息 | 560| ------- | ----------------------------------------------------------------- | 561| 11400104 | The status of the trace is abnormal. | 562| 11400105 | No capture trace running. | 563 564**示例：** 565 566```ts 567import { hidebug } from '@kit.PerformanceAnalysisKit'; 568import { BusinessError } from '@kit.BasicServicesKit'; 569 570let tags: number[] = [hidebug.tags.ABILITY_MANAGER, hidebug.tags.ARKUI]; 571let flag: hidebug.TraceFlag = hidebug.TraceFlag.MAIN_THREAD; 572let limitSize: number = 1024 * 1024; 573try { 574 let fileName: string = hidebug.startAppTraceCapture(tags, flag, limitSize); 575 // code block 576 // ... 577 // code block 578 hidebug.stopAppTraceCapture(); 579} catch (error) { 580 console.error(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 581} 582``` 583 584## hidebug.getAppMemoryLimit<sup>12+</sup> 585 586getAppMemoryLimit() : MemoryLimit 587 588获取应用程序进程的内存限制。 589 590**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 591 592**返回值：** 593 594| 类型 | 说明 | 595| ------ | -------------------------- | 596| [MemoryLimit](#memorylimit12) | 应用程序进程内存限制。 | 597 598**示例** 599 600```ts 601import { hidebug } from '@kit.PerformanceAnalysisKit'; 602 603let appMemoryLimit:hidebug.MemoryLimit = hidebug.getAppMemoryLimit(); 604``` 605 606## hidebug.getSystemCpuUsage<sup>12+</sup> 607 608getSystemCpuUsage() : number 609 610获取系统的CPU资源占用情况。 611 612例如，当系统资源CPU占用为50%时，将返回0.5。 613 614**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 615 616**返回值：** 617 618| 类型 | 说明 | 619|--------|-------------| 620| number | 系统CPU资源占用情况。| 621 622**错误码：** 623 624以下错误码的详细介绍请参见[HiDebug-CpuUsage错误码](errorcode-hiviewdfx-hidebug-cpuusage.md)。 625 626| 错误码ID | 错误信息 | 627| ------- |-------------------------------------------------| 628| 11400104 | The status of the system CPU usage is abnormal. | 629 630**示例** 631```ts 632import { hidebug } from '@kit.PerformanceAnalysisKit'; 633import { BusinessError } from '@kit.BasicServicesKit'; 634 635try { 636 console.info(`getSystemCpuUsage: ${hidebug.getSystemCpuUsage()}`) 637} catch (error) { 638 console.error(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 639} 640``` 641 642## hidebug.setAppResourceLimit<sup>12+</sup> 643 644setAppResourceLimit(type: string, value: number, enableDebugLog: boolean) : void 645 646设置应用的文件描述符数量、线程数量、JS内存或Native内存资源限制。 647 648> **注意：** 649> 650> 当设置的开发者选项开关打开并重启设备后，此功能有效。 651 652**原子化服务API**：从API version 12开始，该接口支持在原子化服务中使用。 653 654**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 655 656**参数：** 657 658| 参数名 | 类型 | 必填 | 说明 | 659| -------- | ------ | ---- | ------------------------------------------------------------ | 660| type | string | 是 | 泄漏资源类型，共四种：<br/>- pss_memory（native内存）<br/>- js_heap（js堆内存）<br/>- fd（文件描述符）<br/>- thread（线程） | 661| value | number | 是 | 对应泄漏资源类型的最大值，范围：<br/>- pss_memory类型：`[1024, 4 * 1024 * 1024]`（单位：KB）<br/>- js_heap类型：`[85, 95]`（分配给JS堆内存上限的85%~95%）<br/>- fd类型：`[10, 10000]`<br/>- thread类型：`[1, 1000]` | 662| enableDebugLog | boolean | 是 | 是否启用外部调试日志，默认值为false。请仅在灰度版本中设置为true，因为收集调试日志会花费太多的cpu或内存。 | 663 664**错误码：** 665 666以下错误码的详细介绍请参见[HiDebug错误码](errorcode-hiviewdfx-hidebug.md)。 667 668| 错误码ID | 错误信息 | 669| ------- | ----------------------------------------------------------------- | 670| 401 | Invalid argument, Possible causes:1.The limit parameter is too small 2.The parameter is not in the specified type 3.The parameter type error or parameter order error. | 671| 11400104 | Set limit failed due to remote exception. | 672 673**示例：** 674 675```ts 676import { hidebug } from '@kit.PerformanceAnalysisKit'; 677import { BusinessError } from '@kit.BasicServicesKit'; 678 679let type: string = 'js_heap'; 680let value: number = 85; 681let enableDebugLog: boolean = false; 682try { 683 hidebug.setAppResourceLimit(type, value, enableDebugLog); 684} catch (error) { 685 console.error(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 686} 687``` 688 689## hidebug.getAppNativeMemInfo<sup>12+</sup> 690 691getAppNativeMemInfo(): NativeMemInfo 692 693获取应用进程内存信息。读取/proc/{pid}/smaps_rollup和/proc/{pid}/statm节点的数据。 694 695**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 696 697> **注意：** 698> 699> 由于/proc/{pid}/smaps_rollup的读取比较耗时，建议不要在主线程中使用该接口，可通过[@ohos.taskpool](../apis-arkts/js-apis-taskpool.md)或[@ohos.worker](../apis-arkts/js-apis-worker.md)开启异步线程以避免应用出现卡顿。 700 701 702**返回值：** 703 704| 类型 | 说明 | 705| ------ | -------------------------- | 706| [NativeMemInfo](#nativememinfo12) | 应用进程内存信息。 | 707 708**示例** 709 710```ts 711import { hidebug } from '@kit.PerformanceAnalysisKit'; 712 713let nativeMemInfo: hidebug.NativeMemInfo = hidebug.getAppNativeMemInfo(); 714console.info(`pss: ${nativeMemInfo.pss}, vss: ${nativeMemInfo.vss}, rss: ${nativeMemInfo.rss}, ` + 715 `sharedDirty: ${nativeMemInfo.sharedDirty}, privateDirty: ${nativeMemInfo.privateDirty}, ` + 716 `sharedClean: ${nativeMemInfo.sharedClean}, privateClean: ${nativeMemInfo.privateClean}`); 717``` 718 719## hidebug.getSystemMemInfo<sup>12+</sup> 720 721getSystemMemInfo(): SystemMemInfo 722 723获取系统内存信息。读取/proc/meminfo节点的数据。 724 725**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 726 727**返回值：** 728 729| 类型 | 说明 | 730| ------ | -------------------------- | 731| [SystemMemInfo](#systemmeminfo12) | 系统内存信息。 | 732 733**示例** 734 735```ts 736import { hidebug } from '@kit.PerformanceAnalysisKit'; 737 738let systemMemInfo: hidebug.SystemMemInfo = hidebug.getSystemMemInfo(); 739 740console.info(`totalMem: ${systemMemInfo.totalMem}, freeMem: ${systemMemInfo.freeMem}, ` + 741 `availableMem: ${systemMemInfo.availableMem}`); 742``` 743 744## hidebug.getVMRuntimeStats<sup>12+</sup> 745 746getVMRuntimeStats(): GcStats 747 748获取系统gc全部统计信息。 749 750**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 751 752**返回值：** 753 754| 类型 | 说明 | 755|-----------------------|----------| 756| [GcStats](#gcstats12) | 系统GC统计信息。 | 757 758**示例** 759 760```ts 761import { hidebug } from '@kit.PerformanceAnalysisKit'; 762 763let vMRuntimeStats: hidebug.GcStats = hidebug.getVMRuntimeStats(); 764console.info(`gc-count: ${vMRuntimeStats['ark.gc.gc-count']}`); 765console.info(`gc-time: ${vMRuntimeStats['ark.gc.gc-time']}`); 766console.info(`gc-bytes-allocated: ${vMRuntimeStats['ark.gc.gc-bytes-allocated']}`); 767console.info(`gc-bytes-freed: ${vMRuntimeStats['ark.gc.gc-bytes-freed']}`); 768console.info(`fullgc-longtime-count: ${vMRuntimeStats['ark.gc.fullgc-longtime-count']}`); 769``` 770 771## hidebug.getVMRuntimeStat<sup>12+</sup> 772 773getVMRuntimeStat(item: string): number 774 775根据参数获取指定的系统gc统计信息。 776 777**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 778 779**参数：** 780 781| 参数名 | 类型 | 必填 | 说明 | 782| -------- | ------ | ---- |-------------| 783| item | string | 是 | 需要获取GC信息的类型。 | 784 785| 输入参数 | 返回值说明 | 786|------------------------------|----------------| 787| ark.gc.gc-count | 当前线程的GC次数。 | 788| ark.gc.gc-time | 当前线程触发的GC总耗时，以ms为单位。 | 789| ark.gc.gc-bytes-allocated | 当前线程Ark虚拟机已分配的内存大小，以B为单位。| 790| ark.gc.gc-bytes-freed | 当前线程GC成功回收的内存，以B为单位。 | 791| ark.gc.fullgc-longtime-count | 当前线程超长fullGC次数。 | 792 793**错误码：** 794 795| 错误码ID | 错误信息 | 796| ------- |------------------------------------------------------------------------------------------------------------| 797| 401 | Possible causes:1. Invalid parameter, a string parameter required. 2. Invalid parameter, unknown property. | 798 799**示例** 800 801```ts 802import { hidebug } from '@kit.PerformanceAnalysisKit'; 803import { BusinessError } from '@kit.BasicServicesKit'; 804 805try { 806 console.info(`gc-count: ${hidebug.getVMRuntimeStat('ark.gc.gc-count')}`); 807 console.info(`gc-time: ${hidebug.getVMRuntimeStat('ark.gc.gc-time')}`); 808 console.info(`gc-bytes-allocated: ${hidebug.getVMRuntimeStat('ark.gc.gc-bytes-allocated')}`); 809 console.info(`gc-bytes-freed: ${hidebug.getVMRuntimeStat('ark.gc.gc-bytes-freed')}`); 810 console.info(`fullgc-longtime-count: ${hidebug.getVMRuntimeStat('ark.gc.fullgc-longtime-count')}`); 811} catch (error) { 812 console.error(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 813} 814``` 815 816## MemoryLimit<sup>12+</sup> 817 818应用进程内存限制。 819 820**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 821 822| 名称 | 类型 | 必填 | 说明 | 823| --------- | ------ | ---- | ------------ | 824| rssLimit | bigint | 是 | 应用进程的驻留集的限制，以KB为单位。 | 825| vssLimit | bigint | 是 | 进程的虚拟内存限制，以KB为单位。 | 826| vmHeapLimit | bigint | 是 | 当前线程的 JS VM 堆大小限制，以KB为单位。 | 827| vmTotalHeapSize | bigint | 是 | 当前进程的 JS 堆内存大小限制，以KB为单位。 | 828 829## VMMemoryInfo<sup>12+</sup> 830 831VM内存信息。 832 833**系统能力**：以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiProfiler.HiDebug 834 835| 名称 | 类型 | 可读 | 可写 | 说明 | 836| -------------------| ------- | ---- | ---- | ---------------------------------- | 837| totalHeap | bigint | 是 | 否 | 表示当前虚拟机的堆总大小，以KB为单位。 | 838| heapUsed | bigint | 是 | 否 | 表示当前虚拟机使用的堆大小，以KB为单位。 | 839| allArraySize | bigint | 是 | 否 | 表示当前虚拟机的所有数组对象大小，以KB为单位。 | 840 841## ThreadCpuUsage<sup>12+</sup> 842 843线程的CPU使用情况。 844 845**系统能力**：以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiProfiler.HiDebug 846 847| 名称 | 类型 | 可读 | 可写 | 说明 | 848| -------------------| ------- | ---- | ---- | ----------------------------------- | 849| threadId | number | 是 | 否 | 线程号。 | 850| cpuUsage | number | 是 | 否 | 线程CPU使用率。 | 851 852## hidebug.tags<sup>12+</sup> 853 854支持trace使用场景的标签，用户可通过[hitrace](../../dfx/hitrace.md)抓取指定标签的trace内容。 855 856> **注意：** 857> 858> 以下标签实际值由系统定义，可能随版本升级而发生改变，为避免升级后出现兼容性问题，在生产中应直接使用标签名称而非标签数值。 859 860**系统能力**：以下各项对应的系统能力均为SystemCapability.HiviewDFX.HiProfiler.HiDebug 861 862| 名称 | 类型 | 只读 | 说明 | 863| -------------------------| ------- |-----|--------------------------------------------| 864| ABILITY_MANAGER | number | 是 | 能力管理标签，hitrace命令行工具对应tagName:ability。 | 865| ARKUI | number | 是 | ArkUI开发框架标签，hitrace命令行工具对应tagName:ace。 | 866| ARK | number | 是 | JSVM虚拟机标签，hitrace命令行工具对应tagName:ark。 | 867| BLUETOOTH | number | 是 | 蓝牙标签，hitrace命令行工具对应tagName:bluetooth。 | 868| COMMON_LIBRARY | number | 是 | 公共库子系统标签，hitrace命令行工具对应tagName:commonlibrary。 | 869| DISTRIBUTED_HARDWARE_DEVICE_MANAGER | number | 是 | 分布式硬件设备管理标签，hitrace命令行工具对应tagName:devicemanager。 | 870| DISTRIBUTED_AUDIO | number | 是 | 分布式音频标签，hitrace命令行工具对应tagName:daudio。 | 871| DISTRIBUTED_CAMERA | number | 是 | 分布式相机标签，hitrace命令行工具对应tagName:dcamera。 | 872| DISTRIBUTED_DATA | number | 是 | 分布式数据管理模块标签，hitrace命令行工具对应tagName:distributeddatamgr。 | 873| DISTRIBUTED_HARDWARE_FRAMEWORK | number | 是 | 分布式硬件框架标签，hitrace命令行工具对应tagName:dhfwk。 | 874| DISTRIBUTED_INPUT | number | 是 | 分布式输入标签，hitrace命令行工具对应tagName:dinput。 | 875| DISTRIBUTED_SCREEN | number | 是 | 分布式屏幕标签，hitrace命令行工具对应tagName:dscreen。 | 876| DISTRIBUTED_SCHEDULER | number | 是 | 分布式调度器标签，hitrace命令行工具对应tagName:dsched。 | 877| FFRT | number | 是 | FFRT任务标签，hitrace命令行工具对应tagName:ffrt。 | 878| FILE_MANAGEMENT | number | 是 | 文件管理系统标签，hitrace命令行工具对应tagName:filemanagement。 | 879| GLOBAL_RESOURCE_MANAGER | number | 是 | 全局资源管理标签，hitrace命令行工具对应tagName:gresource。 | 880| GRAPHICS | number | 是 | 图形模块标签，hitrace命令行工具对应tagName:graphic。 | 881| HDF | number | 是 | HDF子系统标签，hitrace命令行工具对应tagName:hdf。 | 882| MISC | number | 是 | MISC模块标签，hitrace命令行工具对应tagName:misc。 | 883| MULTIMODAL_INPUT | number | 是 | 多模态输入模块标签，hitrace命令行工具对应tagName:multimodalinput。 | 884| NET | number | 是 | 网络标签，hitrace命令行工具对应tagName:net。 | 885| NOTIFICATION | number | 是 | 通知模块标签，hitrace命令行工具对应tagName:notification。 | 886| NWEB | number | 是 | Nweb标签，hitrace命令行工具对应tagName:nweb。 | 887| OHOS | number | 是 | OHOS通用标签，hitrace命令行工具对应tagName:ohos。 | 888| POWER_MANAGER | number | 是 | 电源管理标签，hitrace命令行工具对应tagName:power。 | 889| RPC | number | 是 | RPC标签，hitrace命令行工具对应tagName:rpc。 | 890| SAMGR | number | 是 | 系统能力管理标签，hitrace命令行工具对应tagName:samgr。 | 891| WINDOW_MANAGER | number | 是 | 窗口管理标签，hitrace命令行工具对应tagName:window。 | 892| AUDIO | number | 是 | 音频模块标签，hitrace命令行工具对应tagName:zaudio。 | 893| CAMERA | number | 是 | 相机模块标签，hitrace命令行工具对应tagName:zcamera。 | 894| IMAGE | number | 是 | 图片模块标签，hitrace命令行工具对应tagName:zimage。 | 895| MEDIA | number | 是 | 媒体模块标签，hitrace命令行工具对应tagName:zmedia。 | 896 897## NativeMemInfo<sup>12+</sup> 898 899描述应用进程的内存信息。 900 901**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 902 903| 名称 | 类型 | 必填 | 说明 | 904| --------- | ------ | ---- |--------------------------------------------------------------------------------| 905| pss | bigint | 是 | 实际占用的物理内存大小(比例分配共享库占用的内存)，以KB为单位，计算方式：/proc/{pid}/smaps_rollup: Pss + SwapPss。 | 906| vss | bigint | 是 | 占用的虚拟内存大小(包括共享库所占用的内存)，以KB为单位，计算方式：/proc/{pid}/statm: size * 4。 | 907| rss | bigint | 是 | 实际占用的物理内存大小(包括共享库占用)，以KB为单位，计算方式：/proc/{pid}/smaps_rollup: Rss。 | 908| sharedDirty | bigint | 是 | 共享脏内存大小，以KB为单位，计算方式：/proc/{pid}/smaps_rollup: Shared_Dirty。 | 909| privateDirty | bigint | 是 | 私有脏内存大小，以KB为单位，计算方式：/proc/{pid}/smaps_rollup: Private_Dirty。 | 910| sharedClean | bigint | 是 | 共享净内存大小，以KB为单位，计算方式：/proc/{pid}/smaps_rollup: Shared_Clean。 | 911| privateClean | bigint | 是 | 私有干净内存大小，以KB为单位，计算方式：/proc/{pid}/smaps_rollup: Private_Clean。 | 912 913## SystemMemInfo<sup>12+</sup> 914 915描述系统内存信息，包括总内存、空闲内存和可用内存。 916 917**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 918 919| 名称 | 类型 | 必填 | 说明 | 920| --------- | ------ | ---- |-------------------------------------------------| 921| totalMem | bigint | 是 | 系统总的内存，以KB为单位，计算方式：/proc/meminfo: MemTotal | 922| freeMem | bigint | 是 | 系统空闲的内存，以KB为单位，计算方式：/proc/meminfo: MemFree | 923| availableMem | bigint | 是 | 系统可用的内存，以KB为单位，计算方式：/proc/meminfo: MemAvailable | 924 925## TraceFlag<sup>12+</sup> 926 927描述采集trace线程的类型，包括主线程和所有线程。 928 929**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 930 931| 名称 | 值 | 说明 | 932| --------------------------- |---| ----------------------- | 933| MAIN_THREAD | 1 | 只采集当前应用主线程。| 934| ALL_THREADS | 2 | 采集当前应用下所有线程。 | 935 936## GcStats<sup>12+</sup> 937 938type GcStats = Record<string, number> 939 940描述用于存储GC统计信息的键值对。该类型不支持多线程操作，如果应用中存在多线程同时访问，需加锁保护。 941 942**系统能力**： SystemCapability.HiviewDFX.HiProfiler.HiDebug 943 944| 类型 | 说明 | 945| -----------| ---------------------------- | 946| Record<string, number> | 用于存储GC统计信息的键值对。 | 947 948GcStats包含以下键值信息： 949 950| 参数名 | 类型 | 说明 | 951|-------------------------| ------ |------------------------- | 952| ark.gc.gc-count | number | 当前线程的GC次数。| 953| ark.gc.gc-time | number | 当前线程触发的GC总耗时，以ms为单位。 | 954| ark.gc.gc-bytes-allocated | number | 当前线程Ark虚拟机已分配的内存大小，以B为单位。 | 955| ark.gc.gc-bytes-freed | number | 当前线程GC成功回收的内存，以B为单位。| 956| ark.gc.fullgc-longtime-count | number | 当前线程超长fullGC次数。 | 957 958## hidebug.isDebugState<sup>12+</sup> 959 960isDebugState(): boolean 961 962获取应用进程的调试状态。如果应用进程的Ark层或Native层处于调试状态，则返回true；否则返回false。 963 964**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 965 966**返回值：** 967 968| 类型 | 说明 | 969| ------ | -------------------------- | 970| boolean | 应用进程的调试状态。 | 971 972**示例** 973 974```ts 975import { hidebug } from '@kit.PerformanceAnalysisKit'; 976 977console.info(`isDebugState = ${hidebug.isDebugState()}`) 978``` 979 980## hidebug.getGraphicsMemory<sup>14+</sup> 981 982getGraphicsMemory(): Promise<number> 983 984使用异步方式获取应用显存大小。 985 986**原子化服务API**：从API version 14开始，该接口支持在原子化服务中使用。 987 988**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 989 990**返回值：** 991 992| 类型 | 说明 | 993|-----------------------|------------------------------| 994| Promise<number> | promise对象，调用结束后返回应用显存大小，单位为KB。 | 995 996**错误码：** 997 998| 错误码ID | 错误信息 | 999| ------- | ----------------------------------------------------------------- | 1000| 11400104 | Failed to get the application memory due to a remote exception. | 1001 1002**示例** 1003 1004```ts 1005import { hidebug, hilog } from '@kit.PerformanceAnalysisKit'; 1006import { BusinessError } from '@kit.BasicServicesKit'; 1007 1008hidebug.getGraphicsMemory().then((ret: number) => { 1009 console.info(`graphicsMemory: ${ret}`) 1010}).catch((error: BusinessError) => { 1011 console.error(`error code: ${error.code}, error msg: ${error.message}`); 1012}) 1013``` 1014 1015## hidebug.getGraphicsMemorySync<sup>14+</sup> 1016 1017getGraphicsMemorySync(): number 1018 1019使用同步方式获取应用显存大小。 1020 1021> **注意：** 1022> 1023> 该接口涉及多次跨进程通信，可能存在性能问题，推荐使用异步接口`getGraphicsMemory`。 1024 1025**原子化服务API**：从API version 14开始，该接口支持在原子化服务中使用。 1026 1027**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 1028 1029**返回值：** 1030 1031| 类型 | 说明 | 1032| ------ |----------------| 1033| number | 应用显存大小，单位为KB。 | 1034 1035**错误码：** 1036 1037| 错误码ID | 错误信息 | 1038| ------- | ----------------------------------------------------------------- | 1039| 11400104 | Failed to get the application memory due to a remote exception. | 1040 1041**示例** 1042 1043```ts 1044import { hidebug } from '@kit.PerformanceAnalysisKit'; 1045import { BusinessError } from '@kit.BasicServicesKit'; 1046 1047try { 1048 console.info(`graphicsMemory: ${hidebug.getGraphicsMemorySync()}`) 1049} catch (error) { 1050 console.error(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 1051} 1052``` 1053 1054## hidebug.dumpJsRawHeapData<sup>18+</sup> 1055 1056dumpJsRawHeapData(needGC?: boolean): Promise<string> 1057 1058为当前线程转储虚拟机的原始堆快照，生成的rawheap文件路径将使用Promise进行异步回调。所生成的文件可通过[rawheap-translator工具](../../tools/rawheap-translator.md)将所生成文件转化为heapsnapshot文件进行解析。 1059 1060> **注意：** 1061> 1062> 系统通过该接口转存快照会消耗大量资源，因此严格限制了调用频率和次数。处理完生成的文件后，请立即删除。 1063> 建议仅在应用的灰度测试版本中使用。在正式版本中不推荐使用，避免影响应用流畅性。 1064 1065**原子化服务API**：从API version 18开始，该接口支持在原子化服务中使用。 1066 1067**系统能力**：SystemCapability.HiviewDFX.HiProfiler.HiDebug 1068 1069| 参数名 | 类型 | 必填 | 说明 | 1070|-------------------------|---------|----|------------------------------------------| 1071| needGC | boolean | 否 | 转储堆快照时是否需要GC。默认为true。未填写时，转储前将触发GC。 | 1072 1073**返回值：** 1074 1075| 类型 | 说明 | 1076| ------ |------------------------------------------------------------------------------------------------------| 1077| Promise<string> | Promise对象，返回生成的快照文件路径（[应用沙箱内路径](../../file-management/app-sandbox-directory.md#应用沙箱路径和真实物理路径的对应关系)）。 | 1078 1079**错误码：** 1080 1081以下错误码的详细介绍请参见[HiDebug错误码](errorcode-hiviewdfx-hidebug.md)。 1082 1083| 错误码ID | 错误信息 | 1084|----------| ----------------------------------------------------------------- | 1085| 11400106 | Quota exceeded. | 1086| 11400107 | Fork operation failed. | 1087| 11400108 | Failed to wait for the child process to finish. | 1088| 11400109 | Timeout while waiting for the child process to finish. | 1089| 11400110 | Disk remaining space too low. | 1090| 11400111 | Napi interface call exception. | 1091| 11400112 | Repeated data dump. | 1092| 11400113 | Failed to create dump file. | 1093 1094**示例** 1095 1096```ts 1097import { hidebug } from '@kit.PerformanceAnalysisKit'; 1098import { BusinessError } from '@kit.BasicServicesKit'; 1099hidebug.dumpJsRawHeapData().then((filePath: string) => { 1100 console.info(`dumpJsRawHeapData success and generated file path is ${filePath}`) 1101}).catch((error: BusinessError) => { 1102 console.error(`error code: ${error.code}, error msg: ${error.message}`); 1103}) 1104```