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