Top

Getting Started

N|Solid Overview

NodeSource has developed N|Solid to meet the needs of enterprise production environments. Built upon the experience and insights of several core contributors to the Node.js ecosystem, N|Solid provides live instrumentation of your production system's health, and stability with no changes to your application code. In addition, N|Solid offers the ability to control access and define policies for your critical applications.

Overview of the N|Solid Components

"N|Solid Architecture"

N|Solid Runtime

At times, Node.js can feel like a black box. Shifting to an asynchronous programming model changes how developers are required to handle and interpret existing data. In order to help customers gain more visibility, we provide the N|Solid Runtime. The N|Solid Runtime is a build of Node.js bundled with an advanced native C++ component, the N|Solid Agent. The N|Solid Agent runs on its own thread inside your application, with direct access to the core elements of Node.js, libuv and the V8 JavaScript engine.

The N|Solid Runtime provides access to detailed metrics, and allows you to control application behavior in production. It also includes a powerful security policy model that allows restricting access to system resources by untrusted modules.

Read more about using the Runtime from the command line »

Node Compatibility

N|Solid 3.x is delivered bundled with either a Node.js v4.x Argon LTS, Node.js v6.x Boron LTS, or Node.js v8.x Carbon LTS runtime. All N|Solid features are additive, meaning any application that runs on Node.js will also work with N|Solid. To verify the version of Node.js you have bundled in N|Solid, use nsolid -v.

For more information about the Node.js API, consult the Node.js API Documentation.

N|Solid Console

The N|Solid Console provides centralized access to all of your applications, and an aggregated view of each application's processes. This holistic view simplifies triage at runtime, makes it easier to find outliers, and takes advantage of advanced diagnostic tools directly from your browser.

Read more about the Console »

Summary

The combination of the Runtime and Console make N|Solid an invaluable tool for gaining insight into the behavior of your live production applications.

Backed by NodeSource's 24x7 support, N|Solid adds enterprise-grade diagnostic and security features, delivered on a release cycle that is aligned with Node.js Long Term Support (LTS) releases. This provides a stable production platform for all of your Node applications.

Console Overview

The N|Solid Console provides valuable insight into clusters of N|Solid processes running in a variety of configurations. Processes are grouped by their associated application, making it simple to find outliers in memory and CPU utilization.

Navigating to an individual process shows various metrics, and provides the ability to take heap snapshots and generate CPU profiles.

"Flamegraphs"

Processes View

The Processes view provides a visual overview of all or a subset of N|Solid applications monitored by the Console. When you first view the N|Solid Console, all processes will show up in this view. Using Filtering and Saved Views, you can filter processes by name, tags, performance, and many other attributes and create saved views to group sets of processes.

"Processes View"

Section Description
View The View dropdown allows you to navigate between different Saved Views and their respective Scatterplots. See Saved Views for more information on creating and managing Saved Views. The default view is All Processes
Filter The filter allows you to dynamically query for processes or create a new saved view
Scatterplot The scatterplot is a graph where processes matching the currently-selected saved view will be shown. Graph axes can be configured differently for each saved view, and process dots animate as the values for those attributes change
Processes List The process list is a textual representation of the processes graphed on the scatterplot

The Scatterplot

The Scatterplot is an animated graph that provides an overview of your application’s performance across all or a subset of connected processes.

Graph Axes Configuration

By default, the Y-axis plots the memory (Heap Used), and the X-axis plots the % CPU utilized for each process. You can configure these axes to measure different parameters.

"Configuring scatterplot axes"

The following metrics can be used for the scatterplot axes within either axis configuration drop down.

Section Description
1 Minute Load Average The one-minute load average
5 Minute Load Average The five-minute load average
15 Minute Load Average The fifteen-minute load average
Active Handles The number of active handles the event loop will process
Active Requests The number of active requests the event loop will process
CPU Used (%) % CPU used by the process
Event Loop Idle Percent Percent of time that Node is waiting for I/O ("idle")
Event Loop Estimated Lag The amount of time an I/O response may have to wait before being processed
GC Count The total number of garbage collections
Heap Total The total allocated size of the JavaScript heap (bytes)
Heap Used The amount of heapTotal being used by JavaScript (bytes)
Process Uptime The time in seconds this process has been running
Resident Set Size The total Resident Set Size (total memory used) by this process (bytes)

Additionally, clicking on Show Expert Metrics reveals a search modal in which any numeric metric available to N|Solid may be used.

Processes List

The processes list on the right side of the page provides a textual representation of the processes on the scatterplot.

Click and drag inside the scatterplot to select a subset of processes that are grouped together. The process list will update to show only these processes. Click Apply as Filter to view the selected processes as a filter, which you can then save as a Saved View. Click Clear or click on the graph to clear the selection and show all processes.

"Selecting processes"

Sort selected processes in the process list using the Sort dropdown. Sorting by app name or hostname will group like processes together. Sorting by vulnerability status will group vulnerable and non-vulnerable processes together respectively. Sorting by CPU, memory, or uptime will sort the processes numerically by these metrics. For sorting methods that group processes (app name, hostname, and vulnerability status), clicking on the label for a group of processes will select only that group of processes.

Clicking the process ID will take you to the Process Detail view.

"Selecting processes"

Hovering your mouse over a process in process list will highlight that process in the graph for easy identification among other processes. Hovering on a process when processes are selected also reveals an X icon that may be clicked to remove a single process from the selection.

"Highlighting and unselecting processes"

Hovering over a process also shows a target icon that enables process targeting. Process targeting causes one minute of the process's recent historic metrics to be visualized as a trail following the process around the graph. One process can be targeted at a time. Clicking the target icon a second time will disable process targeting.

"Process targeting"

Process Detail View

The Process Detail view shows detailed information relating to a specific process. At the top of the view it displays data that N|Solid receives from the process, including the pid, host, platform, and CPU configuration.

"Process Detail"

The right side of this page also contains controls for manually taking CPU profiles and heap snapshots of this process.

Metrics Tab

The Metrics tab contains several charts which visualize important performance metrics which N|Solid gets from your processes.

Section Description
CPU Used CPU usage for this process
Memory Heap total, heap used, and resident set size. Heap total is total size of the V8 heap, which includes everything in the heap, including free space which has been allocated by V8 but is unused by JavaScript objects. Heap used is the size of of the V8 heap occupied directly by JavaScript objects created by the application, as well as V8 internal objects created on behalf of it. Resident set size (RSS) is the actual memory footprint of the process over time. It does not include memory that belongs to the process that has been swapped out to disk
Host Load The average system load over the last one, five, and fifteen minutes
Async Data Two series that reflect asynchronous activity. One is the number of async handles, which tend to be generated by longer-lived larger-scale asynchronous operations, such as open sockets or timers. The other is the number of async requests. These tend to be made by shorter-lived and smaller-scale operations, such as writing to file handles
Event Loop Two series that reflect the health of the event loop. The Idle % shows how often the event loop is waiting for work. The Lag data shows the average time in milliseconds for each tick of the event loop
Internal Activity Two series which include process-lifetime counts of the total number of garbage collections performed, and the number of event loop turns
Host Memory The amount of host memory in use by all processes on this system
Internal Activity Rates The Internal Activity graph, but instead of lifetime totals it shows how many Event Loop iterations and Garbage Collections run per second
HTTP Median The median timing of HTTP/HTTPS Client or Server requests and DNS requests made by the application. Each is measured in milliseconds
HTTP 99th Percentile The 99th Percentile timings of HTTP/HTTPS Client and Server requests and DNS requests made by the application, measured in milliseconds
HTTP Totals The total counts of HTTP/HTTPS Client and Server requests and DNS requests for the lifetime of the application
HTTP Requests Per Sec The number of HTTP/HTTPS Client and Server requests and DNS requests made by the application per second

Modules Tab

The Modules tab lists all modules this process is loading and using at runtime. More importantly, this tab prominently features modules that include known security vulnerabilities.

"Process Assets"

Assets Tab

The Assets tab lists CPU profile and heap snapshots related to this process. Click on the asset to view it.

"Process Assets"

Quick Start Guide

This guide will help you quickly install all of the N|Solid components onto your development machine on OS X. For instructions on installing the individual components for a production cluster on Linux, see the installation guide.

Installing The OS X Developer Bundle

To install the Developer Bundle for OS X:

  1. Go to downloads.nodesource.com
  2. Click on the Mac OS button to get an installable package
  3. Double click on the downloaded pkg file and follow the instructions to install the N|Solid compoments

Setting Up the N|Solid Console

Once installed, using the developer bundle on OS X is fairly straightforward. To launch the console, open a terminal window and enter the command:

$ nsolid-console

Note that you do not have to be the root user to run the console, only to install it. Logs for each process can be found under /tmp/nsolid-*.

Once the Console is running, you can see the user interface by opening a new web browser window to http://localhost:6753.

You should be redirected to http://localhost:6753/welcome, where you will be asked to enter your License Key. If you already have and know your License Key, paste it in here. Otherwise click Get Started at the bottom of the form.

Welcome Screen

Fill out all fields on the Register or Retrieve Key form and a key will be emailed to you. If you have previously set up a key, your existing key will be emailed to you, if not, a new one will be generated and emailed to you.

Register or Retrieve Key

Once you've received your N|Solid license key, paste it into the form found at http://localhost:6753/welcome/license and click SUBMIT.

Enter License Key

Once a valid key is entered, you should be immediately redirected to the N|Solid console.

N|Solid Console Up and Running

Running Node Applications in N|Solid

The next step is to configure your shell to use the N|Solid Runtime.

Open a second Terminal window and run:

$ source /usr/local/nsolid/nsolid-env

This will activate the N|Solid shell.

Any Node application that you start from within the N|Solid Shell will then be shown in the N|Solid Console.

For example, monitor the Node.js REPL using N|Solid by running:

$ NSOLID_APPNAME="REPL" node

If you have an existing Nodejs application, e.g. "index.js", you can monitor it with N|Solid by running:

$ NSOLID_APPNAME="My_Application" node index.js

You can customize the name of your application in the N|Solid Console by changing the NSOLID_APPNAME environmental variable. If you do not specify an app name, N|Solid will look for a 'name' property in your package.json, and if that is not found your application will be named untitled application.

You are now ready to use N|Solid for your own applications!

Migration Guide

If you are upgrading from N|Solid 2.x, here are the need-to-know steps for migrating to N|Solid 3.x.

  • N|Solid Storage has been eliminated, and its functionality is provided by the N|Solid 3.x Console server. Attempting to connect an existing N|Solid Storage instance to a N|Solid 3.x Console will not work unless the storage instance is running in relay mode.

  • Many of the settings and environment variables from N|Solid Storage are available in the 3.x N|Solid Console; substitute CONSOLE for STORAGE in the variable name. View the Networking documentation for specific settings.

  • Loading a N|Solid 3.x Console server with the same configuration as a N|Solid Storage instance will load some of your existing assets and metrics history, but Heap Snapshots will need to be accessed directly from your storage device. The default location has changed from ~/.nsolid-storage to ~/.nsolid-console.

  • The N|Solid 2.x Runtime is compatible with the N|Solid 3.x Console, but not all functionality will be available.

  • The environment variables used to configure N|Solid Runtime are the same as with N|Solid 2.x, however you must provide a valid license during any operation, either via a connection to an N|Solid Console, or by providing a License Token directly. Read the Configuration guide for more information.

  • The nsolid-cli syntax and behavior have changed from 2.x, be sure to read the Command Line Interface documentation if you use this functionality.

N|Solid On-Prem in Production

Installation

This guide will help you quickly install all of the N|Solid components for a production cluster. We provide production rpm and deb packages for use in Linux distributions. This makes it significantly easier to set up the N|Solid components by using our repositories.

We support the following rpm based 64-bit Linux distributions:

  • RHEL6 / CentOS6
  • RHEL7 / CentOS7
  • Fedora 24
  • Fedora 25
  • Fedora 26

We also support the following deb based 64-bit Linux distributions:

  • Debian Wheezy
  • Debian Jessie
  • Ubuntu Trusty
  • Ubuntu Xenial
  • Ubuntu Zesty

If you do not wish to use these packages, manual installation instructions are provided below.

Note: The default Node.js runtime used in the instructions below is Node.js v8 LTS (Carbon). If you wish to use a version of N|Solid based on Node.js v6 LTS (Boron) or Node.js v4 LTS (Argon), replace any instances of carbon with boron or argon, respectively.

Installing N|Solid Packages

Step 1: Set Up the NodeSource N|Solid Repository

For rpm based distributions, use the following command as root:

$ curl -sL http://nsolid-rpm.nodesource.com/nsolid_setup_3.x | bash -

For deb based distributions, there is a similar command run as root:

$ curl -sL http://nsolid-deb.nodesource.com/nsolid_setup_3.x | bash -

In both cases, these scripts will attempt to determine the distribution you are using, set up the appropriate repository on your system, and import the NodeSource N|Solid GPG key used to sign the packages.

Step 2: Install the Packages

For rpm based systems, install all the required components with the command:

$ yum -y install nsolid-carbon nsolid-console

For deb based systems, the process is similar. Install the required components:

$ apt-get -y install nsolid-carbon nsolid-console

On deb based systems, the relevant daemons will start automatically on installation, but you will still turn the services on and off using the standard tools.

For both rpm and deb based systems, you can then turn on the installed components using the standard system tools. Below are examples of how to turn on the N|Solid Console component using both init and systemd style systems.

Start the component in an init style system with:

$ /etc/init.d/nsolid-console start

Newer systemd style systems would use the command:

$ systemctl start nsolid-console

These N|Solid components can be installed separately, and possibly on different machines if you wish. However, if you plan on installing all of the components onto a single machine, the process can be further simplified. Instead of installing the components individually by name as we've done here, you can simply install the nsolid-console-all meta package for your system.

For rpm based distributions:

$ yum -y install nsolid-carbon-console-all

And for deb based distributions:

$ apt-get -y install nsolid-carbon-console-all

This meta package will install all of the components and turn them on if needed.

Upgrading N|Solid Packages

Once you have set up the NodeSource N|Solid package repository appropriate to your system, you will automatically get point releases via the standard system update tools. For example, fetch and install any new versions of the packages with:

yum -y update

Manual Installation

These instructions use the Linux platform builds, but the same steps apply for macOS (darwin) platforms.

Step 1: Get N|Solid

  1. Go to downloads.nodesource.com.
  2. Scroll down to the Downloads section and click the Linux Bundle for the LTS version you wish to run.
  3. Extract the archive.

The extracted archive contains all N|Solid components for your architecture:

  • The N|Solid Runtime (e.g. nsolid-v3.0.0-carbon-linux-x64.tar.gz)
  • The N|Solid Console (e.g. nsolid-console-v3.0.0-linux-x64.tar.gz)

Step 2: Install the N|Solid Runtime

The N|Solid Runtime is a build of Node.js that is compiled to include the N|Solid Agent. The runtime should be installed on any application servers where you intend to run your Node.js application.

$ tar xf nsolid-v3.0.0-carbon-linux-x64.tar.gz
$ cd nsolid-v3.0.0-carbon-linux-x64
$ ls
bin  CHANGELOG.md  include  lib  LICENSE  LICENSE.NSOLID  README.md  share

We suggest installing into /usr/local for greatest compatibility, though most preferred installation methods used for Node.js will also work for N|Solid.

To install to /usr/local, first remove existing npm and nsolid-cli installations:

$ rm -rf /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/nsolid-cli

Then, put the N|Solid components in place:

$ cp -r lib bin share /usr/local/

To verify you are running Node compiled with the N|Solid Agent and see your version of N|Solid, use:

$ node -vv
v3.0.0

This package also contains the nsolid-cli application, which can act as a command-line interface to the N|Solid Agent via the N|Solid Console, allowing scripted or manual interaction.

Step 3: Install the N|Solid Console

The N|Solid Console is a graphical interface for your entire cluster of applications running on N|Solid. It communicates with each N|Solid Agent to track metrics, collect information, or trigger events on any of your N|Solid processes.

The N|Solid Console is best experienced using one of the following browsers on a desktop/laptop system.

  • Google Chrome (21 and higher)
  • Mozilla Firefox (22 and higher)
  • Apple Safari (9 and higher)

The download bundle includes the nsolid-console built for your platform.

$ tar xf nsolid-console-v3.0.0-linux-x64.tar.gz
$ ls nsolid-console-v3.0.0-linux-x64

