N|Solid Documentation

Versions

N|Solid Command Line Interface (CLI)

The N|Solid Agent comes with a set of pre-defined endpoints for interaction and introspection and can be customized to add additional endpoints.

Some commands accept input from the command line, this can be supplied via nsolid-cli --data '{"json":"object"} ....

ping

This is the agent's availability check, it will always reply with "PONG" if online.

Usage

nsolid-cli --socket XXXX ping

Example JSON Result:

"PONG"

info

Usage

nsolid-cli --socket XXXX info

Returns information about the running process and N|Solid Agent configuration:

Parameter Description
id The execution id for this run instance
app The NSOLID_APPNAME
pid The process id
execPath Path of the executable running the application
main The main module used when the application started up

Example JSON Result:

{
  "meta": {
    "id": "9f6e7ab8f323a33a31f56bafed32ebc172777dd8",
    "app": "web-server",
    "pid": 5416,
    "hostname": "cluster-1.oregon",
    "address": "192.168.2.27:38580"
  },
  "reply": {
    "id": "9f6e7ab8f323a33a31f56bafed32ebc172777dd8",
    "app": "web-server",
    "pid": 5416,
    "nodeEnv":"production",
    "execPath": "/usr/local/bin/nsolid",
    "main": "/var/myapp/web/server.js"
  }
}
{
  "meta": {
    "id": "ccd48968f3212a06c3aff62bbfa75c481ad5f672",
    "app": "api-server",
    "pid": 5447,
    "hostname": "cluster-1.oregon",
    "address": "192.168.2.27:52352"
  },
  "reply": {
    "id": "ccd48968f3212a06c3aff62bbfa75c481ad5f672",
    "app": "api-server",
    "pid": 5447,
    "nodeEnv":"production",
    "execPath": "/usr/local/bin/nsolid",
    "main": "/var/myapp/api/server.js"
  }
}

versions

Returns the versions of bundled components that make up Node.js and N|Solid.

Usage

nsolid-cli --socket XXXX versions

Example JSON Result:

{
  "http_parser": "2.5.0",
  "node": "4.2.2",
  "nsolid": "1.1.0",
  "v8": "4.5.103.35",
  "uv": "1.7.5",
  "zlib": "1.2.8",
  "ares": "1.10.1-DEV",
  "modules": "46",
  "openssl": "1.0.2d",
  "nsolid_lib": {
    "function_origin": "nsolid-v1.2.0",
    "nan": "v2.1.0",
    "v8_profiler": "nsolid-v5.2.3-fix1",
    "agent": "v4.2.2",
    "cli": "v1.3.3"
  }
}

process_stats

Usage

nsolid-cli --socket XXXX process_stats

Returns live metrics reflecting the health and resource utilization of the N|Solid process.

Parameter Description
uptime The time in seconds this process has been running
rss The total Resident Set Size (total memory used) by this process (bytes)
heapTotal The total allocated size of the JavaScript heap (bytes). A subset of rss
heapUsed The amount of heapTotal being used by JavaScript (bytes)Returns live metrics reflecting the health and resource utilization of the process.
active_requests The number of active requests the event loop will process. For more information see the async_activity command.
active_handles The number of active handles the event loop will process. For more information, see the async_activity command.
title The process title
user The user the process is running as
cpu % cpu being used by the process

Example JSON Result:

{
  "uptime": 2580.584,
  "rss": 25083904,
  "heapTotal": 14423040,
  "heapUsed": 8272800,
  "active_requests": 1,
  "active_handles": 2,
  "title": "nsolid",
  "user": "user",
  "cpu": 0
}

## system_info

> **Usage**
>
> nsolid-cli -- socket XXXX **system_info**

Returns static information about the hosting system for this N|Solid process.

| Parameter | Description |
|----------------|----------------------------------------|
| cpu_cores | The number of CPU cores |
| cpu_model | The CPU model |
| arch | The CPU architecture |
| platform | Name of the NSolid platform |
| hostname | The host name |
| totalmem | Total available memory in the system |

*Example JSON Result:*

