1# @ohos.hiviewdfx.jsLeakWatcher (JS Leak Detection) 2 3<!--Kit: Performance Analysis Kit--> 4<!--Subsystem: HiviewDFX--> 5<!--Owner: @lu-tao--> 6<!--SE: @martin-duan--> 7<!--TSE: @gcw_KuLfPSbe--> 8 9This module provides the capability of monitoring whether JS objects are leaked. 10 11> **NOTE** 12> 13> The initial APIs of this module are supported since API version 12. Newly added APIs will be marked with a superscript to indicate their earliest API version. 14 15## Modules to Import 16 17```js 18import { jsLeakWatcher } from '@kit.PerformanceAnalysisKit'; 19``` 20 21 22## jsLeakWatcher.enable 23 24enable(isEnable: boolean): void 25 26Enables the detection for JS object leaks. This function is disabled by default. 27 28**System capability**: SystemCapability.HiviewDFX.HiChecker 29 30**Parameters** 31 32| Name| Type| Mandatory| Description| 33| -------- | -------- | -------- | -------- | 34| isEnable | boolean | Yes| Whether to enable **jsLeakWatcher**. The value **true** means to enable jsleakwatcher, and **false** means the opposite.| 35 36**Example** 37 38```js 39jsLeakWatcher.enable(true); 40``` 41 42 43## jsLeakWatcher.watch 44 45watch(obj: object, msg: string): void 46 47Registers the object to be checked. 48 49**System capability**: SystemCapability.HiviewDFX.HiChecker 50 51**Parameters** 52 53| Name| Type| Mandatory| Description| 54| -------- | -------- | -------- | -------- | 55| obj | object | Yes| Name of the object to be checked.| 56| msg | string | Yes| Custom object information.| 57 58**Example** 59 60```js 61let obj:Object = new Object(); 62jsLeakWatcher.watch(obj, "Trace Object"); 63``` 64 65 66## jsLeakWatcher.check 67 68check(): string 69 70Obtains the list of objects that are registered using **jsLeakWatcher.watch()** and may leak. Objects that are not reclaimed after GC is triggered are marked as leaked. 71 72**System capability**: SystemCapability.HiviewDFX.HiChecker 73 74**Return value** 75 76| Type | Description | 77| ------- | ---------------------------------------------------------- | 78| string | List of objects that are suspected to leak, in JSON format.| 79 80**Example** 81```js 82let leakObjlist:string = jsLeakWatcher.check(); 83``` 84 85 86## jsLeakWatcher.dump 87 88dump(filePath: string): Array<string> 89 90Exports the list of leaked objects and VM memory snapshot. 91 92**System capability**: SystemCapability.HiviewDFX.HiChecker 93 94**Parameters** 95 96| Name| Type| Mandatory| Description| 97| -------- | -------- | -------- | -------- | 98| filePath | string | Yes| The path for storing exported information files.| 99 100**Return value** 101 102| Type | Description | 103| ------- | ---------------------------------------------------------- | 104| Array<string> | Array of exported results. Index **0** indicates the name of the leak list file, whose name extension is **.jsleaklist**. Index **1** indicates the name of the VM memory snapshot file, whose name extension is **.heapsnapshort**.| 105 106**Error codes** 107 108For details about the error codes, see [Universal Error Codes](../errorcode-universal.md). 109 110| ID| Error Message| 111| ------- | ----------------------------------------------------------------- | 112| 401 | Parameter error. The filepath is invalid. | 113 114**Example** 115 116```js 117let context = this.getUIContext().getHostContext(); 118let files: Array<string> = jsLeakWatcher.dump(context?.filesDir); 119``` 120 121 122## jsLeakWatcher.enableLeakWatcher<sup>20+</sup> 123 124enableLeakWatcher(isEnabled: boolean, configs: Array<string>, callback: Callback<Array<string>>): void 125 126Enables the detection for JS object leaks. This function is disabled by default. 127 128This API can detect the JS object memory leak, which is simpler than the method that needs to call the **enable**, **watch**, **check**, and **dump** functions. 129 130If a memory leak occurs, the leaked file is returned through the callback. 131 132 133**System capability**: SystemCapability.HiviewDFX.HiChecker 134 135**Parameters** 136 137| Name| Type| Mandatory| Description| 138| -------- | -------- | -------- | -------- | 139| isEnabled | boolean | Yes| Whether to enable the detection for JS object memory leaks. The value **true** means to enable the detection for JS object memory leaks, and **false** means the opposite.| 140| configs | array<string> | Yes| Configuration item. Each element in the array indicates a specific monitored object type.<br>Configurable items: **XComponent**, **NodeContainer**, **Window**, Custom Component, and **Ability**.| 141| callback | Callback<Array<string>> | Yes| Callback used to receive the memory-leaked object returned by the **jsLeakWatcher.enableLeakWatcher** API.<br>You need to input an array object in the callback. Index 0 is the name of the leak list file, whose suffix is **.jsleaklist**. Index 1 is the name of the VM memory snapshot file, whose suffix is **.heapsnapshort**.| 142 143 144**Error codes** 145 146For details, see [JsLeakWatcher Error Codes](./errorcode-jsleakwatcher.md). 147 148| ID| Error Message| 149| ------- | ----------------------------------------------------------------- | 150| 10801001 | The parameter isEnabled is invalid. | 151| 10801002 | The parameter config is invalid. | 152| 10801003 | The parameter callback is invalid. Input parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3.Parameter verification failed. | 153 154**Example** 155 156<!--code_no_check--> 157```ts 158let config: Array<string> = ['XComponent']; 159// Monitor the memory leak of the JS object XComponent. 160jsLeakWatcher.enableLeakWatcher(true, config, (filePath: Array<string>) => { 161 console.info('JsLeakWatcher leaklistFileName:' + filePath[0]); 162 console.info('JsLeakWatcher heapDumpFileName:' + filePath[1]); 163}); 164``` 165