1# @ohos.hidebug (HiDebug) 2 3> **NOTE** 4> 5> The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version. 6 7The **hidebug** module provides APIs for you to obtain the memory usage of an application, including the static heap memory (native heap) and proportional set size (PSS) occupied by the application process. You can also export VM memory slices and collect VM CPU profiling data. 8 9## Modules to Import 10 11```ts 12import hidebug from '@ohos.hidebug'; 13``` 14 15 16## hidebug.getNativeHeapSize 17 18getNativeHeapSize(): bigint 19 20Obtains the total heap memory size of this application. 21 22**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 23 24**Return value** 25 26| Type | Description | 27| ------ | --------------------------- | 28| bigint | Total heap memory size of the application, in bytes.| 29 30**Example** 31 ```ts 32 let nativeHeapSize: bigint = hidebug.getNativeHeapSize(); 33 ``` 34 35## hidebug.getNativeHeapAllocatedSize 36 37getNativeHeapAllocatedSize(): bigint 38 39Obtains the allocated heap memory size of this application. 40 41**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 42 43**Return value** 44 45| Type | Description | 46| ------ | --------------------------------- | 47| bigint | Allocated heap memory of the application, in bytes.| 48 49 50**Example** 51 ```ts 52 let nativeHeapAllocatedSize: bigint = hidebug.getNativeHeapAllocatedSize(); 53 ``` 54 55## hidebug.getNativeHeapFreeSize 56 57getNativeHeapFreeSize(): bigint 58 59Obtains the free heap memory size of this application. 60 61**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 62 63**Return value** 64 65| Type | Description | 66| ------ | ------------------------------- | 67| bigint | Free heap memory size of the application, in bytes.| 68 69**Example** 70 ```ts 71 let nativeHeapFreeSize: bigint = hidebug.getNativeHeapFreeSize(); 72 ``` 73 74## hidebug.getPss 75 76getPss(): bigint 77 78Obtains the size of the physical memory actually used by the application process. 79 80**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 81 82**Return value** 83 84| Type | Description | 85| ------ | ------------------------- | 86| bigint | Size of the physical memory actually used by the application process, in KB.| 87 88**Example** 89 ```ts 90 let pss: bigint = hidebug.getPss(); 91 ``` 92 93## hidebug.getSharedDirty 94 95getSharedDirty(): bigint 96 97Obtains the size of the shared dirty memory of a process. 98 99**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 100 101**Return value** 102 103| Type | Description | 104| ------ | -------------------------- | 105| bigint | Size of the shared dirty memory of the process, in KB.| 106 107 108**Example** 109 ```ts 110 let sharedDirty: bigint = hidebug.getSharedDirty(); 111 ``` 112 113## hidebug.getPrivateDirty<sup>9+<sup> 114 115getPrivateDirty(): bigint 116 117Obtains the size of the private dirty memory of a process. 118 119**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 120 121**Return value** 122 123| Type | Description | 124| ------ | -------------------------- | 125| bigint | Size of the private dirty memory of the process, in KB.| 126 127**Example** 128 ```ts 129 let privateDirty: bigint = hidebug.getPrivateDirty(); 130 ``` 131 132## hidebug.getCpuUsage<sup>9+<sup> 133 134getCpuUsage(): number 135 136Obtains the CPU usage of a process. 137 138For example, if the CPU usage is **50%**, **0.5** is returned. 139 140**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 141 142**Return value** 143 144| Type | Description | 145| ------ | -------------------------- | 146| number | CPU usage of the process.| 147 148 149**Example** 150 ```ts 151 let cpuUsage: number = hidebug.getCpuUsage(); 152 ``` 153 154## hidebug.getServiceDump<sup>9+<sup> 155 156getServiceDump(serviceid : number, fd : number, args : Array\<string>) : void 157 158Obtains system service information. 159 160**Required permissions**: ohos.permission.DUMP 161 162**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 163 164**Parameters** 165 166| Name | Type | Mandatory| Description | 167| -------- | ------ | ---- | ------------------------------------------------------------ | 168| serviceid | number | Yes | Obtains the system service information based on the specified service ID.| 169| fd | number | Yes | File descriptor to which data is written by the API.| 170| args | Array\<string> | Yes | Parameter list corresponding to the **Dump** API of the system service.| 171 172**Error codes** 173 174For details about the error codes, see [HiSysEvent Error Codes](../errorcodes/errorcode-hiviewdfx-hidebug.md). 175 176| ID| Error Message| 177| ------- | ----------------------------------------------------------------- | 178| 11400101 | the service id is invalid | 179| 401 | the parameter check failed | 180 181**Example** 182 183```ts 184import fs from '@ohos.file.fs' 185import hidebug from '@ohos.hidebug' 186import common from '@ohos.app.ability.common' 187import { BusinessError } from '@ohos.base' 188 189let applicationContext: common.Context | null = null; 190try { 191 applicationContext = this.context.getApplicationContext(); 192} catch (error) { 193 console.info(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 194} 195 196let filesDir: string = applicationContext!.filesDir; 197let path: string = filesDir + "/serviceInfo.txt"; 198console.info("output path: " + path); 199let file = fs.openSync(path, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); 200let serviceId: number = 10; 201let args: Array<string> = new Array("allInfo"); 202 203try { 204 hidebug.getServiceDump(serviceId, file.fd, args); 205} catch (error) { 206 console.info(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 207} 208fs.closeSync(file); 209``` 210 211## hidebug.startJsCpuProfiling<sup>9+</sup> 212 213startJsCpuProfiling(filename : string) : void 214 215Starts the profiling method. `startJsCpuProfiling()` and `stopJsCpuProfiling()` are called in pairs. `startJsCpuProfiling()` always occurs before `stopJsCpuProfiling()`; that is, calling the functions in the sequence similar to the following is prohibited: `start->start->stop`, `start->stop->stop`, and `start->start->stop->stop`. 216 217**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 218 219**Parameters** 220 221| Name | Type | Mandatory| Description | 222| -------- | ------ | ---- | ------------------------------------------------------------ | 223| filename | string | Yes | User-defined profile name. The `filename.json` file is generated in the `files` directory of the application based on the specified `filename`.| 224 225**Error codes** 226 227For details about the error codes, see [HiSysEvent Error Codes](../errorcodes/errorcode-universal.md). 228 229| ID| Error Message| 230| ------- | ----------------------------------------------------------------- | 231| 401 | the parameter check failed | 232 233**Example** 234 235```ts 236import hidebug from '@ohos.hidebug' 237import { BusinessError } from '@ohos.base' 238 239try { 240 hidebug.startJsCpuProfiling("cpu_profiling"); 241 // ... 242 hidebug.stopJsCpuProfiling(); 243} catch (error) { 244 console.info(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 245} 246``` 247 248## hidebug.stopJsCpuProfiling<sup>9+</sup> 249 250stopJsCpuProfiling() : void 251 252Stops the profiling method. `startJsCpuProfiling()` and `stopJsCpuProfiling()` are called in pairs. `startJsCpuProfiling()` always occurs before `stopJsCpuProfiling()`; that is, calling the functions in the sequence similar to the following is prohibited: `start->start->stop`, `start->stop->stop`, and `start->start->stop->stop`. 253 254**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 255 256**Parameters** 257 258| Name | Type | Mandatory| Description | 259| -------- | ------ | ---- | ------------------------------------------------------------ | 260| filename | string | Yes | User-defined profile name. The `filename.json` file is generated in the `files` directory of the application based on the specified `filename`.| 261 262**Example** 263 264```ts 265import hidebug from '@ohos.hidebug' 266import { BusinessError } from '@ohos.base' 267 268try { 269 hidebug.startJsCpuProfiling("cpu_profiling"); 270 // ... 271 hidebug.stopJsCpuProfiling(); 272} catch (error) { 273 console.info(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 274} 275``` 276 277## hidebug.dumpJsHeapData<sup>9+</sup> 278 279dumpJsHeapData(filename : string) : void 280 281Exports the heap data. 282 283**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 284 285**Parameters** 286 287| Name | Type | Mandatory| Description | 288| -------- | ------ | ---- | ------------------------------------------------------------ | 289| filename | string | Yes | User-defined heap file name. The `filename.heapsnapshot` file is generated in the `files` directory of the application based on the specified `filename`.| 290 291**Error codes** 292 293For details about the error codes, see [HiSysEvent Error Codes](../errorcodes/errorcode-universal.md). 294 295| ID| Error Message| 296| ------- | ----------------------------------------------------------------- | 297| 401 | the parameter check failed | 298 299**Example** 300 301```ts 302import hidebug from '@ohos.hidebug' 303import { BusinessError } from '@ohos.base' 304 305try { 306 hidebug.dumpJsHeapData("heapData"); 307} catch (error) { 308 console.info(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 309} 310``` 311 312## hidebug.startProfiling<sup>(deprecated)</sup> 313 314startProfiling(filename : string) : void 315 316> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [hidebug.startJsCpuProfiling](#hidebugstartjscpuprofiling9). 317 318Starts the profiling method. `startProfiling()` and `stopProfiling()` are called in pairs. `startProfiling()` always occurs before `stopProfiling()`; that is, calling the functions in the sequence similar to the following is prohibited: `start->start->stop`, `start->stop->stop`, and `start->start->stop->stop`. 319 320**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 321 322**Parameters** 323 324| Name | Type | Mandatory| Description | 325| -------- | ------ | ---- | ------------------------------------------------------------ | 326| filename | string | Yes | User-defined profile name. The `filename.json` file is generated in the `files` directory of the application based on the specified `filename`.| 327 328**Example** 329 330```ts 331hidebug.startProfiling("cpuprofiler-20220216"); 332// code block 333// ... 334// code block 335hidebug.stopProfiling(); 336``` 337 338## hidebug.stopProfiling<sup>(deprecated)</sup> 339 340stopProfiling() : void 341 342> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [hidebug.stopJsCpuProfiling](#hidebugstopjscpuprofiling9). 343 344Stops the profiling method. `startProfiling()` and `stopProfiling()` are called in pairs. `startProfiling()` always occurs before `stopProfiling()`; that is, calling the functions in the sequence similar to the following is prohibited: `start->start->stop`, `start->stop->stop`, and `start->start->stop->stop`. 345 346**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 347 348**Example** 349 350```ts 351hidebug.startProfiling("cpuprofiler-20220216"); 352// code block 353// ... 354// code block 355hidebug.stopProfiling(); 356``` 357 358## hidebug.dumpHeapData<sup>(deprecated)</sup> 359 360dumpHeapData(filename : string) : void 361 362> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [hidebug.dumpJsHeapData](#hidebugdumpjsheapdata9). 363 364Exports the heap data. 365 366**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 367 368**Parameters** 369 370| Name | Type | Mandatory| Description | 371| -------- | ------ | ---- | ------------------------------------------------------------ | 372| filename | string | Yes | User-defined heap file name. The `filename.heapsnapshot` file is generated in the `files` directory of the application based on the specified `filename`.| 373 374**Example** 375 376```ts 377hidebug.dumpHeapData("heap-20220216"); 378``` 379