```json
{
 "cpu_cores": 8,
  "cpu_model": "Intel(R) Core(TM) i7-4870HQ CPU @ 2.50GHz",
  "arch": "x64",
  "platform": "darwin",
  "hostname": "user.local",
  "totalmem": 17179869184
}

system_stats

Usage

nsolid-cli -- socket XXXX system_stats

Returns live metrics reflecting the health and resource utilization of the system hosting the N|Solid process.

Parameter Description
freemem The amount of free (unused) memory in bytes
uptime The uptime of the system, in seconds
load_1m The one-minute load average*
load_5m The five-minute load average*
load_15m The fifteen-minute load average*
cpu_speed The current speed of the CPU (averaged across all cores) in MHz

Example JSON Result:

{
  "freemem": 3137511424,
  "uptime": 697783,
  "load_1m": 1.54150390625,
  "load_5m": 1.4052734375,
  "load_15m": 1.44189453125,
  "cpu_speed": 2500
}

startup_times

Usage

nsolid-cli -- socket XXXX startup_times

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

Parameter Description
initialized_node The time it took to initialize the Node internals.
initialized_v8 The time it took to initialize the V8 engine
loaded_environment 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.

The times are provided in hrtime syntax: a Tuple Array of 2 integers representing the time since the initial process execution in [seconds, nanoseconds]. Example JSON Result

{
  "initialized_node":   [ 0, 130404 ],
  "initialized_v8":     [ 0, 482651 ],
  "loaded_environment": [ 0, 620207709 ]
}

Custom startup timers

If you're looking for information on how to add custom startup and lifecyle events check out this tutorial.

async_activity

Usage

nsolid-cli -- socket XXXX aysnc_activity

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

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

Calling the async_activity endpoint will list two types of inflight async work -- handles and requests.

Async handles tend to be longer-lived larger-scale asynchronous operations, such as open sockets or timers.

Async requests tend to be shorter-lived smaller-scale operations such as writing to file handles and other file-related operations.

Example JSON Result:

{
  "handles": [
    {
      "type": {
        "flag": 8,
        "name": "TCP socket connection"
      },
      "details": {
        "fd": 14,
        "transport": "TCP",
        "bytesDispatched": 0,
        "hadError": false,
        "host": null,
        "peerAddress": "::ffff:127.0.0.1",
        "peerFamily": "IPv6",
        "peerPort": 42097,
        "sockAddress": "::ffff:127.0.0.1",
        "sockFamily": "IPv6",
        "sockPort": 8080,
        "ondata": "socketOnData: _http_server.js:318:23",
        "onclose": "serverSocketCloseListener: _http_server.js:263:36",
        "onend": "socketOnEnd: _http_server.js:360:22"
      }
    },
    {
      "name": "__unknown_function_name__",
      "location": {
        "file": "[eval]",
        "line": 1,
        "column": 104,
        "inferredName": ""
      },
      "anonymous": true,
      "source": "function () {res.end(\"ok\")}",
      "type": {
        "flag": 1,
        "name": "setTimeout"
      },
      "details": {
        "msecs": 20000
      }
    },
    {
      "type": {
        "flag": 8,
        "name": "TCP socket connection"
      },
      "details": {
        "fd": 15,
        "transport": "TCP",
        "bytesDispatched": 0,
        "hadError": false,
        "host": null,
        "peerAddress": "::ffff:192.168.1.104",
        "peerFamily": "IPv6",
        "peerPort": 54416,
        "sockAddress": "::ffff:192.168.1.104",
        "sockFamily": "IPv6",
        "sockPort": 35770,
        "ondata": "socketOnData: _http_server.js:318:23",
        "onclose": "serverSocketCloseListener: _http_server.js:263:36",
        "onend": "socketOnEnd: _http_server.js:360:22"
      }
    }
  ],
  "requests": []
}

profile_start, profile_stop

Usage

nsolid-cli -- socket XXXX profile_start nsolid-cli -- socket XXXX profile_stop > my.cpuprofile

Collection will commence immediately after ‘profile_start’ hits the wire and will continue for up to 60 seconds. If profile_stop is not entered before 60 seconds then the process times out and the profile data is discarded. Order of execution is always profile_start, then profile_stop.

profile_start

Begins CPU Profile collection. It will collect for up to 60 seconds before timing out. If it times out, all profile data is discarded.

Only one CPU collection is allowed to be running at a time.

profile_stop

Must be run after profile_start -- completes the CPU Profile collection and sends the resulting cpuprofile data. In the N|Solid Console, this will be automatically loaded into our visualization system. From the CLI, the cpuprofile data can be saved to a file and then loaded into Chrome Dev Tools.

snapshot

Usage

nsolid-cli -- socket XXXX snapshot > my.heapsnapshot

Once the .heapsnapshot file has been created, it can be opened using Chrome’s Development Tool’s CPU Profile Debugging Tool It’s important to note that Chrome requires the generated file to have the extension .heapsnapshot so be sure to use that.

custom commands

The N|Solid Agent provides a JavaScript interface for implementing custom commands that can be triggered externally. For more information read about implementing custom commands here.

Socket Flag Usage

The socket flag is necessary if you are running everything on one machine; the common starting point of those evaluating N|Solid. If you are connecting to a HUB, you would not use --socket.