Place this folder wherever you typically install your Node.js applications. For this example, we'll put it in /var/opt.

$ cp -r nsolid-console-v3.0.0 /var/opt
$ cd /var/opt/nsolid-console-v3.0.0

Running npm start from within this directory will start the N|Solid Console with the default configuration.

For more information about configuration options for the N|Solid Console, see: configuration.

You will want to run nsolid-console as any other Node.js service in your infrastructure, using your process manager of choice.

Upgrading From Previous Versions of N|Solid

To upgrade from previous versions of N|Solid, use the instructions above to install over your previous installation. At each step, verify that the latest version of the component is installed and working.

If you have the N|Solid Hub, Proxy, or Storage components installed from an earlier version of N|Solid, these components can be removed.

For rpm based systems, this can be done with:

$ yum remove nsolid-proxy nsolid-storage

For deb based systems, this would be:

$ apt-get remove nsolid-proxy nsolid-storage

The etcd package may be in use by your system for other purposes, but if you no longer require it, it too can be removed:

$ yum remove etcd

or

$ apt-get remove etcd

Older N|Solid Artifacts

N|Solid 2.x

The storage directory structure did not substantially change from N|Solid 2.x to N|Solid 3.x, and if you start your Console with the same directory, you may see some of your data and artifacts. However, compatibility between these versions is not guaranteed. It is recommended that you start with an empty storage directory and access your old files directly on your storage device.

Configuration

N|Solid Runtime

Environment Variables

All environment variables are optional for the N|Solid Runtime, however functionality will be limited. It is recommended that you connect to the console using NSOLID_COMMAND or a StatsD collector using NSOLID_STATSD, and customize your process using any of the remaining environment variables.

Environment Variable Description
NSOLID_COMMAND The route to the console command port. It should be formatted as "host:port". The default host is localhost, and the default port is 9001. Without this environment variable, the N|Solid Agent will not attempt to connect.

The host can be provided via several formats:
   IPv4 10.0.0.21
   IPv6 [2001:cdba::3257:9652]
   hostname nsolid_hub.local
NSOLID_APPNAME The name of the application that the instance is running. Use this in order to create logical groupings of the processes in the console. If omitted, the value defaults to the name field of your package.json. If this is also omitted, the value defaults to untitled application
NSOLID_TAGS The list of tags associated with your instance, which can be used to identify and filter instances in Console views. See Tags and Filters for more details
NSOLID_PUBKEY The ZMQ public key used with the N|Solid Console server
NSOLID_HOSTNAME The hostname the N|Solid process is running on (overrides system-determined hostname)
NSOLID_STATSD The route to a StatsD collector if you wish to send metrics directly to an external data collection service from the N|Solid process. Without this environment variable, the N|Solid Agent will not attempt to send StatsD data.

It should be formatted as "host:port". If unspecified, the default host is localhost and port is 8125. Hosts and IP addresses are accepted in the same format as NSOLID_COMMAND
NSOLID_INTERVAL The interval, in milliseconds, in which the N|Solid Agent will collect and report metrics to the console and/or the StatsD collector if either are connected. This value defaults to 3000 (3 seconds) and cannot be lower than 1000
NSOLID_STATSD_BUCKET An override for the default StatsD bucket (key prefix) when using the NSOLID_STATSD functionality. See the StatsD section for more details
NSOLID_STATSD_TAGS Optional tags to append to StatsD metric data when using the NSOLID_STATSD functionality. See the StatsD section for more details

package.json

The N|Solid process can also be configured via an nsolid object in the package.json file for the current application. Environment variable values override the properties in the package.json file. The mapping of nsolid object properties in the package.json file to environment variables is as follows:

nsolid property in package.json Environment Variable
command NSOLID_COMMAND
pubkey NSOLID_PUBKEY
statsd NSOLID_STATSD
statsdBucket NSOLID_STATSD_BUCKET
statsdTags NSOLID_STATSD_TAGS
hostname NSOLID_HOSTNAME
env NODE_ENV
interval NSOLID_INTERVAL
tags NSOLID_TAGS - this may be an array of tag values or a comma-separated string of tag values
app NSOLID_APPNAME

Example package.json:

# package.json

{
  "name": "message-service",
  "version": "1.0.0",
  "nsolid": {
    "env": "production",
    "command": "nsolid-command-host.local:9001",
    "app": "messaging",
    "tags": "aws, mq"
  }
}

N|Solid API

Another option, which can be useful if you don't have access to static configuration data, is to use the N|Solid API from within your application. For example, if you have a configuration management platform or database that knows the hostname and port to your Console, you may obtain it and then invoke nsolid.start() to connect and begin reporting metrics. This can be done at any time, as long as your process is not already connected to an N|Solid Console. The keys are the same as the package.json ones documented above, with the following difference:

  • version is specified as appVersion

Example:

nsolid.start({
  command: 'nsolid-command-host.local:9001',
  tags: ['aws', 'mq'],
  app: 'messaging'
})

N|Solid CLI

Configuration File

The N|Solid Command Line Interface (CLI) can be configured via a configuration file, .nsolid-clirc.

# .nsolid-clirc

{
  "remote": "http://localhost:6753",
  "app": "my-node-application"
}

N|Solid Console

Command Line Arguments

These are the command line arguments if you're starting the console explicitly. For most usages, you would utilize npm start.

Parameter Description
--config Specify a config file

Environment Variables

If you are using the developer bundle, you can use the following to configure the console:

Environment Variable Description
NSOLID_CONSOLE_NOTIFICATION_CONSOLE_URL Specify a routable protocol, domain, and port for use in notifications
NSOLID_CONSOLE_WEB_SERVER Specify a hostname and port that the console server should bind to
NSOLID_CONSOLE_WEB_PROTO Specify whether the server should use HTTP or HTTPS
LOGLEVEL The level of logging produced. Defaults to info; can be error, warn, info, debug

Stats Retention

Historical metrics, displayed in the line-chart UI elements, are trimmed to the last 15 minutes by default.

For more information about configuration options for N|Solid Console's data processing functions, see networking.

License Keys

Registering Your License Key

In order to access N|Solid you must have an enabled license key. If you have not entered your license key, when you try and access the console you will be redirected to the welcome screen. If you already have your License Key, paste it in the license key field. Otherwise click Get Started at the bottom of the form.

Welcome Screen

Fill out all of the fields on the Register or Retrieve Key form and a license key will be sent to you via email:

  • If you have previously set up a license key, you will receive your existing key
  • If you have not previously set up a license key, a new license key will be created

Register or Retrieve Key

Once you've received your N|Solid license key, paste it into the Welcome screen form and click SUBMIT.

Once a valid key is entered, you should be immediately redirected to the N|Solid Console.

Updating Your License Key

If you need to update your license key from your original demo key (or for any other reason), click Settings on the right side of the menu at the top of the page.

Paste in your updated N|Solid license. Settings will be saved automatically.

Your updated license key should now be active.

Using StatsD or AppDynamics without connecting to Console

You must have a valid license to use the N|Solid Runtime either with the Console or communicating directly to your StatsD endpoint. If you do connect to your N|Solid Console, the license will be configured automatically for you. If you prefer to use your runtime without connecting to console, you must provide your license in the form of a signed token. This can be obtained from a running licensed N|Solid Console by running nsolid-cli license-token or by querying http://console:6753/api/v3/license-token directly.

If you do not have a N|Solid Console available, you can contact NodeSource Support and they can provide you with one. The token will be valid for the duration of your license period and must be refreshed when your expiration date is extended.

Your valid license token can be specified as the NSOLID_LICENSE_TOKEN environment variable or included in the nsolid section of package.json as "licenseToken".

Offline or Air-Gapped operation

Similar to the StatsD situation, your N|Solid installation must have a valid license to operate. If your system is not able to contact the NodeSource web services, you may use the license token as described previously by pasting it into the License Key entry field in your N|Solid Console.

Make sure you are not passing your xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx license key as the token value. This is your license key and cannot be used in offline licensing.

Troubleshooting

Debug Messages

The N|Solid Runtime and CLI all can have debug messaging enabled by using the NODE_DEBUG=nsolid environment variable.

$ NODE_DEBUG=nsolid NSOLID_APP=testapp NSOLID_COMMAND=localhost ~/ns/nsolid-node/nsolid
> NSOLID 16597: starting agent (js init) name: testapp id: e24a79b2aae58b63e385a4c0ce9ed91f3d0202ee tags: undefined
NSOLID 16597: nsolid agent e24a79b2aae58b63e385a4c0ce9ed91f3d0202ee starting with config
NSOLID 16597: { command: '9001',
  data: undefined,
  bulk: undefined,
  pubkey: undefined,
  statsd: undefined,
  statsdBucket: 'nsolid.${env}.${app}.${hostname}.${shortId}',
  statsdTags: undefined,
  hostname: 'rpi3-1',
  env: 'prod',
  interval: null,
  tags: undefined,
  app: 'testapp',
  appVersion: undefined }
NSOLID 16597: { zmq_command_remote: 'tcp://localhost:9001',
  zmq_data_remote: null,
  zmq_bulk_remote: null,
  statsd_addr: null,
  storage_pubkey: '^kvy<i^qI<r{=ZDrfK4K<#NtqY+zaH:ksm/YGE6I' }
NSOLID 16597: registering default commands
NSOLID 16597: nsolid initializing
NSOLID 16597: agent spawn()
NSOLID 16597: agent spawned
NSOLID 16597: e24a79b2aae58b63e385a4c0ce9ed91f3d0202ee nsolid initialized
NSOLID 16597: { command_remote: 'tcp://localhost:9001',
  data_remote: 'tcp://localhost:9002',
  bulk_remote: 'tcp://localhost:9003',
  storage_pubkey: '^kvy<i^qI<r{=ZDrfK4K<#NtqY+zaH:ksm/YGE6I' }

StatsD

The N|Solid Agent is able to periodically send a suite of metrics directly to a StatsD-compatible data collector endpoint. As this functionality is built directly into the nsolid executable, you do not need to be connected to the N|Solid Console server in order to use it. Independent nsolid processes can be configured to talk to StatsD collectors using environment variables when starting your application.

Consult the Metrics in Detail section for a complete list of metrics that are sent to the StatsD collector for your N|Solid processes.

Consult the Using StatsD or AppDynamics without connecting to Console section for instructions on configuring a license token, if your N|Solid processes are not connected to the N|Solid Console server.

Supported backends

StatsD is a standardized protocol that is supported by many data collection databases and services. Supported backends include AWS CloudWatch, DataDog, ElasticSearch, Graphite, InfluxDB, MongoDB, OpenTSDB, StackDriver, Zabbix and many more. See the StatsD documentation for a more complete list.

Connection options

Supply the NSOLID_STATSD environment variable when starting an N|Solid process to have the Agent attempt to connect to an endpoint. The format of this value is "host:port". If unspecified, the default host is localhost and port is 8125. The host can be specified as a hostname string, an IPv4 or IPv6 address.

Once connected, a suite of metrics will be sent to the collector using the StatsD protocol. The NSOLID_INTERVAL environment variable can be used to adjust the default reporting interval of 3 seconds. Be aware that this will also change the reporting interval for the N|Solid Console connection if connected via the NSOLID_COMMAND environment variable.

StatsD buckets

StatsD metrics are reported using "buckets". A bucket is the full name, or key, of the entry being reported. Buckets need to be descriptive enough to clearly identify the process, host and metric type being reported. It is important that you have enough granularity to be able to inspect the data at the level you require, while also retaining the ability to group metrics for aggregate reporting in your frontend using bucket wildcard mechanisms. This will depend somewhat on your reporting frontend and may require some experimentation.

By default, N|Solid creates bucket names prefixed with "nsolid.<env>.<app>.<hostname>.<shortId>.", followed by the name of the metric. In this string:

  • env is the value of the NSOLID_ENV environment variable if it exists, or the "env" property of the "nsolid" section in package.json if it exists. Defaults to "prod" if not otherwise supplied.
  • app is the value of the NSOLID_APP environment variable if it exists, or the "app" property of the "nsolid" section in package.json if it exists, or the "name" property in package.json if it exists, or process.title if it has been set. Defaults to "untitled application" if not otherwise supplied.
  • hostname is the value of the NSOLID_HOSTNAME environment variable if it exists, or the "hostname" property of the "nsolid" section in package.json if it exists. Otherwise, the value of os.hostname() is used.
  • shortId is the first 7 characters of the random alphanumeric ID created by the N|Solid Agent at startup. This can be used to uniquely identify your processes. The full 40 character string is also available as id if required.

To override the default StatsD metric bucket strings, provide a string via the NSOLID_STATSD_BUCKET environment variable to be used as the full prefix. ${key} style variables can be used to insert any of the above values. The default bucket prefix would be specified as follows: "nsolid.${env}.${app}.${hostname}.${shortId}".

Your StatsD data, by default, will be formatted like so when sent to the collector:

nsolid.prod.myapp.nodehost.803bbd5.uptime:314.4|g
nsolid.prod.myapp.nodehost.803bbd5.rss:28401664|g
nsolid.prod.myapp.nodehost.803bbd5.heapTotal:8425472|g
nsolid.prod.myapp.nodehost.803bbd5.heapUsed:5342488|g
...

StatsD tags

Some backends, such as DataDog support "tags" for metric reporting. By default, N|Solid does not append any tags to its metrics. If required, you can supply your own tags to be appended to all reported metrics from an individual process.

Using the NSOLID_STATSD_TAGS environment variable, or the statsdTags property of the nsolid section in package.json, supply a string with the same variable substitution format as for the buckets above. In addition to env, app, hostname, shortId and id variables, you can also make use of tags to insert the N|Solid tags that have been supplied for the process.

StatsD tags should be a comma-separated list of strings that your backend can decode. Refer to your backend documentation for how these values are made use of for reporting and whether their use will be suitable for your deployment.

Networking

N|Solid Console

The 3.0 N|Solid Console is the component that provides data persistence for your measurements and artifacts, such as heap snapshots and CPU profiles. It communicates directly with N|Solid Agent processes, and provides the web interface and the API interface for nsolid-cli.

Command Line Arguments

These are the supported command line arguments if N|Solid Console is started explicitly.

Parameter Description
--config=config.toml The configuration file for Console. The default config will be used if none is specified
--relay Run Console in Relay mode. This allows you to place an instance in a segment of your network that can aid connectivity and uptime

Configuration File

N|Solid Console can be configured via a configuration file if the --config argument is specified. This file is formatted as TOML (similar to ini file format). A sample file is available in the file config-sample.toml in the root directory of the nsolid-console server. The contents of the file are also listed below.

To run with a customized configuration, copy the file and edit it so that it contains your customized values. You can omit keys from any section which you don't want to override, and omit entire sections if no keys in that section are overridden.

Alternatively, or in addition, you can set environment variables for every configuration key and value. The names of the environment variables are listed with the configuration keys and values below.

For more information on the TOML language used here, please see: https://github.com/toml-lang/toml

# config-sample.toml

#-------------------------------------------------------------------------------
# This is a sample configuration file for nsolid-console.  It shows the
# configuration keys and default values for those keys.
#
# To run with a customized configuration, copy this file and edit it so that it
# contains your customized values.  You can omit keys from any section which
# you don't want to override, and omit entire sections if no keys in that
# section are overridden.
#
# Then invoke nsolid-console with the -c or --config command line parameter
# and the name of the customized file.
#
# For example:
#    nsolid-console --config <your-config-file.toml>
#
# Alternatively, or in addition, you can set environment variables for
# every configuration key and value.  The names of the environment variables
# are listed with the configuration keys and values below.
#-------------------------------------------------------------------------------
# For more information on N|Solid, please see:
#    https://docs.nodesource.com/docs/
#
# For more information on the TOML language used here, please see:
#    https://github.com/toml-lang/toml
#-------------------------------------------------------------------------------

#-------------------------------------------------------------------------------
# Properties that are file or directory names can be absolute or relative file
# names. When relative, the names are considered relative to the configuration
# file they were specified in.  When using relative file names as environment
# variables, they will be considered relative to the current working directory.
#-------------------------------------------------------------------------------

#-------------------------------------------------------------------------------
# set the logging level - "info" or "debug" - debug is more verbose
#-------------------------------------------------------------------------------

# environment variable NSOLID_CONSOLE_LOG_LEVEL

