nsolid-command-gc

nsolid-command-gc - an N|Solid custom command to request garbage collection
================================================================================

This package provides an [N|Solid custom command][] to request garbage
collection for an N|Solid process. After installing the custom command as an
npm package, you can then register the command in your app - when running
your app with the N|Solid Runtime, you'll be able to request garbage collection
with the nsolid-cli tool.

For more information on N|Solid, visit the [N|Solid product page][].

!demo

Installation
================================================================================

npm install nsolid-command-gc

Usage
================================================================================

Once you have installed the package, you can register the gc custom command within
your apps in one of two ways:

* Add require('nsolid-command-gc') somewhere in your application code

* Add the arguments --require nsolid-command-gc to your nsolid command
invocation; the --require option is standard in modern versions of
Node.js, including the N|Solid Runtime

The second option requires no changes to your code, so it obviously wins!

You will also need to use the Node.js --expose-gc option, which will add
a gc() function to the global object. This package uses this function to
request the garbage collection.

Once the gc custom command has been registered, garbage collection can be
requested for these apps with the nsolid-cli command, using the custom
subcommand with the --name gc option.

Putting this all together:

Run your app with the gc custom command registered:

nsolid --require nsolid-command-gc --expose-gc [other Node.js parameters]

Request garbage collection for that process, where $AGENT_ID is the agent id
for that process:

nsolid-cli custom --id $AGENT_ID --name gc

By default, a 'full' garbage collection is requested. For a 'minor' garbage
collection, use the arguments --data minor, as in:

nsolid-cli custom --id $AGENT_ID --name gc --data minor

The result of the nsolid-cli custom command is a line of JSON, that has a
result property as a top-level property. The value of that property contains
two properties: status and type. The status property indicates whether
the garbage collection was able to be requested. The type property returns
full or minor depending on which type of garbage collection was requested.
For example:

{
"result": {
"status": "OK",
"type": "full"
},
"id": "",
"app": "",
"hostname": "",
"tags": [' "time":
}

When the gc command is registered, and when it is invoked, the process it is
registered with will output messages to stderr via
[process.emitWarning()][process.emitWarning]†. You can use Node.js
command-line options and event emitters on process to customize the behavior
of this method call.

† process.emitWarning is only available in N|Solid based on Node.js LTS 6.x Boron
and newer. Argon-based N|Solid releases will simply use process.stderr.

Example Usage
================================================================================

A sample is shipped with this package, in the test directory, named
generate-garbage.js. This application generates and then orphans a lot of
references that need to be garbage collected. After letting it run for a few
seconds, and then using the gc custom command, you should see a drop in the
process's [rss][rss] memory value. Hint: use the N|Solid Console to watch the
rss value drop in the process graphs.

Note that for this example, you will need to have the N|Solid Storage server
already running, and will probably want the N|Solid Console running as well.
For more information on installing and using the N|Solid Storage and Console
servers, see the [N|Solid documentation site][].

We'll assume you've already run npm install nsolid-command-gc for your
application, and that the package is available in
node_modules/nsolid-command-gc.

First, let's set some environment variables for N|Solid:

export NSOLID_APPNAME=generate-garbage # the name of the N|Solid application
export NSOLID_COMMAND=9001 # the command port of N|Solid Storage

Now run the test app with the gc custom command enabled:

nsolid --require nsolid-command-gc --expose-gc node_modules/nsolid-command-gc/test/generate-garbage.js

You should see the following message in the output of the process, indicating
the custom command has been installed:

(nsolid:$PID) nsolid-command-gc: installing nsolid custom command "gc"

By monitoring this process in the N|Solid Console, you can see memory usage
increasing.

To request a garbage collection, we first need to know the agent id of the
process. You can see it in the URL from the N|Solid Console when viewing the
process details - it's a 40 character hex string that is a path element of the
page's URL. Alternatively, you can get it from with the nsolid-cli ls command.
Since the nsolid-cli ls command outputs a line of JSON for every N|Solid process,
you probably want to have a nice JSON swiss army knife utility like [jq][] handy to
produce more readable output. Using jq and grep as filters, the following
command will print out the agent id of the generate-garbage application:

nsolid-cli ls | grep generate-garbage | jq .id

Now, given the agent id, you can request garbage collection with the
command, where you would replace $AGENT_ID below with the actual agent id:

nsolid-cli custom --id $AGENT_ID --name gc | jq

The nice looking output formated from jq will look like this:

``json
{
"result": {
"status": "OK",
"type": "full"
},
"id": "a2827de4011e0b683c101aae7db5c37e9c62c5c7",
"app": "generate-garbage",
"hostname": "your-hostname-here",
"tags": [],
"time": 1484957897813
}
``

The process the command is sent to should also print the following message:

(nsolid:$PID) nsolid-command-gc: requesting full garbage collection

You should notice the garbage collection visually in N|Solid Console, by a drop
in memory measurements in the graphs.

Contributing
================================================================================

To submit a bug report, please create an [issue at GitHub][].

If you'd like to contribute code to this project, please read the
[CONTRIBUTING.md][] document.

Authors and Contributors
================================================================================

License & Copyright
================================================================================

nsolid-command-gc is Copyright (c) 2017 NodeSource and licensed under the
MIT license. All rights not explicitly granted in the MIT license are reserved.
See the included [LICENSE.md][] file for more details.

[N|Solid product page]: https://nodesource.com/products/nsolid
[N|Solid documentation site]: https://docs.nodesource.com
[N|Solid custom command]: https://docs.nodesource.com/docs/custom-commands
[rss]: https://en.wikipedia.org/wiki/Resident_set_size
[jq]: https://stedolan.github.io/jq/
[issue at GitHub]: https://github.com/nodesource/nsolid-command-gc/issues
[CONTRIBUTING.md]: CONTRIBUTING.md
[LICENSE.md]: LICENSE.md
[process.emitWarning]: https://nodejs.org/dist/latest-v6.x/docs/api/process.html#process_event_warning