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.getVss<sup>11+<sup> 94 95getVss(): bigint 96 97Obtains the virtual set size used by the application process. 98 99**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 100 101**Return value** 102 103| Type | Description | 104| ------ | ---------------------------------------- | 105| bigint | Virtual set size used by the application process, in KB.| 106 107**Example** 108 109 ```ts 110let vss: bigint = hidebug.getVss(); 111 ``` 112 113## hidebug.getSharedDirty 114 115getSharedDirty(): bigint 116 117Obtains the size of the shared 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 shared dirty memory of the process, in KB.| 126 127 128**Example** 129 ```ts 130 let sharedDirty: bigint = hidebug.getSharedDirty(); 131 ``` 132 133## hidebug.getPrivateDirty<sup>9+<sup> 134 135getPrivateDirty(): bigint 136 137Obtains the size of the private dirty memory of a process. 138 139**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 140 141**Return value** 142 143| Type | Description | 144| ------ | -------------------------- | 145| bigint | Size of the private dirty memory of the process, in KB.| 146 147**Example** 148 ```ts 149 let privateDirty: bigint = hidebug.getPrivateDirty(); 150 ``` 151 152## hidebug.getCpuUsage<sup>9+<sup> 153 154getCpuUsage(): number 155 156Obtains the CPU usage of a process. 157 158For example, if the CPU usage is **50%**, **0.5** is returned. 159 160**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 161 162**Return value** 163 164| Type | Description | 165| ------ | -------------------------- | 166| number | CPU usage of the process.| 167 168 169**Example** 170 ```ts 171 let cpuUsage: number = hidebug.getCpuUsage(); 172 ``` 173 174## hidebug.getServiceDump<sup>9+<sup> 175 176getServiceDump(serviceid : number, fd : number, args : Array\<string>) : void 177 178Obtains system service information. 179 180**Required permissions**: ohos.permission.DUMP 181 182**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 183 184**Parameters** 185 186| Name | Type | Mandatory| Description | 187| -------- | ------ | ---- | ------------------------------------------------------------ | 188| serviceid | number | Yes | Obtains the system service information based on the specified service ID.| 189| fd | number | Yes | File descriptor to which data is written by the API.| 190| args | Array\<string> | Yes | Parameter list corresponding to the **Dump** API of the system service.| 191 192**Error codes** 193 194For details about the error codes, see [HiDebug Error Codes](../errorcodes/errorcode-hiviewdfx-hidebug.md). 195 196| ID| Error Message| 197| ------- | ----------------------------------------------------------------- | 198| 11400101 | the service id is invalid | 199| 401 | the parameter check failed | 200 201**Example** 202 203```ts 204import UIAbility from '@ohos.app.ability.UIAbility'; 205import fs from '@ohos.file.fs'; 206import hidebug from '@ohos.hidebug'; 207import common from '@ohos.app.ability.common'; 208import { BusinessError } from '@ohos.base'; 209 210export default class HidebugTest extends UIAbility { 211 public testfunc() { 212 let applicationContext: common.Context | null = null; 213 try { 214 applicationContext = this.context.getApplicationContext(); 215 } catch (error) { 216 console.info(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 217 } 218 219 let filesDir: string = applicationContext!.filesDir; 220 let path: string = filesDir + "/serviceInfo.txt"; 221 console.info("output path: " + path); 222 let file = fs.openSync(path, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE); 223 let serviceId: number = 10; 224 let args: Array<string> = new Array("allInfo"); 225 226 try { 227 hidebug.getServiceDump(serviceId, file.fd, args); 228 } catch (error) { 229 console.info(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 230 } 231 fs.closeSync(file); 232 } 233} 234 235let t = new HidebugTest(); 236t.testfunc(); 237``` 238 239## hidebug.startJsCpuProfiling<sup>9+</sup> 240 241startJsCpuProfiling(filename : string) : void 242 243Starts 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`. 244 245**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 246 247**Parameters** 248 249| Name | Type | Mandatory| Description | 250| -------- | ------ | ---- | ------------------------------------------------------------ | 251| 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`.| 252 253**Error codes** 254 255For details about the error codes, see [Universal Error Codes](../errorcodes/errorcode-universal.md). 256 257| ID| Error Message| 258| ------- | ----------------------------------------------------------------- | 259| 401 | the parameter check failed | 260 261**Example** 262 263```ts 264import hidebug from '@ohos.hidebug'; 265import { BusinessError } from '@ohos.base'; 266 267try { 268 hidebug.startJsCpuProfiling("cpu_profiling"); 269 // ... 270 hidebug.stopJsCpuProfiling(); 271} catch (error) { 272 console.info(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 273} 274``` 275 276## hidebug.stopJsCpuProfiling<sup>9+</sup> 277 278stopJsCpuProfiling() : void 279 280Stops 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`. 281 282**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 283 284**Parameters** 285 286| Name | Type | Mandatory| Description | 287| -------- | ------ | ---- | ------------------------------------------------------------ | 288| 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`.| 289 290**Example** 291 292```ts 293import hidebug from '@ohos.hidebug'; 294import { BusinessError } from '@ohos.base'; 295 296try { 297 hidebug.startJsCpuProfiling("cpu_profiling"); 298 // ... 299 hidebug.stopJsCpuProfiling(); 300} catch (error) { 301 console.info(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 302} 303``` 304 305## hidebug.dumpJsHeapData<sup>9+</sup> 306 307dumpJsHeapData(filename : string) : void 308 309Exports the heap data. 310 311**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 312 313**Parameters** 314 315| Name | Type | Mandatory| Description | 316| -------- | ------ | ---- | ------------------------------------------------------------ | 317| 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`.| 318 319**Error codes** 320 321For details about the error codes, see [Universal Error Codes](../errorcodes/errorcode-universal.md). 322 323| ID| Error Message| 324| ------- | ----------------------------------------------------------------- | 325| 401 | the parameter check failed | 326 327**Example** 328 329```ts 330import hidebug from '@ohos.hidebug'; 331import { BusinessError } from '@ohos.base'; 332 333try { 334 hidebug.dumpJsHeapData("heapData"); 335} catch (error) { 336 console.info(`error code: ${(error as BusinessError).code}, error msg: ${(error as BusinessError).message}`); 337} 338``` 339 340## hidebug.startProfiling<sup>(deprecated)</sup> 341 342startProfiling(filename : string) : void 343 344> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [hidebug.startJsCpuProfiling](#hidebugstartjscpuprofiling9). 345 346Starts 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`. 347 348**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 349 350**Parameters** 351 352| Name | Type | Mandatory| Description | 353| -------- | ------ | ---- | ------------------------------------------------------------ | 354| 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`.| 355 356**Example** 357 358```ts 359hidebug.startProfiling("cpuprofiler-20220216"); 360// code block 361// ... 362// code block 363hidebug.stopProfiling(); 364``` 365 366## hidebug.stopProfiling<sup>(deprecated)</sup> 367 368stopProfiling() : void 369 370> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [hidebug.stopJsCpuProfiling](#hidebugstopjscpuprofiling9). 371 372Stops 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`. 373 374**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 375 376**Example** 377 378```ts 379hidebug.startProfiling("cpuprofiler-20220216"); 380// code block 381// ... 382// code block 383hidebug.stopProfiling(); 384``` 385 386## hidebug.dumpHeapData<sup>(deprecated)</sup> 387 388dumpHeapData(filename : string) : void 389 390> **NOTE**<br>This API is deprecated since API version 9. You are advised to use [hidebug.dumpJsHeapData](#hidebugdumpjsheapdata9). 391 392Exports the heap data. 393 394**System capability**: SystemCapability.HiviewDFX.HiProfiler.HiDebug 395 396**Parameters** 397 398| Name | Type | Mandatory| Description | 399| -------- | ------ | ---- | ------------------------------------------------------------ | 400| 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`.| 401 402**Example** 403 404```ts 405hidebug.dumpHeapData("heap-20220216"); 406``` 407