logLevel = "info"

#-------------------------------------------------------------------------------
# settings for licensing
#
# key = "the-license-key"
#-------------------------------------------------------------------------------

[license]

# environment variable NSOLID_CONSOLE_LICENSE_KEY

key = ""

#-------------------------------------------------------------------------------
# settings for the API HTTP server
#
# proto  - "http" or "https"
# server - "<ip addr | hostname>:<port>"
#
# If the environment variable PORT is set, that value, prefixed with ':', will
# be set to the server property. Eg, using PORT=42 will set web.server to ':42'.
#
# httpProxy and httpsProxy are used to set an explicit HTTP/S proxy for HTTP/S
# requests that console makes to the public internet.  You can also set the
# environment variables HTTP_PROXY or http_proxy, and HTTPS_PROXY or https_proxy
# as the value to use.
#-------------------------------------------------------------------------------

[web]

# environment variable NSOLID_CONSOLE_WEB_PROTO
# environment variable NSOLID_CONSOLE_WEB_SERVER
# environment variable NSOLID_CONSOLE_WEB_HTTP_PROXY
# environment variable NSOLID_CONSOLE_WEB_HTTPS_PROXY

proto      = "http"
server     = "0.0.0.0:6753" # 0.0.0.0 allows access on all network interfaces
httpProxy  = ""
httpsProxy = ""

#-------------------------------------------------------------------------------
# settings for running the API HTTP server in https mode
#
# key and cert are file names, as from Node.js https.createServer() options
#
# when set to blank, the files inside the nsolid-console/etc folder will be used:
#   key:  nsolid-self-signed.key
#   cert: nsolid-self-signed.crt
#
# See note above concerning relative paths.
#
# note: generate new default credentials with ./gen-https-creds.sh
# note: default credentials files shipped with nsolid-console expire in 08/2026
#-------------------------------------------------------------------------------

[web.https]

# environment variable NSOLID_CONSOLE_WEB_HTTPS_KEY
# environment variable NSOLID_CONSOLE_WEB_HTTPS_CERT

key  = ""
cert = ""

#-------------------------------------------------------------------------------
# zmq sockets for access by N|Solid processes
#
# commandBindAddr, dataBindAddr, bulkBindAddr are the zmq port addresses
# that will be bound by the server.
#
# publicKey, privateKey are the keys used to encrypt the messages sent over
# zmq.  For more information see:
# https://github.com/msealand/zmq-zap.node/blob/master/examples/curve.js
#
# HWM, bulkHWM are used to set the high water mark for zmq's internal buffering.
# The value indicates the number of messages to buffer, and 0 indicates no limit.
#
# The N|Solid agent will use environment variables that correspond to these
# settings.  For the sockets, the following N|Solid agent environment variable
# should use an address that it can use to connect to the socket the server has
# bound.
#
#    N|Solid agent env vars    server configuration values
#    ----------------------    ---------------------------
#    NSOLID_COMMAND            sockets.commandBindAddr
#    NSOLID_DATA               sockets.dataBindAddr
#    NSOLID_BULK               sockets.bulkBindAddr
#    NSOLID_PUBKEY             sockets.publicKey
#
# If running the console server in server mode AND relay mode on the same host,
# the configuration values for the sockets.xxxBindAddr above must be different
# for the server mode and relay configurations.
#-------------------------------------------------------------------------------

[sockets]

# For commandBindAddr, dataBindAddr, and bulkBindAddr, the format should be:
#    tcp://[ipAddress]:[port]
# [ipAddress] should be an ip address - host names cannot be used; use
# "*" to addresses on any available network interface.

# environment variable NSOLID_CONSOLE_SOCKETS_COMMAND_BIND_ADDR
# environment variable NSOLID_CONSOLE_SOCKETS_DATA_BIND_ADDR
# environment variable NSOLID_CONSOLE_SOCKETS_BULK_BIND_ADDR
# environment variable NSOLID_CONSOLE_SOCKETS_PUBLIC_KEY
# environment variable NSOLID_CONSOLE_SOCKETS_PRIVATE_KEY
# environment variable NSOLID_CONSOLE_SOCKETS_HWM
# environment variable NSOLID_CONSOLE_SOCKETS_BULK_HWM

commandBindAddr = "tcp://*:9001"
dataBindAddr    = "tcp://*:9002"
bulkBindAddr    = "tcp://*:9003"
publicKey       = "^kvy<i^qI<r{=ZDrfK4K<#NtqY+zaH:ksm/YGE6I"
privateKey      = "2).NRO5d[JbEFli7F@hdvE1(Fv?B6iIAn>NcLLDx"
HWM             = 0
bulkHWM         = 0

# The following socket address values are only relevant when running in --relay
# mode. They are analogs of their similiarly named 'xxxBindAddr' values, but
# used as the zmq sockets of the console server to connect to.  These should
# be formatted as "tcp://host:port"
#
# If you want to use a different keypair on the remote endpoint, you may
# specify a remotePublicKey matching that endpoint.  This can be used to
# perform a rolling update to keys without losing data from agents with the old
# encryption key (by using multiple relays)

# environment variable NSOLID_CONSOLE_SOCKETS_COMMAND_REMOTE_ADDR
# environment variable NSOLID_CONSOLE_SOCKETS_DATA_REMOTE_ADDR
# environment variable NSOLID_CONSOLE_SOCKETS_BULK_REMOTE_ADDR
# environment variable NSOLID_CONSOLE_SOCKETS_REMOTE_PUBLIC_KEY

commandRemoteAddr = ""
dataRemoteAddr    = ""
bulkRemoteAddr    = ""
remotePublicKey   = ""

#-------------------------------------------------------------------------------
# Relay mode settings
#
# These settings are specific to running in relay mode.
#
# maxBufferSizeMb is the max buffering "hwm" values shared between the
# "pull/push" sockets in megabytes.
#
# cleanupSizeMb is the amount of megabytes of buffers to be dropped when limits
# are reached.
#
# logSizeInterval is the interval in seconds that will trigger a buffering
# status to be logged. Only happens when upstream (remote) sockets are
# disconnected.
#-------------------------------------------------------------------------------

[relay]

# environment variable NSOLID_CONSOLE_RELAY_MAX_BUFFER_SIZE_MB
# environment variable NSOLID_CONSOLE_RELAY_CLEANUP_SIZE_MB
# environment variable NSOLID_CONSOLE_RELAY_LOG_SIZE_INTERVAL

maxBufferSizeMb = -1
cleanupSizeMb   = 100
logSizeInterval = 10

#-------------------------------------------------------------------------------
# data settings
#
# dir           - the directory where data will be persisted
# retentionDays - the number of days of metric data that will be retained
#
# See note above concerning relative paths.
#-------------------------------------------------------------------------------

[data]

# environment variable NSOLID_CONSOLE_DATA_DIR
# environment variable NSOLID_CONSOLE_DATA_RETENTION_DAYS

dir           = "~/.nsolid-console/data"
retentionDays = 31
dbname        = 'database'

#-------------------------------------------------------------------------------
# notification settings
#
# consoleURL - the base URL of the console, for use in providing links
# back to the console in notifications.
#-------------------------------------------------------------------------------
[notification]

# environment variable NSOLID_CONSOLE_NOTIFICATION_CONSOLE_URL

consoleURL = "http://localhost:6753"

#-------------------------------------------------------------------------------
# view settings
#
# interval - how often to process saved views
#-------------------------------------------------------------------------------
[view]

interval = 5000

#-------------------------------------------------------------------------------
# log settings
#
# influx - the name of the file where the influxd log will be written
#
# See note above concerning relative paths.
#-------------------------------------------------------------------------------

[logs]

# environment variable NSOLID_CONSOLE_LOGS_INFLUX

influx = "~/.nsolid-console/influxdb.log"

#-------------------------------------------------------------------------------
# vulnerability settings
#
# refreshMinutes - how often the vulnerability database will be refreshed
#-------------------------------------------------------------------------------

[vulnerabilities]

# environment variable NSOLID_CONSOLE_VULNERABILITIES_REFRESH_MINUTES

refreshMinutes = 30

#-------------------------------------------------------------------------------
# assets settings - storage of heap snapshots, cpu profiles, etc
#
# cleanupMinutes  - how often the asset files are cleaned up; the oldest asset
#                   files are deleted to ensure constraints below are met.
# maxAssets       - maximum number of assets to retain
# maxAssetsMb     - maximum size of all assets to retain
#-------------------------------------------------------------------------------

[assets]

# environment variable NSOLID_CONSOLE_ASSETS_CLEANUP_MINUTES
# environment variable NSOLID_CONSOLE_ASSETS_MAX_ASSETS
# environment variable NSOLID_CONSOLE_ASSETS_MAX_ASSETS_MB

cleanupMinutes  = 5
maxAssets       = 500
maxAssetsMb     = 100

Relay Mode

N|Solid Console supports running in a relay mode in order to support proxying through firewalls, buffering agent data during downtime, and scaling with complex network topologies.

The relay sits between your Runtime instances and N|Solid Console. In this mode, nsolid-console looks like an N|Solid Console instance to agents but does not have any N|Solid Console functionality enabled.

Relay Configuration

To use relay mode, set the --relay flag and the three [sockets] variables described below. These can be provided via the configuration file or as environment variables. If omitted, the defaults will be used.

Changing the NSOLID_COMMAND, NSOLID_DATA, and NSOLID_BULK variables is recommended, as those will be the ones that the relay itself listens on while it uses the NSOLID_CONSOLE_SOCKETS-* variables in order to connect to N|Solid Console.

In the simplest case, set the NSOLID_CONSOLE_SOCKETS_* variables to the same values that the related NSOLID_* variables were set to, picking different addresses for the NSOLID_CONSOLE_SOCKETS_* variables.

Environment Variables

Environment Variable Description
NSOLID_CONSOLE_SOCKETS_COMMAND_REMOTE_ADDR This is the route to the Console command port that the relay will use. It should be formatted as "host:port" and follows the same conventions as NSOLID_COMMAND
NSOLID_CONSOLE_SOCKETS_DATA_REMOTE_ADDR This is the route to the Console data port that the relay will use. It should be formatted as "host:port" and follows the same conventions as NSOLID_COMMAND. Unlike NSOLID_DATA, this variable has to be specified or included in the config
NSOLID_CONSOLE_SOCKETS_BULK_REMOTE_ADDR This is the route to the Console bulk port that the relay will use. It should be formatted as "host:port" and follows the same conventions as NSOLID_COMMAND. Unlike NSOLID_BULK, this variable has to be specified or included in the config

Configuration File

The following example shows the [sockets] section of a configuration file written to support relay mode. Note that the related Bind addresses have been changed, and an explicit public key has been specified for the remote Console server.

# config-sample.toml

[sockets]
commandBindAddr = "tcp://<console-address>:8001"
dataBindAddr    = "tcp://<console-address>:8002"
bulkBindAddr    = "tcp://<console-address>:8003"

commandRemoteAddr = "tcp://<console-address>:9001"
dataRemoteAddr = "tcp://<console-address>:9002"
bulkRemoteAddr = "tcp://<console-address>:9003"
remotePublicKey = "^kvy<i^qI<r{=ZDrfK4K<#NtqY+zaH:ksm/YGE6I"

Docker Compose File

Relay mode environment variables need to be added to the console section of the Docker configuration file.

For example, in order to match the settings in the above configuration file, add the following:

# docker-compose.yml

  console:
    environment:
      - NSOLID_CONSOLE_SOCKETS_COMMAND_BIND_ADDR=console:8001
      - NSOLID_CONSOLE_SOCKETS_DATA_BIND_ADDR=console:8002
      - NSOLID_CONSOLE_SOCKETS_BULK_BIND_ADDR=console:8003
      - NSOLID_CONSOLE_SOCKETS_COMMAND_REMOTE_ADDR=console:9001
      - NSOLID_CONSOLE_SOCKETS_DATA_REMOTE_ADDR=console:9002
      - NSOLID_CONSOLE_SOCKETS_BULK_REMOTE_ADDR=console:9003

See the Docker page for more information on setting up Docker Compose.

Advanced Environment Variables

The variables described below should only be necessary if a proxy is required in front of N|Solid Console.

If this is not needed, ignore this section as the variables will be configured by the N|Solid agent via the COMMAND interface.

Environment Variable Description
NSOLID_DATA This is the route to the Console data port. It should be formatted as "host:port", and follows the same conventions as NSOLID_COMMAND. If this argument is not specified, N|Solid will attempt to discover this port from Console via the COMMAND interface
NSOLID_BULK This is the route to the Console bulk port. It should be formatted as "host:port", and follows the same conventions as NSOLID_COMMAND. If this argument is not specified, N|Solid will attempt to discover this port from Console via the COMMAND interface
NSOLID_PUBKEY This is Console's public key. If a custom key is not configured, the default keypair that ships with N|Solid will be used

Moving the N|Solid Console server

The data maintained in the N|Solid Console server is stored in a directory determined by the dir property of the [data] section of the configuration file. The default value is ~/.nsolid-console/data. If the contents of the directory are copied to a new machine, the N|Solid Console server can be run with its configuration pointing to the copied directory.

Docker

For people who need to use N|Solid in a Dockerized environment, NodeSource has developed the N|Solid Docker images.

These images are built with the enterprise customer in mind, developing a versatile set of independently scalable Docker images that work together to provide a unified N|Solid experience across all of your Dockerized infrastructure.

In addition to being friendly to enterprise operations teams, the N|Solid Docker Images have been designed to be accessible to developers. For those who are already using Docker, these images provide an easy way to get up and running with the N|Solid console. With the use of docker-compose, you can now get the full N|Solid Suite on your local machine with a single command.

Overview of N|Solid Docker Images

"N|Solid Architecture"

We provide 3 separate Docker Images for N|Solid, allowing each component of the platform to be scaled and deployed independently.

Docker Image Description
nodesource/nsolid The base image that your Docker images should build from. It provides the N|Solid runtime and agent and needs to be properly configured to register its agent with the N|Solid Console service. Releases
nodesource/nsolid-console Contains the N|Solid console, a web-based interface for monitoring Node.js applications. You will need to bind the internal port 6753 to your host. Releases
nodesource/nsolid-cli Provides an easy way to query statistics from your Node.js processes. It is meant to be run directly from the command line and is optional. Releases

All of the images are built on the official ubuntu:trusty image maintained by the Docker project. The latest tag defaults to the latest Node.js v8.x Carbon LTS release. For more details please refer to the docker-nsolid github repository.

Installing the N|Solid Docker Images

Setting up Docker

First, follow the steps for installing Docker for your operating system.

Although not required, it is recommended that you use docker-compose when first getting started. It simplifies managing these Docker images when running them locally.

Docker Compose

The docker-compose file below provides an example of the N|Solid platform configuration. It is also useful as a starting point for your docker setup.

The following docker-compose file doesn't include any N|Solid applications yet. We will explain how to add your application below. Use a valid path in the volumes configuration, or remove it if persistence is not important to you.

# nsolid.yml

version: "2"
services:
  console:
    image: nodesource/nsolid-console
    container_name: nsolid.console
    ports:
      - 9001:9001
      - 9002:9002
      - 9003:9003
      - 6753:6753
    environment:
      - NSOLID_CONSOLE_LICENSE_KEY=xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
    volumes:
      - /path/to/persistent/console:/var/lib/nsolid/console
     networks:
      - nsolid
networks:
  nsolid:

Note: The NSOLID_CONSOLE_LICENSE_KEY should be a valid license key not a JWT license token, you can see more information about license tokens here.

Downloading the Docker Images

To download the images using docker-compose, open a terminal in the directory where nsolid.yml is kept, and run:

$ docker-compose -f nsolid.yml pull

This will download all of the images needed to run the N|Solid console locally.

To download the images using docker, execute the following commands:

$ docker pull nodesource/nsolid-console

# Optional CLI
$ docker pull nodesource/nsolid-cli

Using the N|Solid Docker Images

Starting the N|Solid Console

With Docker Compose

To bring up the N|Solid Console, run the following command:

$ docker-compose -f nsolid.yml up

By default, this will bring up the N|Solid Console available on 127.0.0.1:6753.

With Docker

Though using docker-compose is our recommended approach for local development, the N|Solid console can be started with docker:

