Version: 4.10.0

Configuration

N|Solid Runtime

Environment Variables

The N|Solid runtime can be configured via the environment variables listed below. Although each of these environment variables are optional, certain features will be missing or limited in each case. 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_OTLP`	It defines the type of OTLP endpoint we want N
`NSOLID_OTLP_CONFIG`	Specific configuration for the OTLP endpoint tye defined with `NSOLID_OTLP`. See the OpenTelemetry section for more details
`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
`NSOLID_TRACING_ENABLED`	Boolean to indicate if you want N\|Solid to generate traces when connected to an endpoint that supports it. See the Tracing section for more details
`NSOLID_TRACING_MODULES_BLACKLIST`	List of core modules instrumented by N\|Solid you want to disable when tracing is enabled. See the Tracing section for more details
`NSOLID_REDACT_SNAPSHOTS`	Boolean to indicate if you want heap snapshots to obscure string variable contents. This may impede your ability to debug and is meant for sensitive production environments.

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`
`otlp`	`NSOLID_OTLP`
`otlpConfig`	`NSOLID_OTLP_CONFIG`
`tracingEnabled`	`NSOLID_TRACING_ENABLED`
`tracingModulesBlacklist`	`NSOLID_TRACING_MODULES_BLACKLIST`
`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 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_NOTIFICATION_STACK_FRAMES`	Specify the number of frames to be shown in Slack event loop blocked 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 Console

In order to access N|Solid you must have a valid NodeSource account. If you have not connected your Console to your account, when you try and access the console you will be redirected to the welcome screen. Using this form to log into your NodeSource account will automatically configure your Console server and allow you to associate it with your account or organization.

Welcome Screen

Once connected, you should be immediately redirected to the N|Solid Console.

Updating Your License

If you want your Console to be associated with a different account or organization, click Settings on the right side of the menu at the top of the page.

If you are an administrator for the linked organization, you will see a "Reset License" button which can be used to restore the Console to its initial login state.

If you do not have administrative access to the registered license and need to reset the Console's registration state, you can start the Console with the NSOLID_CONSOLE_AUTH_REQUIRE_LOGIN=false environment variable to disable the authentication requirement and allow access to the Reset Console button. Remember to restart without this setting if authentication is still desired.

User Authentication

Beginning with N|Solid 3.4.0, users will be asked to authenticate before they can access the console. If the user is not the owner of the account or a member of the associated organization, they will not be permitted to access the console.

To allow additional users to access your console, add them to the NodeSource Accounts organization which is associated with this Console.

If you do not wish to enforce user authentication, it can be disabled by setting the NSOLID_CONSOLE_AUTH_REQUIRE_LOGIN=false environment variable or its associated config file setting.

This authentication also impacts nsolid-cli. If you require use of the CLI, you should set NSOLID_CONSOLE_AUTH_ADMIN_TOKEN or the corresponding config file setting to a secure value and use it with the --auth argument. This grants administrative access to the console and should be used with discretion. See Command Line Interface for instructions.

Using StatsD 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' }

Configuration

N|Solid Runtime​

Environment Variables​

package.json​

Example package.json:​

N|Solid CLI​

Configuration File​

N|Solid Console​

Command Line Arguments​

Environment Variables​

Stats Retention​

License Keys​

Registering Your Console​

Updating Your License​

User Authentication​

Using StatsD without connecting to Console​

Offline or Air-Gapped operation​

Troubleshooting​

Debug Messages​

N|Solid Runtime

Environment Variables

package.json

Example package.json:

N|Solid CLI

Configuration File

N|Solid Console

Command Line Arguments

Environment Variables

Stats Retention

License Keys

Registering Your Console

Updating Your License

User Authentication

Using StatsD without connecting to Console

Offline or Air-Gapped operation

Troubleshooting

Debug Messages