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