# start console
$ docker run -d -p 9001-9003:9001-9003 -p 6743:6753 \
  -v /path/to/persistent/console:/var/lib/nsolid/console --name console  \
  --network docker_nsolid \
  nodesource/nsolid-console

This will bring up the N|Solid console available on localhost:6753.

Make sure you have a Docker network to link your containers, you can create one with:

$ docker network create docker_nsolid

Visit the docker docs) for more information on Docker container networking.

Creating an Example Docker Application

Create a file called server.js:

// server.js

var http = require('http');
var hostname = require('os').hostname();
var port = process.env.PORT || 8888;

var server = http.createServer(function handleRequest (request, response) {
  response.end('[' + hostname + '] Serving requests from myapp. Request URL:' + request.url);
});

server.listen(port, function () {
  console.log('Server listening on port', port);
});

Create a file called Dockerfile:

# Dockerfile

FROM nodesource/nsolid

COPY server.js /server.js

EXPOSE 8888

CMD ["nsolid", "/server.js"]

Build docker image:

$ docker build -t example .

Starting Example Application with Docker Compose

Create the file docker-compose.yml in the directory along-side nsolid.yml:

# docker-compose.yaml

version: "2"
services:
  example:
    image: example
    container_name: nsolid.example
    ports:
      - 8888:8888 # Port your application exposes
    environment:
      - NSOLID_APPNAME=example
      - NSOLID_COMMAND=console:9001
      - NSOLID_DATA=console:9002
      - NSOLID_BULK=console:9003
networks:
      - nsolid
networks:
  nsolid:

For the complete documentation on defining a service with docker-compose.yml, refer to the Docker project’s documentation page: https://docs.docker.com/compose/overview/.

At this point, you are ready to bring up your application using docker-compose:

$ docker-compose -f nsolid.yml -f docker-compose.yml up

Starting Example Application with Docker

Start your service:

# start and connect your application to N|Solid
$ docker run -d --name example -e 'NSOLID_APPNAME=example' -e 'NSOLID_COMMAND=console:9001' -e 'NSOLID_DATA=console:9002' -e 'NSOLID_BULK=console:9003' --network docker_nsolid example

Adding Your Own Application with Docker Compose

If you are new to Docker, follow the steps in our blog post to get your application into a Docker container.

Your Dockerfile should begin with the following line:

#Dockerfile

FROM nodesource/nsolid

Congratulations, you are now up and running with N|Solid and Docker!

Using N|Solid

CPU Profiling

CPU Profiling allows you to understand where opportunities exist to improve the speed and load capacity of your Node processes.

Analyzing the Function Call Stack

Generated CPU profiles can be used to indicate all of the functions on the function call stack. For instance, if a function foo() calls a function bar() during its execution, and a sample was taken while bar() was running, the function call stack will show that foo() called bar(). Because multiple samples may be taken while bar() is executing, there will be an approximate start and stop time recorded for bar(), which is an indication of how long it took to run. In addition, further samples before and after the ones that captured bar() will capture foo(), and likewise to the bottom of the function call stack.

This data can then be analyzed to show, for the function foo(), how much time was actually spent in foo() and not in bar(). Every function has two time values, a self time and a total time. For the foo() and bar() case, if foo() only calls the bar() function, then the self time for foo() plus the total time for bar() will equal the total time for foo():

function foo() {
        … processing that takes a lot of time but calls no other functions ...
    bar()
        … processing that takes a lot of time but calls no other functions …
}

function bar() {
    …
}

foo() total time = foo() self time + bar() total time

Note: Total time shows you which functions are fastest and slowest, from start to finish, but does not definitively tell you if the time was spent in that function or other functions.

Named Functions

Named functions are easier to spot in CPU profiles. The stack frame entries available in a CPU profile include the name of a function, and source code location information for detail views. For anonymous functions, the name will often be displayed as "(anonymous)". In some cases, the V8 JavaScript engine can calculate an "inferred name" for a function. When possible, name functions so that they can be easily spotted in a CPU profile.

For instance, a function busyFunction(), which you like to easily track the callers for, is being called from an anonymous function:

setInterval(function(){busyFunction()}, 1000)

In a CPU profile, you'll see that busyFunction() is being called by (anonymous).

To make this easier to spot in a CPU profile, you can simply use:

setInterval(function busyFunctionCaller(){busyFunction()}, 1000)

In the CPU profile, you'll now see that busyFunction() is called by busyFunctionCaller().

For additional code cleanliness and clearer profiling, consider moving the entire function out into the same scope as the function usage:

setInterval(busyFunctionCaller, 1000)
//...
function busyFunctionCaller() {
  busyFunction()
}

Because JavaScript functions are "hoisted" to the top level of the scope they're defined in, you can reference busyFunctionCaller before it is actually defined.

Analyzing Profiles Using the N|Solid Console

The N|Solid Console allows you to generate and analyze profiles in one action. This is particularly useful if you need to take a series of profiles, as it avoids the overhead of switching between environments. The console also saves a profile history, simplifying navigation between profiles when troubleshooting.

  1. Launch the console and select the process of interest. "All applications"
  2. On the process details page, click the New CPU Profile button. "New profile"
  3. Select your profile window (5 to 60 seconds) and desired visualization style and run profile. "Run profile"
  4. N|Solid Console will pop up a green notification bar across the top of the screen when the profile is complete. Click it to view your new CPU profile. "Call stack"

For convenience, profiles are saved in your console session so you can easily flip between profiles. If your application ends before the profile is complete, N|Solid will try to save the profile data generated so far. If it is able to do so, your profile will be viewable under the Assets tab of the process detail page.

Visualizations Explained

All of the visualizations available for profile data show the unique set of stack traces captured during the profile, with the "area" of the stack indicating the proportional time spent in a function compared to that of its parent.

The Flame Graph visualization shows the time along the x-axis. The y-axis is used to show the function calls that make up a particular stack trace.

The Sunburst visualization is like the Flame Graph, where the x-axis is curved into a circle. Stack traces grow from the center to the outer parts of the graph.

The Treemap visualization shows time by area. The larger the rectangle, the more time a function took. The stack traces grow from the outer boxes into the inner boxes.

You can use the visualizations to find long-running functions. These can be identified by:

  • wide rectangles in the Flame Graph
  • long radial sections in the Sunburst
  • large areas in the Treemap

The stack trace height - how many functions deep a particular stack trace went - does not necessarily indicate a time issue. Focus on interpreting the time values as discussed above.

As you hover over the visualization itself, the function tied to the visualization will be shown. Clicking will show a stack trace to the right of the visualization. Other areas in the visualization may "light up" with a less bright color as you hover over the visualization - these are entries in stack traces for the same function and indicate additional CPU usage for the function under the cursor.

When analyzing CPU profiles with the N|Solid Console visualizations, pay careful attention to stack trace entries that take up the most area. This is displayed as a factor of width in the Flame Graph, circumference in the Sunburst, and area in the Treemap.

Analyzing Profiles Using N|Solid and the Chrome Profiler

You can also view the generated CPU profile in Chrome Dev Tools:

  1. Click the Download Profile button on the left side of the screen
  2. Open the Chrome web browser
  3. Open Chrome Dev Tools from the menu View / Developer / Developer Tools
  4. When the Developer Tools open, select the Performance tab
  5. Click the Load Profile Button (⇧), 4th from the left in the upper left corner
  6. Find the .cpuprofile file that was downloaded, and click the Open button
  7. A CPU profile chart will appear in the Performance tab
  8. Below it you will be able to view Summary, Bottom Up, and Call Tree views by selecting the respective tab header

The CPU profile chart shows function execution times and what functions were on the stack at the time the system was sampled.

Profiling Using the Command Line Interface (CLI)

N|Solid's Command Line Interface (CLI) is a great way to quickly pull profiles from remote processes for local examination. You can learn more about the profile command in the N|Solid Command Line Interface (CLI) reference.

Profiling Using the N|Solid Node API

The N|Solid Node API provides an efficient way to trigger a CPU Profile programmatically from within your application and have the resulting profile saved to your N|Solid console. The profile duration can be up to 600000 milliseconds, which is the default if none is specified.

const nsolid = require('nsolid')
nsolid.profile(durationMilliseconds, err => {
  if (err) {
    // The profile could not be started!
  }
})

To complete your profile before the duration expires, call profileEnd:

nsolid.profileEnd(err => {
  if (err) {
    // Error stopping profile (was one running?)
  }
})

Filtering and Tagging

Tags

You can use the NSOLID_TAGS environment variable to add tags that will be applied to a process. This can aid in identification and filtering, particularly when creating Saved Views in N|Solid Console. Tags can also be retrieved using the info command in the N|Solid CLI.

Setting Tags

$ NSOLID_APPNAME="leaderboard" NSOLID_TAGS="DC, us-east-1" nsolid app

Retrieving Tags

$ nsolid-cli info --q app=leaderboard

Example JSON Response

{
  "id": "57234c38b3f08dd8a3e9a567c82887a552c27b01",
  "app": "leaderboard",
  "tags": [ "DC", "us-east-1" ],
  "pid": 2440,
  ...
}

Tag Constraints

  • Tags can contain any whitespace characters
  • Tags are trimmed, so only whitespace in the middle of a tag is kept intact
  • Tags cannot contain commas and commas cannot be escaped
  • Tags are transmitted exactly the way they are entered and therefore are case sensitive, i.e. world is different than wOrld
  • The byte length of a tag must be between 2 and 140
  • There is no minimum number of tags per process
  • There is a maximum of 20 tags per process allowed
  • Tags cannot be changed at runtime

Filtering

As many applications are comprised of tens to thousands of processes, it is often necessary to be able to filter a subset based on some criteria. The N|Solid Console offers a filtering mechanism with auto-complete to help you navigate your complex applications.

"Filter Search"

Filters

Typing just the filter name will list all of the items for that filter. Subsequent characters are then used to find partial matches within that filter.

"Supported Filters"

Here are the currently supported filters in the N|Solid Console:

Filter Name Description
host Hostname(s) for the selected application's processes
name Application name as specified by NSOLID_APPNAME
pid Process IDs (pids)
tag Custom process tags (if any) as specified by NSOLID_TAGS
title Process title(s)

You may enter multiple filters and search terms in the filter box. Multiple terms will be logically AND'ed together when they are applied to the set of processes being filtered.

Heap Snapshots

When faced with a memory leak or performance issue, taking heap snapshots is a great way to help identify the underlying problem. N|Solid provides several ways to capture snapshots: the N|Solid Console, the N|Solid CLI, and the N|Solid Node API.

Analyzing Heap Snapshots

Heap Snapshots capture a record of all live JavaScript objects in your Node application available at the time the snapshot is captured. The objects are grouped by their constructor name, with aggregated counts of the total number of objects, their shallow size, and their retained size as columns in the Constructors view.

Shallow Size indicates the amount of space the object uses for its own properties. For instance, an object with no properties will have a very small shallow size, where an object with a number of properties will have a larger shallow size.

Retained Size indicates the amount of space the object is referencing, and keeping from being garbage collected.

From the Constructors view of the snapshot, you can sort by constructor name, number of objects, shallow size, and retained size. The list can also be filtered by constructor name.

You can use the number of objects value to look for the objects that are leaking, and you can use the retained size value to look for objects referencing those leaking objects.

In cases where you are leaking objects - and thus consuming more memory than you should be - sorting by number of objects and by retained size can provide a good indication of where to look for the cause of the leak. A large number of objects of a particular type may be an indication that these objects are still being referenced by other objects, when they could be garbage collected. A large retained size may be an indication that these objects are referencing more objects than they should be, keeping them from being garbage collected.

Taking Heap Snapshots with the N|Solid Console

Using the N|Solid Console, take a series of snapshots and quickly switch between them to better identify problematic areas:

  1. Launch the console and locate the Processes list on the right. "All applications"
  2. Click the process ID of the process of interest, and click New Heap Snapshot from the Process Detail view. "New snapshot"
  3. Once the snapshot completes, a green alert will pop up on the page. Click View Snapshot to see the results, and navigate through the various objects indexed during the snapshot process. To navigate a large number of indexed objects, you can use the Search Constructors search box to narrow the results.
  4. Snapshots taken in the N|Solid Console can be downloaded to your local drive for exploration via a 3rd party tool (i.e. Chrome Developer Tools). If you wish to download the snapshot for analysis through other tools, simply click Download on the right.
  5. If you want a particular snapshot to be saved and prevented from being deleted automatically, click Save to mark it for retention.

Taking Heap Snapshots from the Command Line Interface (CLI)

N|Solid's Command Line Interface (CLI) is a great way to quickly take heap snapshots from remote processes for local examination. You can learn more about the snapshot command in the N|Solid Command Line Interface (CLI) reference.

Heap Snapshots Using the N|Solid Node API

Use the N|Solid Node API to programmatically create a heap snapshot from within your application. The resulting snapshot(s) can be saved to your N|Solid Console.

const nsolid = require('nsolid')
nsolid.snapshot(err => {
  if (err) {
    // The snapshot could not be created!
  }
})

Best Practices

Using constructors will show class names in heap snapshots. Since the heap snapshot groups objects by constructor name, if at all possible you should use named constructors for objects you would like to track, as opposed to using literal objects. Literal objects will be aggregated under the Object constructor name.

For instance, the following code snippet creates objects which will be categorized under the Object constructor:

trackableObject = {x: "some value", y: "another value"}

To be able to track trackableObject in a snapshot, make it an instance of a specifically named class:

trackableObject = new TrackableObject()
trackableObject.x = "some value"
trackableObject.y = "another value"
// ...
function TrackableObject() {}

You'll then see these objects grouped by themselves in the heap snapshot.

For more of an "inline" feel, you can enhance your constructor to take initialization values:

trackableObject = new TrackableObject({x: "some value", y: "another value"})
// ...
function TrackableObject(initialValue) {
  this.x = initialValue.x
  this.y = initialValue.y

With EcmaScript 6 parameter destructuring, you can make it a little shorter:

trackableObject = new TrackableObject({x: "some value", y: "another value"})
// ...
function TrackableObject({x, y}) {
  this.x = x
  this.y = y
}

You can also make the constructor open-ended regarding the properties:

trackableObject = new TrackableObject({x: "some value", y: "another value"})
// ...
function TrackableObject(initialValue) {
  for (var key in initialValue) {
    this[key] = initialValue[key]
  }
}

Saved Views

A Saved View is a graph defined by a search query. Saved views allow you to view processes that fulfill certain parameters and to instruct N|Solid to take certain actions (such as taking heap snapshots, CPU profiles, or sending webhooks) when one or more processes cross over performance thresholds or match query parameters that you set.

Performance problems often occur in production code non-deterministically, and the only diagnostics available are an error log or possibly a stack trace. With N|Solid's saved views, you can automatically capture critical information when problems arise in production.

Creating a Saved View with N|Solid Console

  1. Click Processes in the Nav Bar to get to the Processes view. The default view shows all processes connected to N|Solid Console.

  2. To create a saved view, enter some query parameters and values into the filter search bar. Clicking on the bar will display a partial list of query terms. Type to begin searching for the parameter you wish to use. Click on one of the terms to select an operator and value.

  1. Click Set Filter to save this search term to your active filter. Repeat this process until your filter is set up as desired with all of your required search terms.

  2. When the filter has been named and saved, it will become available in the View dropdown selector.

Configuring Actions and Notifications

  1. The first step in configuration notifications is to create some integrations on the Slack, Webhooks, and Email Integrations page.

  2. Navigate to the Processes view and select a saved view from the dropdown menu. If you have never created a saved view before, you might see the default All Processes view. Actions and notifications can't be added to the All Processes view, so create a new saved view.

  3. Click the gear icon to the right of the saved view name.

  1. Select one or more actions or notification integrations, if desired. These will run on each process that matches the saved view filter.

Note: Be careful about setting a very high value on your saved view's filter expression, such as 99% Heap, and then selecting an action that uses the same resource, such as Take Heap Snapshot. Taking an intensive action at a very high ceiling is likely to negatively impact your application.

Security Vulnerabilities

The N|Solid Console can be configured to perform periodic verification of all packages loaded by all N|Solid processes. All loaded packages are verified against a list of known vulnerabilities.

When new vulnerabilities are found, information about each vulnerability will be reported in the Console. Notification options can also be configured to streamline reporting.

Detecting Security Vulnerabilities

The Security View

If there are any vulnerabilities found in your applications, the Security link in the Nav Bar will be annotated with a numbered badge indicating the number of vulnerabilities found across all of your applications.

image

Clicking on Security in the Nav Bar will display the Security view. This view displays a list of all the vulnerabilities found across all applications.

image

All of the vulnerabilities found in all applications will be listed on the left. The numbered badge in that list indicates the number of applications which are affected by the vulnerability. Clicking on a vulnerability in the list will display more details about that vulnerability. The Affected Processes tab will display information about the processes which are affected.

image

The Affected Processes subview contains an entry for every application affected by the vulnerability. By clicking on the disclosure triangle next to the application name, a list of the module dependencies for the vulnerable package is displayed.

image

You can use the Hide/Show toggle on the right to have the vulnerability ignored when determining the number of vulnerabilities across all the applications.

Vulnerable Processes in the Processes View

From the Processes view, you can sort the Process list on the right by Vulnerabilities, which will sort the currently filtered processes into two sets - Vulnerable and Secure.

image

The vulnerable processes will be shown with a bright red dot in the scatterplot, and secure processes will be shown with a light colored dot in the scatterplot. Clicking on the process in the Process list will display the Process Details view, which contains additional vulnerability information.

Vulnerability Information in the Process Details View

The Process Details view contains a Modules subview, which contains information about the vulnerabilities found in the process. Clicking on the vulnerability title will display the Security view for the vulnerable module.

image

Configuring Notifications for Security Vulnerabilities

You can configure the N|Solid Console to notify you when new vulnerabilities are found in your applications. To configure these notifications, click the Global Notifications link on the left side of the Settings view.

image

Scroll down to the section Vulnerability Notifications. Here you can add Integrations to be invoked when a new vulnerability is found.

image

Integrations (Slack, Webhooks, and Emails)

You can enable Saved Views, Vulnerabilities and global event notifications as Slack messages, invoked webhooks, or emails.

Slack Integration

To configure notifications to use Slack incoming messages, you will need to create a Slack Incoming Webhook. From the Slack Incoming Webhooks New Configuration page, select a channel the messages should be posted to, and then click the Add Incoming Webhooks Integration button. This will take you to a page where the Webhook URL is displayed, and you can further configure the message to be sent.

Copy the webhook URL displayed on that page. In the N|Solid Console, click Settings and choose Integrations from the left side menu. Paste the Slack webhook URL into the form and name the new integration. Once you have saved this integration, you will be able to attach it to global events, vulnerabilities, and saved views as a notification.

Examples

Below are examples of typical saved view and vulnerability notifications sent as incoming Slack messages.

Process Event Loop Blocked

Saved View Entered

Vulnerability Detected

Webhook Integration

You can also have notifications sent as HTTP POST messages to a webserver you manage. As the messages are sent to your server, you can run your own customized code to handle the notification.

Notification data is sent in the HTTP request as a JSON object in the body of the request. The HTTP request will be sent with the Content-Type header set to application/json.

In the N|Solid Console, click Settings and choose Integrations from the left side menu. Paste your webhook URL into the form and name the new integration. Once you have saved this integration, you will be able to attach it to global events, vulnerabilities, and saved views as a notification.

Events

The data the webhook receives has an event property. The value of this property will change depending on the event that prompts the notification. The following events are supported.

Event Description
nsolid-saved-view-match An agent has entered a saved view. Additionally, the configured delay time period has passed, and this event has not fired in the time period specified by the snooze parameter
nsolid-agent-exit An agent that was connected is no longer connected to N|Solid Console
nsolid-snapshot-generated A heap snapshot has been generated. This could have been done manually or as a result of another event
nsolid-profile-generated A CPU profile has been generated. This could have been done manually or as a result of another event
nsolid-process-blocked A process has had its event loop blocked for at least the time period specified by the duration parameter
nsolid-vulnerability-detected A vulnerability has been detected for this process

Common Data

All notifications will include the following properties in the notification object and additional properties that may be specific to individual events.

Property Description
time ISO datetime string indicating when this event was triggered
event One of the event types, described above
agents A list of objects with properties described below
assets A list of assets like heap snapshots or cpu profiles that this event caused to be created
config The notifications config that caused this notification to be sent

The property named agent will be an object with the following properties:

Property Description
id The agent id
info Information about this agent including tags, app name, and hostname
metrics The latest metrics information we have from this agent, if any

In addition to the data specified above, some events may contain additional information.

Agent Exit

Agent exit events will include the exit code of the process. If the there was a stack trace associated with an abnormal exit, that stack trace will also be included.

Event Loop Blocked Data

The value of the event property in the notification object will be nsolid-process-blocked.

The notification object will include an additional property named stacktrace, whose value is a string version of the stack trace being executed when the event loop was blocked.

Vulnerability Event Data

The value of the event property in the notification object will be nsolid-vulnerability-detected.

The notification object will include an additional property named vulnerability, whose value is a list of vulnerabilities for this process. The new vulernability whose discovery triggered this event will have a new property with the value true.

Email Notifications

In N|Solid Console, click Settings and choose Integrations from the left side menu. Enter one or more email addresses and name the new integration. Once you have saved this integration, you will be able to attach it to global events, vulnerabilities, and saved views as a notification.

N|Solid in the cloud

AWS Quick Start Guide

This guide provides step-by-step instructions for deploying N|Solid on the Amazon Web Services (AWS) cloud. We offer custom N|Solid AMIs on the AWS Marketplace to simplify the process.

Installing N|Solid Console

  1. Log in to the AWS Marketplace at http://aws.amazon.com/marketplace.
  2. Open the N|Solid Console - AMI page and choose Continue.
  3. Review the settings and read the terms and conditions for software usage, and then click Launch with 1-click.
  4. Open AWS Management Console and wait for the instance to be in a running state.
  5. Once running, open the Public DNS or Public IP in a web browser. You will be prompted for a username and password. nsolid is the username, and the password is the Instance ID.

Setting up N|Solid Console

Complete the AWS activation screen.

N|Solid AWS start screen

Once completed, you should be immediately redirected to the N|Solid console.

N|Solid Console Up and Running

Running Node Applications in N|Solid

ssh into the machine as ubuntu user.

NSOLID_COMMAND=localhost:9001 \
NSOLID_DATA=localhost:9002 \
NSOLID_BULK=localhost:9003 \
NSOLID_APPNAME="My_Application" node app.js

You can customize the name of your application in the N|Solid Console by changing the NSOLID_APPNAME environmental variable. If you do not specify an app name, N|Solid will look for a name property in your package.json, and if that is not found, your application name will default to "untitled application".

You are now ready to use N|Solid for your own applications!

Creating Instances of the N|Solid Runtime

  1. Log in to the AWS Marketplace at http://aws.amazon.com/marketplace.
  2. Open the N|Solid Runtime Carbon - AMI page and choose Continue.
  3. Review the settings and read the terms and conditions for software usage, and then click Launch with 1-click.
  4. Open AWS Management Console and wait for the instance to be in a running state.
  5. Utilize the Public DNS or Public IP of the N|Solid Console instance to start your application.
NSOLID_COMMAND=<NSOLID_CONSOLE_IP>:9001 \
NSOLID_DATA=<NSOLID_CONSOLE_IP>:9002 \
NSOLID_BULK=<NSOLID_CONSOLE_IP>:9003 \
NSOLID_APPNAME="My_Application" node app.js

Configuration of N|Solid Console

Process Management

  • Nginx: /etc/init.d/nginx
  • N|Solid Console: /etc/init.d/nsolid-console

Nginx

The configuration for the external proxy is located at /etc/nginx/sites-enabled/nsolid-nginx.conf if you want to change the default login credentials.

N|Solid Console

The default configuration file is located at /etc/nsolid/console-config.toml will all artifacts stored at /var/lib/nsolid/console.

Microsoft Azure Quickstart Guide

This guide provides step-by-step instructions for deploying N|Solid on the Microsoft Azure cloud. You can find N|Solid on the Azure Marketplace, allowing quick, easy, and customized deployments of N|Solid directly to your Azure-based cloud.

Installing the N|Solid Console from the Azure Marketplace

  1. Login to the Microsoft Azure Portal.
  • If you don't already have a Microsoft account, you can create one for free.
  1. Access Marketplace, as seen on the dashboard.
  • The Marketplace can also be accessed from the search bar at any time.

  Once in the Azure Marketplace, you will be able to search for - and deploy - the N|Solid Console and Runtime directly to Azure.

  1. Search the Azure Marketplace for nsolid.
  2. Select the N|Solid Console from the search results.
  • Click the Create button to create a new virtual machine (VM) with the N|Solid Console.
  1. Fill in the required fields, and customize optional fields to your desired specifications.
  • Name
  • Username
  • Authentication Type
  • Resource Group
  1. Select a VM Size
  • We suggest DS3_V2 or larger VMs for production usage.
  1. Once “N|Solid Console” is up and running, open the IP address in a browser.
  • You will be prompted to access it with Basic Auth.
  • The default username is nsolid and the default password is nodesource.

Note: The configuration for the external proxy that provides the basic authentication is located at /etc/nginx/sites-enabled-nsolid-nginx.conf in the N|Solid Console instance. If you'd like to change the default login credentials (we highly suggest you do), you can do so there.

The N|Solid Console should be up and running! You will be prompted for an N|Solid License key. If you do not have one, you can request one be sent by email. Read the Quick Start Guide for more instruction on getting started with the Console.

Creating Instances of the N|Solid Runtime

To start running your apps with N|Solid, you will need to start VMs with instances of the N|Solid Runtime. To create instances of the N|Solid Runtime, you can follow the same process you did for the N|Solid Console in the Azure Marketplace:

  1. Search the Azure Marketplace for nsolid.
  2. Select the N|Solid Runtime from the search results.
  • Click the Create button to create a new VM with the N|Solid Runtime.
  1. Fill in the required fields, and customize optional fields to your desired specifications.
  • Name
  • Username
  • Authentication Type
  • Resource Group
  1. Select a VM Size
  • For the N|Solid Runtime, select whatever VM Size your application or project needs.

Note: It is likely you will want to use the same resource group as the “N|Solid Console” instance.

The N|Solid Runtime instances are Linux machines that have the bare essentials for running Node.js. If there is additional tooling you need for your application, you can SSH into the machine and install it as needed.

Connecting the N|Solid Runtime to the N|Solid Console on Azure

To connect an N|Solid Runtime to your N|Solid Console, SSH into your N|Solid Runtime instance, and run the following commands:

NSOLID_COMMAND={nsolid_console_ip_address}:9001 \
NSOLID_DATA={nsolid_console_ip_address}:9002 \
NSOLID_BULK={nsolid_console_ip_address}:9003 \
NSOLID_APPNAME="My Application Name" node app.js

In the above code block, you will need to replace {nsolid_console_ip_address} with the IP address of your N|Solid Console. You will also want to replace "My Application Name" with the name of your application, as you want it to be displayed in the N|Solid Console.

You can connect multiple N|Solid Runtimes to your N|Solid Console, enabling you to monitor all your Node.js deployments from a single dashboard.

Configuration of N|Solid Console

Process Management

  • Nginx: /etc/init.d/nginx
  • N|Solid Console: /etc/init.d/nsolid-console

Nginx

If you want to change the default login credentials, the configuration for the external proxy is located at /etc/nginx/sites-enabled/nsolid-nginx.conf.

N|Solid Console

The default configuration file is located at /etc/nsolid/console-config.toml and will configure all artifacts stored at /var/lib/nsolid/console.

GCP Quick Start Guide

This guide provides step-by-step instructions for deploying N|Solid on the Google Cloud Platform (GCP) cloud. Cloud Launcher uses GCP Deployment Manager to configure, launch, and run the GCP compute engine, network, storage, and other services required to deploy a workload on GCP.

Install N|Solid on GCP with Google Cloud Launcher

  1. Locate N|Solid in the Google Cloud Launcher and click Launch on Compute Engine.

N|Solid GCP locate screen

  1. Details for your new N|Solid deployment will be displayed. Adjust settings to your desire and click Deploy.

N|Solid GCP setup screen

  1. Wait for setup to complete.

N|Solid GCP pending screen

  1. Click the Log into the N|Solid Console button and provide the username and password listed.

N|Solid GCP complete screen

Setting up N|Solid Console

  1. Complete the Activate Optional Features form to enable GCP activation.

N|Solid GCP start screen

  1. Once completed, you should be redirected to the N|Solid console.

N|Solid Console Up and Running

Running Node Applications with N|Solid

ssh into a runtime machine.

NSOLID_COMMAND=<NSOLID_CONSOLE_IP>:9001 \
NSOLID_DATA=<NSOLID_CONSOLE_IP>:9002 \
NSOLID_BULK=<NSOLID_CONSOLE_IP>:9003 \
NSOLID_APPNAME="My_Application" node app.js

You can customize the name of your application in the N|Solid Console by changing the NSOLID_APPNAME environmental variable. If you do not specify an app name, N|Solid will look for a name property in your package.json, and if that is not found, your application name will default to "untitled application".

You are now ready to use N|Solid for your own applications!

Configuration of N|Solid Console

Process Management

  • Nginx: /etc/init.d/nginx
  • N|Solid Console: /etc/init.d/nsolid-console

Nginx

If you want to change the default login credentials, the configuration for the external proxy is located at /etc/nginx/sites-enabled/nsolid-nginx.conf. See Configuring SSL for adding security to N|Solid Console.

N|Solid Console

The default configuration file is located at /etc/nsolid/console-config.toml, with all artifacts stored at /var/lib/nsolid/console.

Advanced Topics

Command Line Interface (CLI)

Table of Contents

Options

N|Solid comes with a set of predefined endpoints for interaction and introspection that can be accessed at the command-line using the N|Solid Command Line Interface, nsolid-cli.

The N|Solid CLI tool mirrors the Console's API schema. Many options are documented below. For commands not documented here, consult your Console's API Docs at http://localhost:6753/api/v3/api-docs (replace localhost:6753 with your Console server's address.)

To see a list of help information for nsolid-cli, use the -h option:

$ nsolid-cli -h

The output of the nsolid-cli commands, unless otherwise noted, is line-delimited JSON (each line is separated by a newline delimiter \n). The output shown in the examples below is expanded for readability.

--start and --end options

For commands that take --start and --end options, you can pass the following formats for the date/time value:

Format Description
milliseconds since epoch Value returned from Date.now()
yyyy-mm-ddThh:mm:ss ISO date
-Ns N seconds since now
-Nm N minutes since now
-Nh N hours since now
-Nd N days since now
0 Now, when used with the --end option

--q option

Some commands take a --q parameter followed by a query filter expression. Only results matching all query filter terms will be returned.

A filter term is a string with no spaces separating the values.

"field+operator+value"

The field may be any field from info or metrics, or vulns, vuln, or package. See the output of those commands to see what options exist for the field portion of the query.

The operators for each field type are described below.

The value can be a single value or a list of values separated by ,. The term will evaluate to true if the field and operator match any of the specified values. Values may escape any character by preceding it with the % character. In practice, the only characters that need to be escaped are %, (space), and ,.

A query filter expression is a list of filter terms, separated by space characters.

Here is an example showing the list command being passed the --q flag with a query filter expression that has two filter terms:

$ nsolid-cli list --q "vulns>=2 package=express"

String Operators

Operator Description
"=" Evaluates to true if the field value is equal to any value in the expression
"!=" Evaluates to true if the field value is not equal to any value in the expression
"~" Evaluates to true if the field value wild-card matches any value in the expression
"!~" Evaluates to true if the field value does not wild-card match any value in the expression

Note that multiple string values may be specified in the expression, separated by commas.

Number Operators

Operator Description
"<" Evaluates to true if the field value is less than the value in the expression
"<=" Evaluates to true if the field value is less than or equal to the value in the expression
">" Evaluates to true if the field value is greater than the value in the expression
">=" Evaluates to true if the field value is greater than or equal to the value in the expression

Package Operators

Operator Description
"=" Evaluates to true if the field value equals the value in the expression
"!=" Evaluates to true if the field value does not equal the value in the expression
"<" Evaluates to true if the field value is less than the value in the expression
"<="" Evaluates to true if the field value is less than or equal to the value in the expression
">" Evaluates to true if the field value is greater than the value in the expression
">=" Evaluates to true if the field value is greater than or equal to the value in the expression

A value for packages fields is either package name or {package name}@{simple-semver-range}, where a simple semver range is one of:

Semver Ranges

Type Examples
X-ranges 1.2.3, 1.2, 1.2.x, 1.x, 1.2.*, etc.
Tilde ranges ~1.2.3, ~1.2, etc.
Caret ranges ^1.2.3, ^1.2, etc.

Using the < and > operators will do a semver range check comparing the versions.

asset

Download an asset.

Option Description
--id The asset id (required)

Usage

$ nsolid-cli asset --id 217040c0-02d1-4956-8648-7fb84b78c65e > my.heapsnapshot

Asset IDs are available via the assets command described below. The asset file itself will be written to stdout. The N|Solid CLI tool will automatically manage decompression if the asset is compressed.

assets

Lists the assets (CPU profiles and heap snapshots) that are currently available for download.

Option Description
--id The agent id or agent id prefix
--app The NSOLID_APP value
--hostname The host the process is running on
--tag An NSOLID_TAGS value (may be specified multiple times)
--type One of snapshot, snapshot-summary, or profile to limit the type of asset returned
--start Return assets that were created after the specified time
--end Return assets that were created before the specified time
--starred Return only assets that have been starred

Usage

$ nsolid-cli assets --app my-app-name --type snapshot

Returns a JSON stream including the following properties:

Property Description
time The timestamp of the asset completion
asset An asset id to use with the asset command
type profile, snapshot, or snapshot-summary
id The agent id
app The NSOLID_APP value
hostname The host the process is running on
tags The NSOLID_TAGS values
size The size of the asset in bytes
compressed Boolean value representing whether the asset will be served as a gzip
pid The operating system process id
title The process title
info The process info
metrics The process metrics nearest the time of collection
starred Boolean value representing whether the asset is starred or not

Example JSON Result

{
  "time": "2017-11-29T17:08:17.364Z",
  "asset": "3011f777-b8e0-4696-ae6c-50358bce298a",
  "type": "snapshot",
  "id": "272470293ef95e530b1d9d072e6ed87e0c980173",
  "app": "my-app-name",
  "hostname": "my-computer.local",
  "tags": [
    "region:north",
    "zone:A"
  ],
  "size": 4288158,
  "compressed": true,
  "pid": 5940,
  "title": "my-app-name",
  "info": { ... },
  "metrics": { ... },
  "starred": false
}

async-activity

N|Solid can list any pending asynchronous operations and where the JavaScript callbacks will resume. This can be extremely helpful for determining how many concurrent operations a given N|Solid process is handling and what they are. It can also be useful in determining where an application is hanging, if there are any left-behind callbacks, or where there is a misuse of resources (e.g. reading the same file repetitively).

The output will list the in-flight asynchronous activity, including the function location and line of source code to reference where the callback will resume.

Option Description
--id The agent id or agent id prefix

Usage

$ nsolid-cli async-activity --id 5dd6f7a

Returns a JSON stream including the following properties:

Property Description
handles An array of async operations. Usually longer-lived, larger-scale asynchronous operations, such as open sockets or timers
requests An array of async operations. Usually shorter-lived, smaller-scale operations such as writing to file handles and other file-related operations
pending An array of async operations. Represents async activity that is lower level. Often activity created by code inside Node.js core, like DNS lookups, signal handlers and TCP connections

Example JSON Result

{
  "handles": [
    {
      "name": "onrequest",
      "location": {
        "file": "nsolid-user/server-http.js",
        "line": 3,
        "column": 19,
        "inferredName": ""
      },
      "anonymous": false,
      "code": "function onrequest(req, res) { res.end('ok\n') }",
      "type": {
        "group": "handle",
        "flag": 4,
        "name": "TCP server connection"
      },
      "details": {
        "fd": 10,
        "transport": "TCP",
        "connectionKey": "6::::0",
        "connections": 0,
        "unrefd": false
      },
      "metadata": {
        "async_wrap_provider": "TCPWRAP",
        "async_wrap_providerKey": "15"
      }
    },
    {
      "type": {
        "group": "handle",
        "flag": 64,
        "name": "pipe socket"
      },
      "details": {
        "fd": 1,
        "transport": "Pipe",
        "bytesDispatched": 0,
        "hadError": false,
        "host": null,
        "pendingData": "<Buffer>"
      },
      "metadata": {
        "async_wrap_provider": "PIPEWRAP",
        "async_wrap_providerKey": "8"
      }
    },
    {
      "type": {
        "group": "handle",
        "flag": 64,
        "name": "pipe socket"
      },
      "details": {
        "fd": 2,
        "transport": "Pipe",
        "bytesDispatched": 57985,
        "hadError": false,
        "host": null,
        "pendingData": "<Buffer>"
      },
      "metadata": {
        "async_wrap_provider": "PIPEWRAP",
        "async_wrap_providerKey": "8"
      }
    }
  ],
  "requests": [
    {
      "name": "onreadFile",
      "location": {
        "file": "nsolid-user/server-http.js",
        "line": 14,
        "column": 20,
        "inferredName": ""
      },
      "anonymous": false,
      "code": "function onreadFile(err, src) {\n  if (err) return console.error(err)\n  readAgain()\n}",
      "type": {
        "group": "request",
        "flag": 4,
        "name": "readFile",
        "api": "fs.readFile(filename[, options], callback)"
      },
      "details": {
        "path": "nsolid-user/server-http.js",
        "flag": "r",
        "isUserFd": false,
        "buffers": [
          "<Buffer>"
        ],
        "buffer": "<Buffer>",
        "pos": 0,
        "encoding": null,
        "err": null
      },
      "metadata": {
        "async_wrap_provider": "FSREQWRAP",
        "async_wrap_providerKey": "3"
      }
    }
  ],
  "pending": [],
  "time": "2017-12-04T00:56:28.566Z",
  "id": "8ed04c57f248624c6068945b68a5f023497498cd",
  "app": "runtime/async-activity/03-server-http_app",
  "hostname": "ebc192f5fae2"
}

custom

Invoke a custom command. For more information on custom commands, see Custom Commands.

Option Description
--id The agent id or id prefix (required)
--name The name of the custom command (required)
--data Data to be sent with the command

Usage

$ nsolid-cli custom --id=[agent id] --name=verbose --data=off

Returns a JSON object with the following properties:

Property Description
time The timestamp recorded for the event
id The agent id
app The NSOLID_APP value
hostname The host the process is running on
tags The NSOLID_TAGS values
result The result of the custom command

Example JSON Result

{
  "time": "2017-12-04T00:56:28.566Z",
  "id": "81535293aea1fe8c1e2f3f7518d8db3f96cf7b39",
  "app": "nsolid2",
  "hostname": "computer.local",
  "tags": [
    "localdev"
  ],
  "result": {
    "verbose": false
  }
}

events

Subscribe to the event stream, which emits a wide array of event types and metadata.

Usage

$ nsolid-cli events

There are many types of events, and more are added all the time. Some of the primary types are described below.

Event Type Description
license-updated The license data has been changed or verified with the license server
field-range-changed The range or option set for a field has expanded or contracted
agent-packages-added An agent's package list has been added or updated
agent-found A new agent has connected to the console
agent-exit An agent has terminated

Example JSON Result

{"time":"2017-12-04T01:47:16.386Z","event":"license-updated","args":{"licensed":true}}
{"time":"2017-12-04T01:47:17.905Z","event":"field-range-changed","args":{"domain":"metrics","name":"loopsPerSecond","range":[0,22]}}
{"time":"2017-12-04T01:47:48.613Z","event":"agent-packages-added","agent":"21fdaca1fd8533465392697e3d305e1991808836","args":{"app":"my-app","hostname":"x1c","tags":[],"pid":27646}}
{"time":"2017-12-04T01:47:48.613Z","event":"agent-found","agent":"21fdaca1fd8533465392697e3d305e1991808836","args":{"app":"my-app","hostname":"x1c","tags":[],"pid":27646}}
{"time":"2017-12-04T01:47:53.087Z","event":"agent-exit","agent":"21fdaca1fd8533465392697e3d305e1991808836","args":{"app":"my-app","hostname":"x1c","tags":[],"pid":27646,"exitCode":0}}

events-historic

Extract the events from a range of time in the past.

Option Description
--id An agent id
--type An optional event type to only include
--start Return events that occurred after the specified time
--end Return events that occurred before the specified time

Usage

$ nsolid-cli events-historic --start "-2h" --end "-1h"

generate-keypair

Returns a randomly generated keypair suitable for use in the N|Solid Console socket configuration. If your N|Solid Console instance is running on an untrusted network, it is recommended that you generate and use new keys.

Usage

$ nsolid-cli generate-keypair

Returns a JSON object with the following properties:

Property Description
public Public key value. publicKey in N|Solid Console configuration, and env variable NSOLID_PUBKEY for N|Solid Runtime
private Private key value. privateKey in N|Solid Console configuration

Example JSON Result

{
  "public": "[t&m}{EZH7=HR(IW:+Ttk:=r.Y$:CP+-Q&5L?2N!",
  "private": "4QZof={^Pman?I?mB0o!]%z/{Jlu6:mJfl[Ms@[^"
}

info

Returns objects which contain static information about processes and the hosts they are running on.

Option Description
--id The full or partial agent id
--q The query options (see above)

Usage

$ nsolid-cli info

Returns a JSON stream including the following properties:

Property Description
time Milliseconds since epoch time message was sent
id The agent id
app The NSOLID_APP value or name property from package.json
appVersion The version property from package.json
hostname The host the process is running on
tags The NSOLID_TAGS values
pid Operating system process id
processStart The time the process started
execPath Path of the executable running the application
main The main module used when the application started up
arch The CPU architecture
platform Name of the N|Solid platform
totalMem Total available memory in the system
cpuCores The number of CPU cores
cpuModel The CPU model
versions Object describing the versions of components used in the runtime

Example JSON Result

{
  "id": "5dd6f7a940bfc3633cc3ffc82332640d51ce5112",
  "app": "my-app-name",
  "appVersion": "1.0.0",
  "tags": [
    "region:north",
    "zone:A"
  ],
  "pid": 14880,
  "processStart": 1512335595061,
  "nodeEnv": "dev",
  "execPath": "/usr/bin/nsolid",
  "main": "/var/my-app/app.js",
  "arch": "x64",
  "platform": "linux",
  "hostname": "my-computer.local",
  "totalMem": 8244523008,
  "versions": {
    "http_parser": "2.7.0",
    "node": "8.9.1",
    "nsolid": "3.0.0",
    "v8": "6.1.534.47",
    "uv": "1.15.0",
    "zlib": "1.2.11",
    "ares": "1.10.1-DEV",
    "modules": "57",
    "nghttp2": "1.25.0",
    "openssl": "1.0.2m",
    "icu": "59.1",
    "unicode": "9.0",
    "cldr": "31.0.1",
    "tz": "2017b",
    "nsolid_lib": {
      "v8_profiler": "nsolid-v5.7.0-fix1",
      "sodium": "nsolid-2.1.0",
      "cjson": "nsolid-2.0.0",
      "function_origin": "nsolid-v1.2.1",
      "nan": "v2.5.1",
      "cli": "bryce/three-point-oh",
      "agent": "agent-3.0",
      "zmq-bindings": "nsolid-2.15.4-fix1",
      "zmq": "nsolid-v4.2.0-fix4",
      "persistents_with_classid": "v1.1.1"
    }
  },
  "cpuCores": 4,
  "cpuModel": "Intel(R) Core(TM) i7-5600U CPU @ 2.60GHz",
  "time": "2017-12-03T21:13:15.061Z"
}

list

Returns an array of all available matching N|Solid processes, along with their most recent info and metrics data. The command ls is an alias for this command.

Option Description
--q The query object (see above)

Usage

$ nsolid-cli list --q id=5dd6

Returns newline delimited JSON objects where each row includes the following properties:

Property Description
time The timestamp of the last metrics payload
info The object returned from the info command
metrics The object returned from the metrics command

Example JSON Result

{
  "time": "2017-12-04T01:17:31.299Z",
  "info": { ... },
  "metrics": { ... }
}

metrics

Subscribes to the metrics for a set of agents.

Option Description
--field A list of fields to include in the output. If unspecified, all fields will return
--interval How frequently to poll for metrics data
--q The query set (see above)

Usage

$ nsolid-cli metrics

Consult the Metrics in Detail section for complete details on the metrics available.

Example JSON Result

{
  "time": "2017-12-04T01:23:16.163Z",
  "id": "5dd6f7a940bfc3633cc3ffc82332640d51ce5112",
  "app": "my-app-name",
  "hostname": "my-computer.local",
  "tags": [
    "region:north",
    "zone:A"
  ],
  "activeHandles": 750,
  "activeRequests": 0,
  "blockInputOpCount": 0,
  "blockOutputOpCount": 19424,
  "cpuPercent": 0.2666424917029181,
  "cpuSpeed": 2640,
  "cpuSystemPercent": 0.13332124585145905,
  "cpuUserPercent": 0.13332124585145905,
  "ctxSwitchInvoluntaryCount": 9988,
  "ctxSwitchVoluntaryCount": 1795924,
  "dns99Ptile": 0,
  "dnsCount": 0,
  "dnsMedian": 0,
  "freeMem": 251301888,
  "gcCount": 446,
  "gcCpuPercent": 0,
  "gcDurUs99Ptile": 409,
  "gcDurUsMedian": 527,
  "gcForcedCount": 0,
  "gcFullCount": 0,
  "gcMajorCount": 54,
  "heapSizeLimit": 1501560832,
  "heapTotal": 73269248,
  "heapUsed": 60332056,
  "httpClient99Ptile": 0,
  "httpClientAbortCount": 0,
  "httpClientCount": 0,
  "httpClientMedian": 0,
  "httpServer99Ptile": 0,
  "httpServerAbortCount": 0,
  "httpServerCount": 0,
  "httpServerMedian": 0,
  "ipcReceivedCount": 0,
  "ipcSentCount": 0,
  "load15m": 0.2333984375,
  "load1m": 0.2265625,
  "load5m": 0.28564453125,
  "loopAvgTasks": 0,
  "loopEstimatedLag": 0,
  "loopIdlePercent": 100,
  "loopTotalCount": 713,
  "loopsPerSecond": 0,
  "pageFaultHardCount": 0,
  "pageFaultSoftCount": 132206,
  "rss": 138301440,
  "signalCount": 0,
  "swapCount": 0,
  "systemUptime": 23006,
  "title": "node",
  "totalAvailableSize": 1437491784,
  "totalHeapSizeExecutable": 5242880,
  "totalPhysicalSize": 72644376,
  "uptime": 15000.85,
  "user": "appuser",
  "vulns": 1
}

metrics-historic

Retrieve metrics records over a historical time range. Records match the metrics command output.

Option Description
--field A list of fields to include in the output. If unspecified, all fields will return
--q The query set (see above)
--start The start of the time range
--end The end of the time range
--series The aggregation level of the data. Can be raw, 1m, or 1h. Defaults to raw

Usage

$ nsolid-cli metrics-historic --start=-5m --end=-1m

packages

Returns a list of packages and modules available in the specified process.

Option Description
--id The full agent id or prefix

Usage

$ nsolid-cli packages --id=[agent id]

Returns a JSON object with the following properties:

Property Description
id The agent id
time The timestamp of the message
app The NSOLID_APP value
packages An array of package objects with details about the package and its dependencies
vulnerabilities An object with vulnerability details

Example JSON Result

{
  "id": "a40827afbc3620e40887d6774249c321848d54f6",
  "time": "2017-12-04T01:26:12.514Z",
  "packages": [
    {
      "name": "my-app-name",
      "version": "1.0.0",
      "path": "/var/my-app",
      "main": "app.js",
      "dependencies": [
        "node_modules/debug",
        "node_modules/minimist",
        "node_modules/split"
      ],
      "dependents": [],
      "vulns": []
    },
    {
      "name": "debug",
      "version": "2.2.0",
      "path": "/var/my-app/node_modules/debug",
      "main": "./node.js",
      "dependencies": [
        "../ms"
      ],
      "dependents": [
        "../.."
      ],
      "vulns": [
        "npm:debug:20170905"
      ]
    },
    {
      "name": "minimist",
      "version": "1.2.0",
      "path": "/var/my-app/node_modules/minimist",
      "main": "index.js",
      "dependencies": [],
      "dependents": [
        "../.."
      ],
      "vulns": []
    },
    {
      "name": "ms",
      "version": "0.7.1",
      "path": "/var/my-app/node_modules/ms",
      "main": "./index",
      "dependencies": [],
      "dependents": [
        "../debug"
      ],
      "vulns": [
        "npm:ms:20170412"
      ]
    },
    {
      "name": "split",
      "version": "1.0.0",
      "path": "/var/my-app/node_modules/split",
      "dependencies": [
        "../through"
      ],
      "dependents": [
        "../.."
      ],
      "vulns": []
    },
    {
      "name": "through",
      "version": "2.3.8",
      "path": "/var/my-app/node_modules/through",
      "main": "index.js",
      "dependencies": [],
      "dependents": [
        "../split"
      ],
      "vulns": []
    }
  ],
  "vulnerabilities": [
    {
      "package": "debug",
      "title": "Regular Expression Denial of Service (ReDoS)",
      "published": "2017-09-26T03:55:05.106Z",
      "credit": [
        "Cristian-Alexandru Staicu"
      ],
      "id": "npm:debug:20170905",
      "ids": {
        "NSP": 534,
        "CWE": [
          "CWE-400"
        ],
        "CVE": [],
        "ALTERNATIVE": [
          "SNYK-JS-DEBUG-10762"
        ]
      },
      "vulnerable": "<2.6.9 || >=3.0.0 <3.1.0",
      "severity": "low",
      "description": " ... ",
      "nsolidMetaData": {
        "hidden": false
      },
      "packages": [
        "/var/my-app/node_modules/debug"
      ],
      "depsChains": [
        [
          "nsolid-dev-demo@1.0.0",
          "debug@2.2.0"
        ]
      ],
      "topLevel": 1
    },
    {
      "package": "ms",
      "title": "Regular Expression Denial of Service (ReDoS)",
      "published": "2017-05-15T06:02:45.497Z",
      "credit": [
        "Snyk Security Research Team"
      ],
      "id": "npm:ms:20170412",
      "ids": {
        "CWE": [
          "CWE-400"
        ],
        "CVE": [],
        "ALTERNATIVE": [
          "SNYK-JS-MS-10509"
        ]
      },
      "vulnerable": "<2.0.0",
      "severity": "low",
      "description": " ... ",
      "nsolidMetaData": {
        "hidden": false
      },
      "packages": [
        "/var/my-app/node_modules/ms"
      ],
      "depsChains": [
        [
          "nsolid-dev-demo@1.0.0",
          "debug@2.2.0",
          "ms@0.7.1"
        ]
      ],
      "topLevel": 1
    }
  ]
}

profile

Generates a V8 CPU profile of the specified process.

Option Description
--id The agent id (required)
--duration Duration of profile in seconds. Default is 10 minutes

Usage

$ nsolid-cli profile --id=[agent id] > my.cpuprofile

Once the profile file has been created, it can be opened using Chrome’s Development Tool’s CPU Profile Debugging Tool.

Note: To load the file, Chrome requires that the generated file have the extension .cpuprofile.

snapshot

Generates a V8 heap snapshot of the specified process.

Option Description
--id The agent id (required)

Usage

$ nsolid-cli snapshot --id=[agent id] > my.heapsnapshot

Once the snapshot file has been created, it can be opened using Chrome’s Development Tool’s heap snapshot browser

Note: To load the file, Chrome requires that the generated file have the extension .heapsnapshot.

startup-times

Lists the time to reach certain process lifecycle startup phases from initial process execution.

Option Description
--id The full agent id or prefix

Usage

$ nsolid-cli startup-times

Returns a JSON stream including the following properties:

Property Description
time Milliseconds since epoch time message was sent
id The agent id
app The NSOLID_APP value
hostname The host the process is running on
initialized_node An array of two integers. The time it took to initialize the Node internals, reported as [seconds, nanoseconds]
initialized_v8 An array of two integers. The time it took to initialize the V8 engine, reported as [seconds, nanoseconds]
loaded_environment An array of two integers. The time it took to complete all initialization, which includes running some of Node's internal JavaScript code, and your main module's top-level code, reported as [seconds, nanoseconds]

Example JSON Result

{
  "loaded_environment": [
    0,
    322526338
  ],
  "initialized_node": [
    0,
    120919
  ],
  "initialized_v8": [
    0,
    240910
  ],
  "id": "5dd6f7a940bfc3633cc3ffc82332640d51ce5112",
  "time": "2017-12-04T01:32:30.042Z",
  "tags": [
    "region:north",
    "zone:A"
  ],
  "app": "my-app-name",
  "hostname": "my-computer.local"
}

Additional timers can be added to your application with custom lifecycle events.

vulnerabilities

Returns known security vulnerabilities for all processes.

Usage

$ nsolid-cli vulnerabilities

Returns a JSON object representing all current known vulnerabilities.

Property Description
time Message timestamp
vulnerabilities An array of vulnerability objects

Example JSON Result

{
  "time": "2017-12-04T01:34:54.805Z",
  "vulnerabilities": [
    {
      "report": {
        "package": "ms",
        "title": "Regular Expression Denial of Service (DoS)",
        "published": "2015-11-06T02:09:36.187Z",
        "credit": [
          "Adam Baldwin"
        ],
        "id": "npm:ms:20151024",
        "ids": {
          "CWE": [
            "CWE-400"
          ],
          "CVE": [
            "CVE-2015-8315"
          ],
          "NSP": 46,
          "ALTERNATIVE": [
            "SNYK-JS-MS-10064"
          ]
        },
        "vulnerable": "<=0.7.0",
        "severity": "medium",
        "description": " ... ",
        "nsolidMetaData": {
          "hidden": false
        }
      },
      "processes": [
        {
          "id": "e1c17bc36d7a9cc76ead259ace0307d4b9705646",
          "app": "my-app-name",
          "tags": [
            "region:north",
            "zone:A"
          ],
          "hostname": "my-computer.local",
          "topLevel": 1,
          "depChains": [
            [
              "ms@0.7.0"
            ]
          ]
        }
        ...
      ]
    },
  ...
 ]
}

query

Subscribe to matching agent data on an interval.

Option Description
--field List of fields to request. All fields returned if not specified
--interval Number of seconds before returning next current object (default: 1)
--q The query filter options (see above)

Usage

$ nsolid-cli query --q id=5

Returns newline delimited JSON objects with framing objects.

Framing Type Description
start The query stream start frame
interval-start The start of the records for this interval
agent-enter An agent entry
summary Summary data about the entire (unfiltered) data set
interval-end The last record for this interval frame

Example JSON Result

{"time":"2017-12-04T01:42:29.502Z","type":"start"}
{"time":"2017-12-04T01:42:29.502Z","type":"interval-start"}
{"time":"2017-12-04T01:42:29.502Z","type":"agent-enter","id":"5dd6f7a940bfc3633cc3ffc82332640d51ce5112","info":{ ... },"metrics":{ ... }
{"time":"2017-12-04T01:42:29.502Z","type":"summary","totalAgents":9}
{"time":"2017-12-04T01:42:29.502Z","type":"interval-end"}

summary

Pull a summary of all connected N|Solid processes. Reports counts of matched properties or resources.

Option Description
--q The query options (see above)

Usage

$ nsolid-cli summary

Example JSON Result

{
  "time": "2017-12-04T02:12:02.506Z",
  "processes": 9,
  "apps": {
    "my-app-name": 5,
    "api-server": 1,
    "web": 1,
    "batch-service": 2
  },
  "tags": {
    "region:north": 4,
    "zone:A": 5,
    "region:south": 5,
    "zone:B": 2,
    "zone:C": 2
  },
  "rss": 693153792,
  "cpu": 3.4667812728278924,
  "node": {
    "8.9.1": 9
  },
  "nsolid": {
    "3.0.0": 9
  },
  "packages": 552,
  "vulnerabilities": {
    "npm:ms:20170412": 4,
    "npm:qs:20140806": 2,
  },
  "hiddenVulnerabilities": {}
}

Metrics in Detail

N|Solid makes available a rich set of metrics covering the Node.js process's host system, the process itself, the internal behavior of Node.js, and the internal behavior of the V8 JavaScript engine. Combining these data points can give you sophisticated insight into your Node.js deployment.

Many of the key metrics are displayed directly on the N|Solid Console. To make numeric metrics available to your StatsD collector directly from the N|Solid Process, configure using the NSOLID_STATSD environment variable (see the StatsD section for more detail). For the full set of metrics, use the nsolid-cli utility.

Process Details

Property Description
time The ISO8601 timestamp representing when a given metrics window completed
id The unique agent ID. 1:1 relationship with Node processes
app The user-specified name for the "application" this Node process is running
tags User-specified tags to provide additional metadata for this process
vulns The number of matched known vulnerabilities found in 3rd-party packages being used by a given process

System Data

Property Description
hostname The hostname of the system (hardware, VM, or container) a process is running on
freeMem The amount of free host memory, in bytes
systemUptime The hosting system's uptime, in seconds
load1m The one-minute load average of the hosting system
load5m The five-minute load average of the hosting system
load15m The fifteen-minute load average of the hosting system
cpuSpeed The current speed of the host system's CPU (averaged across all cores, taking into account CPU scaling), in MHz

General Process Stats

Property Description
uptime The process uptime in seconds
user The user account this process is running as
title The current process title
rss The total Resident Set Size (total memory used) by this process
cpuPercent The percent of one CPU core used by this process
cpuSystemPercent The percent of one CPU core used by this process for system calls
cpuUserPercent The percent of one CPU core used by this process for non-system calls
ctxSwitchInvoluntaryCount The process lifetime total of involuntary context switches by this process
ctxSwitchVoluntaryCount The process lifetime total of voluntary context switches by this process
ipcReceivedCount The process lifetime total of IPC messages received
ipcSentCount The process lifetime total of IPC messages sent
signalCount The process lifetime count of signals received by this process
pageFaultSoftCount The process lifetime total of "soft" page faults (page reclaims)
pageFaultHardCount The process lifetime total of "hard" page faults
swapCount The process lifetime total of times the process has been swapped out of memory
blockInputOpCount The process lifetime total of block input operations
blockOutputOpCount The process lifetime total of block output operations

JavaScript Memory Stats

Property Description
heapTotal The total allocated size of the JavaScript heap in bytes. A subset of rss
heapUsed The amount of heapTotal in use by JavaScript in bytes
totalHeapSizeExecutable The amount of heapTotal that has been marked as "executable" to the operating system
totalPhysicalSize The amount of physical memory currently committed to store the allocated heap (heapTotal)
totalAvailableSize The amount of memory that can be allocated without exceeding heapSizeLimit
heapSizeLimit The maximum amount of memory that may be reserved as JavaScript heap (heapTotal) before V8 will terminate with allocation failures

Asynchronous Activity Stats

For more information on these asynchronous activity stats, see the async-activity command.

Property Description
activeRequests The number of short-lived event-loop operations currently in flight or attached to resources
activeHandles The number of longer-lived event-loop operations currently in flight or attached to resources

Node.js Event Loop Stats

Property Description
loopIdlePercent Percent of time that the process is waiting for external input (I/O) or timers (idle)
loopEstimatedLag The estimated amount of time a task may have to wait in the event queue before the main JavaScript thread is available to dequeue and execute it
loopsPerSecond The number of event loop "turns" elapsed in the last second
loopAvgTasks The average number of batched event loop tasks dequeued per event loop "turn"
loopTotalCount The process lifetime total count of event loop "turns"

JavaScript Garbage Collection Stats

Property Description
gcCount The process lifetime total count of Garbage Collections (scavenge + mark-sweep + full)
gcFullCount The process lifetime total of Garbage Collections collecting all available unreachable nodes. Usually only observed when the heapTotal is approaching heapSizeLimit
gcMajorCount The process lifetime total of Garbage Collections considered "significant," such as "Mark-Sweep"
gcForcedCount The process lifetime total of forced (manually triggered) Garbage Collections
gcCpuPercent The percent of one CPU core used exclusively for garbage collection during the sample window
gcDurUs99Ptile The 99th Percentile duration of garbage collection run times, in microseconds
gcDurUsMedian The median (50th Percentile) duration of garbage collection run times, in microseconds

HTTP and DNS Stats

Property Description
httpClientCount The process lifetime total of HTTP[S] outgoing client requests performed
httpClientMedian The median (50th Percentile) duration of HTTP[S] outgoing client requests completed during the sample window
httpClient99Ptile The 99th percentile of HTTP[S] outgoing client requests completed during the sample window
httpServerCount The process lifetime total of HTTP[S] incoming client requests handled
httpServerMedian The median (50th Percentile) duration of HTTP[S] incoming client requests completed during sample window
httpServer99Ptile The 99th Percentile duration of HTTP[S] incoming client requests completed during the sample window
dnsCount The process lifetime total of DNS lookups performed
dnsMedian The median (50th Percentile) duration of DNS lookups completed during the http_sample collection window
dns99Ptile The 99th Percentile of DNS lookups completed during the sample window
httpClientAbortCount The process lifetime total of HTTP[S] outgoing client requests that were timed out, cancelled, or aborted before completion
httpServerAbortCount The process lifetime total of served HTTP[S] incoming client requests that were timed out, cancelled, or aborted before completion

Custom Commands

Custom commands can be triggered via the N|Solid Command Line Interface (CLI). Custom commands allow you to interact with your application's processes in ways specific to your business needs.

Create A Custom Command

To implement a custom command, create a function to handle the command, and register that function with N|Solid.

The custom command function should be defined to take a single parameter, request:

function customCommandHandler(request) { ... }

The request parameter is an object with the following properties/functions:

Property Description
request.value An optional piece of data sent with the command, using the nsolid-cli parameter --data
request.return(value) The function to call when you are ready to return the result of this command. The N|Solid Agent will reply with the value passed as a parameter
request.throw(error) A function to call if an error is encountered. The N|Solid Agent will reply with the error passed as a parameter

Your function you must call either request.return() or request.throw() to signal completion of the command.

To get access to N|Solid's built-in nsolid module, call require("nsolid"). A custom command handler is registered using the nsolid.on() function:

The nsolid.on() function takes the following parameters:

Parameter Description
commandName The string name of the command to implement
handler The custom command function implementing the command
nsolid.on(commandName, handler)

Example Custom Command Registration

const nsolid = require("nsolid")
...
nsolid.on("foo", fooCommand)
...
function fooCommand(request) { ... }

Sample Case: Log Level Custom Command

Below is an example of how you can use custom commands to dynamically change the configuration state of the application, specifically the log level. The example assumes that a global boolean variable Verbose is used to indicate whether to log verbosely or not.

//------------------------------------------------------------------------------
// This program is a simple "server" which does nothing, but does implement
// an N|Solid custom command, named `verbose`.  Once you've started this program
// with the N|Solid agent enabled, you can send the `verbose` command as in:
//
// nsolid-cli --id $NSOLID_AGENTID custom --name verbose
// nsolid-cli --id $NSOLID_AGENTID custom --name verbose --data on
// nsolid-cli --id $NSOLID_AGENTID custom --name verbose --data off
//
// All these forms get or set the "verbose" level of logging in the program.
//
// The server logs a message every second when "verbose" is off, and logs
// an additional message after that one when "verbose" is on.  The default
// setting of "verbose" is false.
//------------------------------------------------------------------------------

"use strict"

// get access to N|Solid's built-in module `nsolid`
const nsolid = require("nsolid")

// the current "verbose" level
let Verbose = false

// register the `verbose` command for nsolid-cli
nsolid.on("verbose", verboseCommand)

// your server which doesn't do much
setInterval(onInterval, 2000)

console.log("N|Solid custom command demo - log-level - started")
console.log("")
console.log("to use the verbose command with `nsolid-cli`, run:")
console.log("   nsolid-cli --id $NSOLID_AGENTID custom --name verbose")
console.log("   nsolid-cli --id $NSOLID_AGENTID custom --name verbose --data on ")
console.log("   nsolid-cli --id $NSOLID_AGENTID custom --name verbose --data off ")

//------------------------------------------------------------------------------
function onInterval() {
  log("interval event!")
  logVerbose("some extra logging here")
}

//------------------------------------------------------------------------------
// implements the `verbose` command  for nsolid-cli
//------------------------------------------------------------------------------
function verboseCommand(request) {

  // if "on" or "off" passed in with --data, set Verbose appropriately
  if (request.value == "on") {
    Verbose = true
  }
  else if (request.value == "off") {
    Verbose = false
  }
  else if (request.value) {
    return request.throw("expecting data of `on` or `off`, got " + request.value)
  }

  // return current value of Verbose
  return request.return({verbose: Verbose})
}

//------------------------------------------------------------------------------
function log(message) {
  console.log(message)
}

//------------------------------------------------------------------------------
function logVerbose(message) {
  if (!Verbose) return
  log(message)
}

When running your application with the N|Solid agent active, you can use the following command to return the current value of the Verbose setting:

$ nsolid-cli --id $NSOLID_AGENTID custom --name verbose

To set Verbose on or off, use one of the following commands:

$ NSOLID_AGENTID="69d916ad395061f80589e20bef9af3cb50ece9cb" # This will change
$ nsolid-cli --id $NSOLID_AGENTID custom --name verbose --data on
$ nsolid-cli --id $NSOLID_AGENTID custom --name verbose --data off

The output of these three CLI commands looks like the following:

{"verbose":false,"time":1472496720972,"timeNS":"1472496720972042976","id":"69d916ad395061f80589e20bef9af3cb50ece9cb","app":"my-verbose-app","hostname":"titania"}

Custom Lifecycle Events

Implementing Custom Lifecycle Events

In addition to the built-in lifecycle events, you can add your own using the process.recordStartupTime(label) function. The label will then be used in the JSON output of the startup-times command.

You can use this to record the times at various stages of your application's startup. For instance:

  • when a database connection is requested
  • when the database connection is returned
  • when an http server is ready for incoming events

Using the CLI

To obtain the startup timing values, you can use the nsolid-cli startup-times command.

N|Solid provides three startup times by default via startup-times:

Parameter Description
initialized_node The time it takes to initialize the Node internals, reported in [seconds, nanoseconds]
initialized_v8 The time it takes to initialize the V8 engine, reported in [seconds, nanoseconds]
loaded_environment The time it takes to complete all initialization, which includes running some of Node's internal JavaScript code, and your main module's top-level code, reported in [seconds, nanoseconds]

Usage

$ nsolid-cli startup-times

Example JSON Result

{
  "id": "bf24f4ed072b3bb4b220aa81fa3a73fde8038409",
  "app": "MyApp",
  "hostname": "myApp.example.com",
  "initialized_node":   [ 0, 130404 ],
  "initialized_v8":     [ 0, 482651 ],
  "loaded_environment": [ 0, 620207709 ]
}

This indicates that Node was initialized in 130,404 nanoseconds (which is 130 microseconds, 0.130 milliseconds, or 0.000130 seconds).

Note: The timing information is provided in hrtime format, which is a two element array of [seconds, nanoseconds]. A nanosecond is one billionth (1,000,000,000th) of a second. The time values are the elapsed time since the process was started.

Example: Adding A Custom Timer

Below is an example web server instrumented to provide the time it takes for the web server to start listening to connections:

# http_sample.js

const http = require("http")

const server = http.createServer(onRequest)

server.listen(3000, onListen)

function onListen() {
  console.log("server listening on http://localhost:3000")
  process.recordStartupTime("http_listen")
}

function onRequest(request, response) {
  response.end("Hello, world!")
}

To start this program with the N|Solid agent listening on port 5000, use the following command:

$ NSOLID_APPNAME=http-sample nsolid http_sample.js

To obtain the startup times, including the custom timer, use the following command:

$ nsolid-cli startup-times --app http-sample

Example JSON Result

{
  "id": "bf24f4ed072b3bb4b220aa81fa3a73fde8038409",
  "app": "http-sample",
  "hostname": "http-sample.example.com",
  "initialized_node":   [ 0, 129554 ],
  "initialized_v8":     [ 0, 460521 ],
  "loaded_environment": [ 0, 95201339 ],
  "http_listen":        [ 0, 94902772 ]
}

Policies

N|Solid ships with the ability to enable some security-related policies to help harden your application. Currently these include the ability to disable core modules and bindings.

To enable policy configuration with N|Solid, you must create a policies file in JSON format, and specify that file via the policies flag when starting N|Solid.

$ nsolid --policies my-policies.json app.js

Disabling Core Resources

N|Solid includes the ability to disable core modules with a policy file. This can be used to restrict application access to system resources or features that should not be used by your application.

Modules and bindings are the two types of core resources that can be disabled:

  • modules are the JavaScript APIs of Node, e.g. fs or http;
  • bindings are the wrappers for native code, e.g. stream_wrap or tcp_wrap.

There are four different severity levels you can configure:

Parameter Level Description
0 ignore No notice will be provided during the loading of the module or binding. This is the default behavior
1 warning A warning is written to stderr during the loading of the module or binding. The application otherwise runs normally
2 throw error A error is thrown only when the policy is _violated_​ which doesn't occur during the ​_loading_​ of the module, but when a function on it is called. You can catch this by writing a try/catch in your code around your require() calls
3 exit The application exits during the loading of the module or binding

Disabling a module in the policy file prevents all non-core modules from using it. A warning is printed when loaded, but only when it is used does the violation handler kick in). Core modules are still able to load it (e.g. the core module library can still use fs to read new files via require()).

Example Policy File

# disable-dns-all.policy.json

{
  "// severity levels": "0 - ignore; 1 - warning; 2 - throw error; 3 - exit",

  "blacklist": {
    "modules": {
      "dns": 2
    },
    "bindings": {
      "cares_wrap": 2
    }
  }
}

The policy file can also be used to restrict access to bindings. The example policy file above disables both the dns module and the cares_wrap binding, both of which can be used to access DNS.

When a non-core module attempts to access a disabled core module, messages will be logged to stdout, and an exception thrown.

Using A Policy File

In this example, a DNS connection is made in a separate file, faux-dns.js. To implement the above policy file, disable-dns-all.policy.json, enter the following command. Note the printed result:

$ nsolid --policies disable-dns-all.policy.json faux-dns.js

nsolid error Binding "cares_wrap" is requested via a process.binding call
nsolid error at Object.<anonymous> (/Users/user/nsolid-demos/demos/faux-dns.js:3:23)
nsolid error But it was disabled in the policies.
_module_wrap.js:423
    throw new Error('Binding "' + id +
    ^

Error: Binding "cares_wrap" has been disabled by the policies flag, using "GetAddrInfoReqWrap" on it is not allowed, terminating execution.
    at new throwError (_module_wrap.js:423:11)
    at Module._compile (module.js:430:26)
... more stack trace lines here

Example: Restricting Access to Modules and Bindings

The cares_wrap binding can be used directly for DNS access. We will invoke it and restrict access with a policy file.

# fauxdns.js

module.exports = lookup;

var cares = process.binding('cares_wrap');

function lookup(hostname, callback) {

  var req = new cares.GetAddrInfoReqWrap();
  req.callback = callback;
  req.family = 4;
  req.hostname = hostname;
  req.oncomplete = callback;

  var err = cares.getaddrinfo(req, hostname, 4, 0);

  if (err) {
    callback(new Error("OOPS"));
    return {};
  }
  return req;
}

Call the function:

# lookup.js

var look = require("./fauxdns.js");
look("nodesource.com", function (err, data) {
  console.log(data);
});

Without a policy file in place, you still have access to the network via the dns module:

$ nsolid lookup.js
[ '162.243.142.64' ]

Create a policy file that prevents just the dns module:

# disable_dns.js

{
  "blacklist": {
    "modules": {
      "dns": 2
    }
}

But, we still have DNS access:

$ nsolid --policies disable_dns.js lookup.js
[ '162.243.142.64' ]

To prevent the circumvention of the modulesBlacklist, we need to blacklist the cares_wrap binding directly:

# disable_cares.json

{
  "blacklist": {
    "bindings": {
      "cares_wrap": 2
    }
  }
}

The behavior is now blocked:

$  nsolid --policies disable_cares.json lookup.js
nsolid error Binding "cares_wrap" is requested via a process.binding call
nsolid error at Object.<anonymous> (/Users/user/develop/nodesource/policies/fauxdns.js:3:21)
nsolid error But it was disabled in the policies.
_module_wrap.js:423
    throw new Error('Binding "' + id +
    ^

Error: Binding "cares_wrap" has been disabled by the policies flag, using "GetAddrInfoReqWrap" on it is not allowed, terminating execution.
    at new throwError (_module_wrap.js:423:11)
    at lookup (/Users/user/develop/nodesource/policies/fauxdns.js:7:13)
    at Object.<anonymous> (/Users/user/develop/nodesource/policies/lookup.js:3:1)
    at Module._compile (module.js:434:26)
    at Object.Module._extensions..js (module.js:452:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Function.Module.runMain (module.js:475:10)
    at startup (node.js:150:18)
    at node.js:986:3

More Policy Usage

Example: Disabling the child_process Module

In this example, the child_process module is blacklisted with severity level 2.

# disable_childprocess.json

{
  "blacklist": {
    "modules": {
      "child_process": 2
    }
  }
}

Code Usage

var ls = require("child_process").execSync("ls -l")
console.log(ls.toString())

Running with Policy

$ nsolid --policies disable_childprocess.json child_process_example.js
nsolid error Module "child_process" is required
nsolid error at Object.<anonymous> (/home/bryce/ns/nsolid-node/foo.js:1:72)
nsolid error But it was disabled in the policies.
child_process.js:75
  throw new Error('"' + module.id + '" has been disabled ' +
  ^

Error: "child_process" has been disabled by the policies flag, terminating execution.
    at handleDisabledMethodCall (child_process.js:75:9)
    at Object.execSync (child_process.js:89:22)
    at Object.<anonymous> (/home/bryce/ns/nsolid-node/foo.js:1:96)
    at Module._compile (module.js:434:26)
    at Object.Module._extensions..js (module.js:452:10)
    at Module.load (module.js:355:32)
    at Function.Module._load (module.js:310:12)
    at Function.Module.runMain (module.js:475:10)
    at startup (node.js:149:18)
    at node.js:985:3

JSON Comments

To be able to include comments in your JSON files, N|Solid ignores properties whose keys start with "//".

{
  "//this": "is an N|Solid JSON comment"
}

N|Solid Policies and Security

N|Solid's Policies feature should not be used as a blind replacement for good security practices with regard to your code and the code of your application's dependencies. Disabling core modules and bindings does not provide a complete guarantee that your application is unable to use the features provided by those parts of Node.js.

For example, child processes interacting with Unix utilities, if not disabled, can be used to replace the functionality of many of the core modules. Some core modules may be completely re-implemented in user-land modules, such as in the dns and cares_wrap example. Compiled add-ons have complete freedom to insert new functionality that can replace anything that has been disabled.

N|Solid's policy features augment and support existing enterprise-wide application security hardening programs. Please contact NodeSource if you wish to discuss your Node.js application security needs and prepare a customized security hardening program that involves the use of internal and third-party code review, application monitoring, and the use of operating system security tools.

Invalid Policies

Anytime an unexpected property or a property with an invalid value is encountered, the policies are considered invalid and the process is halted.

Modules That Can Be Blacklisted

The following is a list of modules that can be blacklisted. It should be noted that for most of these modules it is rare to have a business need where blacklisting makes sense.

Module Description
assert Used for writing unit tests for your applications, you can access it with require('assert')
async_hooks Provides an API to register callbacks tracking the lifetime of asynchronous resources
buffer Raw data is stored in instances of the Buffer class
bootstrap_node Bootstraps the Node.js core, with a special eye on performance
child_process Provides a tri-directional popen(3) facility in order to create a child process
cluster Allows you to easily create child processes that all share server ports
console Console object is a special instance of Console whose output is sent to stdout or stderr
constants Deprecated way of accessing constant values. Updated: require('someModule').constants
crypto Crypto module offers a way of encapsulating secure credentials to be used as part of a secure HTTPS net or HTTP connection
dgram Provides Datagram sockets
dns Provides name resolution
domain Pending deprecation - provide a way to handle multiple different I/O operations as a single group
encoding Converts strings from one encoding to another
errors Provides an API for handling errors
events Provides event emitters
freelist Data structure used internally by Node.js
fs Provides file I/O via simple wrappers around standard POSIX functions
http Provides ability to create HTTP servers and clients
http2 Provides ability to create HTTP2 servers and clients
https Provides ability to create HTTPS servers and clients
_http_agent Provides support for HTTP and HTTPS modules, mostly used internally
_http_client Provides support for HTTP and HTTPS modules, mostly used internally
_http_common Provides support for HTTP and HTTPS modules, mostly used internally
_http_incoming Provides support for HTTP and HTTPS modules, mostly used internally
_http_outgoing Provides support for HTTP and HTTPS modules, mostly used internally
_http_server Provides support for HTTP and HTTPS modules, mostly used internally
inspector Provides an API for interacting with the V8 inspector
inspector_async_hook Registers async hooks with the V8 inspector
module Provides the Node.js module system, mostly used internally
net Net module provides asynchronous network wrapper for server and clients
os Provides basic operating-system related utility functions
path Provides utilities for handling and transforming file paths
perf_hooks Supports collection of high resolution performance metrics
process Same as the global process object
punycode Provides Unicode utilities
querystring Provides utilities for dealing with query strings
readline Allows reading of a stream (such as process.stdin) on a line-by-line basis
repl Provides a way to interactively run JavaScript and see the results
socket_list Provides a way to monitor socket connections
stream Provides streaming functionality
_stream_duplex Provides the DuplexStream exposed via the stream module
_stream_passthrough Provides the PassThroughStream exposed via the stream module
_stream_readable Provides the ReadableStream exposed via the stream module
_stream_transform Provides the TransformStream exposed via the stream module
_stream_wrap Provides the wrapper to the libuv stream implementation, mostly used internally
_stream_writable Provides the WritableStream exposed via the stream module
string_decoder Decodes a buffer to a string with utf8 support
sys Deprecated alias for util
timers Provides internal support for global Timers
tls Uses OpenSSL to provide Transport Layer Security and/or Secure Socket Layer: encrypted stream communication
_tls_common Provides support for tls module, mostly used internally
_tls_legacy Provides support for tls module, mostly used internally
_tls_wrap Provides support for tls module, mostly used internally
tty Provides the tty.ReadStream and tty.WriteStream classes
url Provides utilities for URL resolution and parsing
util Primarily designed to support the needs of Node.js's internal APIs, but many of these utilities are useful for user programs
v8 Events and interfaces specific to the version of V8
vm Provides support to compile and run code immediately, or compile, save, and run code later
wrap_js_stream Provides an interface for the C++ side of Node and a standard JS stream
zlib Provides bindings to Gzip/Gunzip

Bindings That Can Be Blacklisted

The following is a list of bindings that can be blacklisted. It should be noted that for most of these bindings it is rare to have a business need where blacklisting makes sense.

Binding Description
async_wrap Base class for all async request modules which supports hooks into async events
buffer Interface to libuv methods to operate on buffers
cares_wrap Wraps the cares library for asynchronous name resolves
config Build configuration
constants Provides access to C++ constants
contextify Interface to V8 in order to create execution contexts
crypto Provides crypto functionality such as SSL and ciphers
fs Interface to file system methods provided by libuv
fs_event_wrap Binding to listen to file-related events in order to support watching files and directories for changes
http_parser Binding to http_parser
icu Internationalization API and database
inspector Provides the source code for the --inspect debug tooling
js_stream Binding that provides support for Node.js streams
os Interface to libuv in order to obtain process state information
performance Provides the code for the perf_hooks module
pipe_wrap Wraps libuv's socket implementation
process_wrap Provides process functionality such as spawning child processes
serdes Polyfill for the Node.js 8.x serializer API
signal_wrap Supports sending and handling signals to processes
spawn_sync Supports child_process.execSync functionality via libuv
stream_wrap Wraps stream implementations exposed by libuv to communicate via file descriptors or network connections
tcp_wrap Integrates TCP functionality exposed by libuv in order to create TCP connections
timer_wrap Integrates with timer functionality provided by libuv so support things like setTimeout and setInterval
tls_wrap Provides TLS termination functionality via crypto
tty_wrap Integrates with TTY terminal functionality provided by libuv
udp_wrap Provides UDP protocol functionality such as binding and broadcasting
url WhatWG URL parser
util Backing code for Node's util module
uv Provides libuv integration such as error name resolution
v8 Limited interface to the V8 API, i.e. to set flags and get process information
zlib Wraps the zlib library