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.
--auth
If your Console is running with authentication enabled, you will need to configure an administrative access token to allow nsolid-cli to be permitted to access it. This can be set with the NSOLID_CONSOLE_AUTH_ADMIN_TOKEN
environment variable or the corresponding config file setting to a secure value value. Once set, you can pass this value to nsolid-cli using the --auth
argument. To disable this authentication, see user authentication.
--attach
For the specific case of importing settings from a configuration file .nsconfig
, you can use this option to read the contents from the file in the filesystem.
--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
}
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.10.0",
"nsolid": "3.1.0",
"v8": "6.2.414.50",
"uv": "1.19.1",
"zlib": "1.2.11",
"ares": "1.10.1-DEV",
"modules": "57",
"nghttp2": "1.25.0",
"openssl": "1.0.2n",
"icu": "60.1",
"unicode": "10.0",
"cldr": "32.0",
"tz": "2017c",
"nsolid_lib": {
"v8_profiler": "nsolid-v5.7.0-fix1",
"sodium": "nsolid-2.1.0",
"cjson": "nsolid-3.0.0",
"function_origin": "nsolid-v1.2.1",
"nan": "v2.5.1",
"cli": "v3.0.0",
"agent": "v8.0.3",
"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,
"externalMem": 734532,
"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": {}
}
export-settings
Pull a JSON object with one or many settings configuration to backup or import
later. The only settings available to export are: integrations
, savedViews
and notifications
.
Option |
Description |
--item |
Could be one or a list of items to export (see example) |
Usage
$ nsolid-cli export-settings --item integrations,savedViews,notifications
Example JSON Result
{
"_metadata": {
"_timestamp": "",
},
"integrations": {},
"notifications": {},
"savedViews": {}
}
import-settings
Apply a previously backup/exported settings. The only settings available to
import are: integrations
, savedViews
and notifications
.
Option |
Description |
--item |
Could be one or a list of items to export (see example) |
--action |
Append to or clean previous settings (see example) |
Usage
$ nsolid-cli import-settings --item integrations --action clean --attach backup.nsconfig
N|Solid API
Table of Contents N|Solid API
nsolid.start()
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 keys documented above, with the following difference:
version
is specified as appVersion
Example:
const nsolid = require('nsolid')
nsolid.start({
command: 'nsolid-command-host.local:9001',
tags: ['nsolid-awesome', 'Auth service'],
app: 'nsolid-awesome',
appVersion: '1.0.0'
})
nsolid.appName
Get the N|Solid app name (equal to nsolid.app
getter).
const nsolid = require('nsolid')
nsolid.appName
'nsolid-awesome'
nsolid.appVersion
Get the N|Solid app version (taken from the package.json
file).
const nsolid = require('nsolid')
nsolid.appVersion
'1.0.0'
nsolid.app
Get the N|Solid app name.
const nsolid = require('nsolid')
nsolid.app
'nsolid-awesome'
nsolid.clearFatalError()
const nsolid = require('nsolid')
process.on('uncaughtException', err => {
nsolid.clearFatalError(err)
proces.exit(1)
})
nsolid.config
Get the N|Solid application config.
const nsolid = require('nsolid')
nsolid.config
{
app: 'nsolid-awesome',
appVersion: '1.0.0',
blockedLoopThreshold: 200,
env: 'prod',
hostname: 'nsolid-host',
interval: 3000,
pauseMetrics: false,
pubkey: '<3',
statsdBucket: 'nsolid.${env}.${app}.${hostname}.${shortId}',
tags: ['nsolid-awesome', 'Auth service']
}
nsolid.id
Get the N|Solid agent id.
const nsolid = require('nsolid')
nsolid.id
'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
nsolid.info()
It returns relevant information about the running process and platform is running on.
const nsolid = require('nsolid')
nsolid.info()
{
id: '14e708a4bdb1fc5763fa1f29a9567229ab1b1ac4',
app: 'beautiful-nsolid-app',
appVersion: '1.0.0',
tags: undefined,
pid: 855556,
processStart: 1600731441576,
nodeEnv: undefined,
execPath: 'your-beautiful-app-directory/beautiful-nsolid-app',
main: 'index.js',
arch: 'x64',
platform: 'linux',
hostname: 'NodeSource',
totalMem: 16302604288,
versions: {
node: '12.18.4',
nsolid: '4.0.0',
v8: '7.8.279.23-node.39',
uv: '1.38.0',
zlib: '1.2.11',
brotli: '1.0.7',
ares: '1.16.0',
modules: '72',
nghttp2: '1.41.0',
napi: '6',
llhttp: '2.1.2',
http_parser: '2.9.3',
openssl: '1.1.1g',
cldr: '37.0',
icu: '67.1',
tz: '2019c',
unicode: '13.0'
},
cpuCores: 4,
cpuModel: 'Intel(R) Core(TM) i7-7500U CPU @ 2.70GHz'
}
The nsolid.info()
method can be called asynchronously too:
const nsolid = require('nsolid')
nsolid.info((err, info) => {
if (!err) {
// Yay!
}
})
nsolid.metrics()
It retrieves a list of enviroment and process metrics.
const nsolid = require('nsolid')
nsolid.metrics()
{
threadId: 0,
timestamp: 0,
activeHandles: 0,
activeRequests: 0,
heapTotal: 4464640,
totalHeapSizeExecutable: 524288,
totalPhysicalSize: 3685528,
totalAvailableSize: 2194638976,
heapUsed: 2666008,
heapSizeLimit: 2197815296,
mallocedMemory: 8192,
externalMem: 833517,
peakMallocedMemory: 91744,
numberOfNativeContexts: 1,
numberOfDetachedContexts: 0,
gcCount: 1,
gcForcedCount: 0,
gcFullCount: 0,
gcMajorCount: 0,
gcDurUs99Ptile: 812,
gcDurUsMedian: 812,
dnsCount: 0,
httpClientAbortCount: 0,
httpClientCount: 0,
httpServerAbortCount: 0,
httpServerCount: 0,
dns99Ptile: 0,
dnsMedian: 0,
httpClient99Ptile: 0,
httpClientMedian: 0,
httpServer99Ptile: 0,
httpServerMedian: 0,
loopIdleTime: 0,
loopIterations: 0,
loopIterWithEvents: 0,
eventsProcessed: 0,
eventsWaiting: 0,
providerDelay: 0,
processingDelay: 0,
loopUtilization: 1,
res5s: 0,
res1m: 0,
res5m: 0,
res15m: 0,
loopTotalCount: 0,
loopAvgTasks: 0,
loopEstimatedLag: 40.416415,
loopIdlePercent: 0,
title: 'nsolid',
user: 'NodeSource',
uptime: 0,
systemUptime: 96314,
freeMem: 2586660864,
blockInputOpCount: 0,
blockOutputOpCount: 0,
ctxSwitchInvoluntaryCount: 14,
ctxSwitchVoluntaryCount: 21,
ipcReceivedCount: 0,
ipcSentCount: 0,
pageFaultHardCount: 0,
pageFaultSoftCount: 1929,
signalCount: 0,
swapCount: 0,
rss: 31719424,
load1m: 2.79,
load5m: 2.52,
load15m: 2.47,
cpuUserPercent: 86.061918,
cpuSystemPercent: 15.533329,
cpuPercent: 101.595247,
cpu: 101.595247
}
If callback is passed, it returns the metrics asynchronously:
const nsolid = require('nsolid')
nsolid.metrics((err, metrics) => {
if (!err) {
// Yay!! All the metrics are in store in metrics param
}
})
See Metrics in detail for more information about each metric.
nsolid.metricsPaused
Whether the agent is currently retrieving metrics or not.
const nsolid = require('nsolid')
nsolid.metricsPaused
false
See nsolid.pauseMetrics()
nsolid.packages()
It retrieves the list of packages listed in the package.json
file and its dependencies, it returns a list of all packages that can be required by walking through all directories that could contain a module.
const nsolid = require('nsolid')
nsolid.packages()
[
{
path: 'nsolid-service/node_modules/js-tokens',
name: 'js-tokens',
version: '4.0.0',
main: 'index.js',
dependencies: [],
required: false
},
{
path: 'nsolid-service/node_modules/important-package',
name: 'important-package',
version: '3.0.0',
main: 'main.js',
dependencies: ['../express', '../object-assign'],
required: false
},
...
]
The nsolid.packages()
method has async implementation too:
const nsolid = require('nsolid')
nsolid.packages((err, packages) => {
if (!err) {
console.log(packages)
}
})
[
{
path: 'your-beautiful-app-directory/beautiful-nsolid-app',
name: 'beautiful-nsolid-app',
version: '1.5.2',
main: 'index.js',
dependencies: [],
required: false
}
]
nsolid.pauseMetrics()
It pauses the process metrics collection, and do nothing if metrics were already paused
(this method must be called on the main thread).
const nsolid = require('nsolid')
nsolid.pauseMetrics()
See nsolid.metricsPaused.
nsolid.processStart
It gets the start date of the process in milliseconds.
const nsolid = require('nsolid')
nsolid.processStart
1600730465456
nsolid.profile([duration])
This is the way to trigger a CPU profile programmatically from within your application and have the resulting profile saved on your N|Solid console. The profile duration 600000 milliseconds, which is the default if none is specified, and profiler can be stoped before the duration expires.
duration
is the duration in milliseconds of the Cpu profile (600000 milliseconds is the default duration).
const nsolid = require('nsolid')
nsolid.profile(600000 /* durationMilliseconds */, err => {
if (err) {
// The profile could not be started!
}
})
The CPU profiler can be triggered in a synchronous way:
const nsolid = require('nsolid')
try {
nsolid.profile(600000 /* durationMilliseconds */)
} catch (err) {
// The profile could not be started!
}
Learn more about Cpu profiling.
nsolid.profileEnd()
To complete the profile before the duration expires, call profileEnd
method:
const nsolid = require('nsolid')
nsolid.profileEnd(err => {
if (err) {
// Error stopping profiler (may it was not running)
}
})
Learn more about Cpu profiling.
nsolid.resumeMetrics()
It resumes the process metrics collection, and does nothing if metrics were already resumed
(this method must be called on the main thread).
const nsolid = require('nsolid')
nsolid.resumeMetrics()
nsolid.saveFatalError(error)
If you must exit asynchronously from an uncaughtException
handler it is still possible to report the exception by passing it to nsolid.saveFatalError()
prior to shutting down.
const nsolid = require('nsolid')
process.on('uncaughtException', err => {
nsolid.saveFatalError(err)
proces.exit(1)
})
nsolid.snapshot()
This is the way to take a heap snapshot programmatically from within your application and have the resulting snapshot(s) saved on your N|Solid console.
const nsolid = require('nsolid')
nsolid.snapshot(err => {
if (err) {
// The snapshot could not be created!
}
})
Snapshots can also be taken on a synchronous way:
const nsolid = require('nsolid')
try {
nsolid.snapshot()
} catch (err) {
// The snapshot could not be created!
}
Learn more about Heap snapshots.
nsolid.startupTimes()
It retrieves the startup times of the process in a high resolution array of [seconds, nanoseconds]
.
const nsolid = require('nsolid')
nsolid.startupTimes()
{
initialized_node: [ 0, 971137 ],
initialized_v8: [ 0, 181632 ],
loaded_environment: [ 0, 3874746 ]
}
The nsolid.startupTimes()
method can be called asynchronously:
const nsolid = require('nsolid')
nsolid.startupTimes((err, startupTimes)) {
if (!err) {
console.log(startupTimes)
}
}
{
initialized_node: [ 0, 971137 ],
initialized_v8: [ 0, 181632 ],
loaded_environment: [ 0, 3874746 ]
}
nsolid.statsd
The nsolid.statsd
object:
Property |
Description |
counter: |
Send a "counter" type value to statsd. Will use NSOLID_STATSD_BUCKET and NSOLID_STATSD_TAGS if configured. |
format: |
Function that retrieves the statsd agent status. |
gauge: |
Send a "gauge" type value to statsd. Will use NSOLID_STATSD_BUCKET and NSOLID_STATSD_TAGS if configured. |
sendRaw: |
Send a raw string to statsd. Caller is required to comply to statsd format (terminating newline not required). An array of strings is also permissible, they will be sent newline separated. If connected via UDP, data sent via sendRaw() will be split up into 1400Kb batches to fit within a standard MTU window, this applies to newline separated strings or an array of strings passed to this interface. |
set: |
Send a "set" type value to statsd. Will use NSOLID_STATSD_BUCKET and NSOLID_STATSD_TAGS if configured. |
status: |
Function that retrieves the statsd agent status. |
tcpIp: |
If configured, returns the ip address tcp statsd data will be sent to. |
timing: |
Send a "timing" type value to statsd. Will use NSOLID_STATSD_BUCKET and NSOLID_STATSD_TAGS if configured. |
udpIp: |
If configured, returns the ip address udp statsd data will be sent to. |
The statsd statuses are:
- unconfigured
- initializing
- connecting
- ready
Usage example:
const nsolid = require('nsolid')
nsolid.statsd.status()
'unconfigured'
The nsolid.statsd.format
object:
Property |
Description |
bucket: |
Returns the "bucket" string prepended to all auto-generated statsd metric strings. |
counter: |
Format a "counter" string for name and value suitable for statsd. |
gauge: |
Format a "gauge" string for name and value suitable for statsd. |
set: |
Format a "set" string for name and value suitable for statsd. |
timing: |
Format a "timing" string for name and value suitable for statsd. |
Usage example:
const nsolid = require('nsolid')
nsolid.statsd.format.bucket()
''
nsolid.tags
Get the N|Solid app tags (taken from the package.json
file or NSOLID_TAGS
environment variable).
const nsolid = require('nsolid')
nsolid.tags
['nsolid-awesome', 'Auth service']
nsolid.traceStats
The nsolid.traceStats
object:
Property |
Description |
dnsCount: |
The process's total number of DNS lookups performed |
httpClientAbortCount: |
The process's total number of outgoing HTTP(S) client requests canceled due to inactivity. |
httpClientCount: |
The process's total number of outgoing HTTP(S) client requests performed. |
httpServerAbortCount: |
The process's total number of served incoming HTTP(S) requests canceled. |
httpServerCount: |
The process's total number of incoming HTTP(s) requests served. |
nsolid.zmq
The nsolid.zmq
object:
Property |
Description |
status: |
Function that retrieves the zmq agent status. |
The zmq
agent statuses are:
- buffering
- connecting
- initializing
- ready
- unconfigured
Usage example:
const nsolid = require('nsolid')
nsolid.zmq.status()
'ready'