Make heapdump a manual dependency
ADD
docs/en/advanced-concepts/memory-collection.md
+## Memory Collection
+
+It is possible to collect the dumps of Appium's memory usage to be analyzed for
+problems. This is _extrememly_ useful for finding memory leaks.
+
+
+### Enabling
+
+The feature is enabled by starting Appium with the `--enable-heapdump`
+[server argument](../writing-running-appium/server-args.md)
+```
+appium --enable-heapdump
+```
+
+### Creating a dump file
+
+To create a dump file at any given time, execute the command
+```
+kill -SIGUSR2 &lt;PID&gt;
+```
+
+Dump files are created in the same folder as the main Appium script was executed.
+They will have the `.heapsnapshot` extension, and can be loaded into the Chrome
+Inspector for further investigation.
+
+### Dump file analysis
+
+Read the [Rising Stack article](https://blog.risingstack.com/finding-a-memory-leak-in-node-js/) for more details.
+
+### Installation
+
+For this feature to work, the [heapdump](https://www.npmjs.com/package/heapdump)
+package must be installed and available to the Appium. This can be done either by
+installing `heapdump` in the Appium directory
+```
+cd <location of appium installation>
+npm install heapdump
+```
+Alternatively, since `heapdump` is built on install, it may be helpful to install
+it once and then link it to the Appium installation
+```
+npm install -g heapdump
+cd <location of appium installation>
+npm link heapdump
+```
+
+**Note:** The installation of `heapdump` requires Python 2. If you do not have
+Python installed, make sure you install Python 2, not 3. If you have Python 3
+installed, install Python 2 (see [stack overflow](https://stackoverflow.com/a/2547577)
+for information on having multiple Python versions installed on the same
+machine).

MODIFY
docs/en/writing-running-appium/server-args.md
docs/en/writing-running-appium/server-args.md
@@ -92,5 +92,5 @@ All flags are optional, but some are required in conjunction with certain others
|`--keep-keychains`|false|[DEPRECATED] - (iOS-only) Whether to keep keychains (Library/Keychains) when reset app between sessions||
|`--localizable-strings-dir`|en.lproj|[DEPRECATED] - (IOS-only) the relative path of the dir where Localizable.strings file resides |`--localizable-strings-dir en.lproj`|
|`--show-ios-log`|false|[DEPRECATED] - (IOS-only) if set, the iOS system log will be written to the console||
-|`--enable-heapdump`|false|Enables NodeJS memory dumps collection feature. This feature is extremely useful for finding memory leaks. Use the 'kill -SIGUSR2 &lt;PID&gt;' command to create a dump of memory heap for _node_ process with the particular PID (this works for *nix systems only). The dump file will be created in the same folder, where main Appium script was executed and will have *.heapsnapshot extension. These snapshot can be then loaded to Chrome Inspector for further investigation. Read the [Rising Stack article](https://blog.risingstack.com/finding-a-memory-leak-in-node-js/) for more details.||
+|`--enable-heapdump`|false|Enables NodeJS memory dumps collection feature. This feature is extremely useful for finding memory leaks. See [memory collection docs](../advanced-concepts/memory-collection.md) for more information.||
|`--relaxed-security`|false|Disable additional security checks, so it is possible to use some advanced features, provided by drivers supporting this option. Only enable it if all the clients are in the trusted network and it is not the case if a client could potentially break out of the session sandbox.||

MODIFY
docs/toc.js
docs/toc.js
@@ -264,7 +264,8 @@ module.exports = {
['Running with multiple versions of Xcode', 'multiple-xcode-versions.md'],
['The Event Timings API', 'event-timings.md'],
['Setup for Parallel Testing', 'parallel-tests.md'],
- ['The Settings API', 'settings.md']]],
+ ['The Settings API', 'settings.md'],
+ ['Memory Collection', 'memory-collection.md']]],
['Contributing', ['contributing-to-appium',
['Running Appium from Source', 'appium-from-source.md'],
['Developer Overview', 'developers-overview.md'],

MODIFY
lib/main.js
lib/main.js
@@ -92,7 +92,14 @@ function logServerPort (address, port) {
function initHeapdump (args) {
if (args.heapdumpEnabled) {
+ try {
require('heapdump');
+ } catch (err) {
+ logger.error(`Memory dump enabled through the '--enable-heapdump' server argument\n` +
+ `but 'heapdump' not installed.\n` +
+ `See https://github.com/appium/appium/tree/master/docs/en/advanced-concepts/memory-collection.md ` +
+ `for more information.`);
+ }
}
}

MODIFY
package.json
package.json
"yaml-js": "^0.2.0"
},
"optionalDependencies": {
- "fsevents": "2.x",
- "heapdump": "0.x"
+ "fsevents": "2.x"
}
}

Make heapdump a manual dependency (#12420)