Version: 6.x (latest)

Configuration

This page explains how to configure the N|Solid Runtime to send data to N|Solid SaaS, a self-hosted N|Solid Console, OpenTelemetry (OTLP) endpoints, and StatsD. It ends with a complete configuration reference.

Configuration methods

You can configure the N|Solid Runtime in three ways:

Environment variables, for example NSOLID_GRPC=localhost:50051.
The nsolid section of your package.json file. The runtime reads the nearest package.json above your main script, or the file named in NSOLID_PACKAGE_JSON.
The JavaScript API, by calling nsolid.start() from your application.

The three methods accept the same settings, except a few that are environment-only (marked env only in the configuration reference). When a setting is defined in more than one place, the runtime uses this order of precedence:

The object passed to nsolid.start()
Environment variables
The nsolid section of package.json
The built-in default

Boolean environment variables are off when unset or set to 0 or false. Any other value turns them on.

By default, the N|Solid Agent thread starts, but it doesn't perform automated checks or send observability data anywhere until you configure an endpoint.

To connect to an N|Solid Console, the minimum configuration is one of NSOLID_SAAS, NSOLID_GRPC, or NSOLID_COMMAND, pointing at your N|Solid SaaS instance or your self-hosted N|Solid Console. The runtime completes the handshake and the Console supplies the rest of the connection settings.

NSOLID_GRPC connects over the gRPC protocol. It's available in N|Solid Runtime 5.4.0 and later and requires N|Solid Console 6.1.0 or later. NSOLID_COMMAND connects over the legacy ZeroMQ protocol.

Running with the agent disabled

If none of NSOLID_SAAS, NSOLID_GRPC, NSOLID_COMMAND, NSOLID_STATSD, or NSOLID_OTLP is set, the agent is created but most functionality is disabled, and the runtime behaves like unmodified Node.js.

In this mode the N|Solid JavaScript API is still active, including nsolid.start(), which you can use to configure and start the N|Solid Agent's connections at any time.

Connect to N|Solid SaaS

N|Solid SaaS is the quickest way to start working with observability data for your application. NodeSource runs a dedicated N|Solid Console for your organization and gives you a connection token that the runtime uses to connect and authenticate.

To find your NSOLID_SAAS token, log in to NodeSource Accounts and copy the connection string. To open your N|Solid Console, click Visit Now.

NodeSource Accounts page showing the NSOLID_SAAS connection string

Environment
package.json
JavaScript API

Set the NSOLID_SAAS token as an environment variable:

NSOLID_SAAS='<your-saas-token>' nsolid index.js

Add the token to the nsolid section of your package.json:

{
  "name": "example",
  "version": "0.0.0",
  "description": "N|Solid configuration example",
  "main": "index.js",
  "nsolid": {
    "saas": "<your-saas-token>"
  }
}

For configurations that depend on runtime logic, start the N|Solid Agent from within your application:

nsolid.start({
  app: 'example',
  appVersion: '0.0.0',
  saas: '<your-saas-token>'
})

After you apply any of these methods, your process connects and appears in the N|Solid Console.

NSOLID_SAAS connects over gRPC with TLS to your N|Solid SaaS Console's gRPC endpoint on port 443.

note

If both NSOLID_SAAS and NSOLID_COMMAND are set, NSOLID_COMMAND takes precedence and the SaaS token is ignored.

Connect to a self-hosted N|Solid Console

To connect to a self-hosted N|Solid Console, specify the address where it listens for agent connections. You can use the gRPC protocol (NSOLID_GRPC, N|Solid Console 6.1.0 and later) or the ZeroMQ protocol (NSOLID_COMMAND).

NSOLID_GRPC: the address of the Console's gRPC endpoint. gRPC uses a single connection. Default Console port: 50051.
NSOLID_COMMAND: the address of the ZeroMQ "command" channel, used for bidirectional communication between the agent and the Console. Default port: 9001.
NSOLID_DATA: the ZeroMQ channel for one-shot replies with small payloads. Default port: 9002.
NSOLID_BULK: the ZeroMQ channel for large, multi-chunk content such as heap snapshots and CPU profiles. Default port: 9003.

With ZeroMQ, the runtime connects to the Console on three ports so that commands and data are prioritized over bulk asset transfers. You only need to set NSOLID_COMMAND: the Console provides the data and bulk addresses during the handshake.

warning

The agent uses TLS for gRPC connections by default. A self-hosted N|Solid Console serves gRPC without TLS unless you put a TLS endpoint in front of it. If your Console's gRPC endpoint isn't behind TLS, set NSOLID_GRPC_INSECURE=1. To trust a private certificate authority instead, set NSOLID_GRPC_CERTS to the path of a PEM file with your CA certificates. Both are environment variables only.

Environment
package.json
JavaScript API

gRPC, to a Console without TLS:

NSOLID_GRPC='localhost:50051' NSOLID_GRPC_INSECURE=1 nsolid index.js

gRPC, to a Console behind TLS with a private CA:

NSOLID_GRPC='console.example.com:50051' NSOLID_GRPC_CERTS=/path/to/ca.pem nsolid index.js

ZeroMQ:

NSOLID_COMMAND='localhost:9001' nsolid index.js

gRPC:

{
  "name": "example",
  "version": "0.0.0",
  "description": "N|Solid configuration example",
  "main": "index.js",
  "nsolid": {
    "grpc": "localhost:50051"
  }
}

Set NSOLID_GRPC_INSECURE or NSOLID_GRPC_CERTS in the environment as needed (see the warning above).

ZeroMQ:

{
  "name": "example",
  "version": "0.0.0",
  "description": "N|Solid configuration example",
  "main": "index.js",
  "nsolid": {
    "command": "localhost:9001"
  }
}

gRPC:

nsolid.start({
  app: 'example',
  appVersion: '0.0.0',
  grpc: 'localhost:50051'
})

Set NSOLID_GRPC_INSECURE or NSOLID_GRPC_CERTS in the environment as needed (see the warning above).

ZeroMQ:

nsolid.start({
  app: 'example',
  appVersion: '0.0.0',
  command: 'localhost:9001'
})

note

Custom commands are only delivered over the ZeroMQ (NSOLID_COMMAND) connection. They aren't available when you connect with NSOLID_GRPC or NSOLID_SAAS.

Connect to an OpenTelemetry endpoint

Three settings control OpenTelemetry export: NSOLID_TRACING_ENABLED, NSOLID_OTLP, and NSOLID_OTLP_CONFIG.

`NSOLID_TRACING_ENABLED`

Tracing is off by default. To enable it at startup, set this flag to a true value. You can also turn tracing on and off while the process runs from the N|Solid Console.

Environment
package.json
JavaScript API
N|Solid Console

NSOLID_TRACING_ENABLED=1 nsolid index.js

{
  "name": "example",
  "version": "0.0.0",
  "description": "N|Solid configuration example",
  "main": "index.js",
  "nsolid": {
    "command": "localhost:9001",
    "tracingEnabled": true
  }
}

nsolid.start({
  app: 'example',
  appVersion: '0.0.0',
  command: 'localhost:9001',
  tracingEnabled: true
})

With tracing enabled, the N|Solid Agent sends trace data to the N|Solid Console automatically if it's connected to one.

info

You must enable tracing to send traces to OTLP endpoints, even if you aren't connected to an N|Solid Console. Metrics are exported to a configured OTLP endpoint on every metrics interval, whether or not tracing is enabled.

`NSOLID_OTLP` and `NSOLID_OTLP_CONFIG`

Use NSOLID_OTLP and NSOLID_OTLP_CONFIG to export traces and metrics to additional endpoints.

NSOLID_OTLP sets the type of endpoint. The options are:

datadog
dynatrace
newrelic
otlp

NSOLID_OTLP_CONFIG is a JSON object with the configuration for the selected type:

Endpoint type	Keys	Example	Behavior
`datadog`	`zone`, `key`, `url` (all required)	`{"zone": "us", "key": "<your-datadog-api-key>", "url": "http://localhost:4318"}`	`zone` is `us` or `eu`. `url` is the base URL of your Datadog Agent's OTLP HTTP receiver; the runtime appends `/v1/traces`. Metrics go to the Datadog API for the selected zone.
`dynatrace`	`site`, `token` (both required)	`{"site": "<your-dynatrace-environment-id>", "token": "<your-dynatrace-api-token>"}`	Traces go to `https://<site>.live.dynatrace.com/api/v2/otlp/v1/traces`, authenticated with `Api-Token <token>`.
`newrelic`	`zone`, `key` (both required)	`{"zone": "us", "key": "<your-newrelic-license-key>"}`	`zone` is `us` or `eu`. Traces go to New Relic's OTLP endpoint for the zone; metrics go to the New Relic Metric API.
`otlp`	`url` (required), `protocol` (optional)	`{"url": "http://localhost:4318", "protocol": "http"}`	`url` is the base URL of the collector, with scheme and port; the runtime appends `/v1/traces` and `/v1/metrics`. `protocol` is `http` (default) or `grpc` (typically port 4317).

warning

If NSOLID_OTLP_CONFIG is missing a required key or isn't valid JSON, OTLP export is disabled. The only exception is NSOLID_OTLP=otlp, which works without NSOLID_OTLP_CONFIG (see below).

Environment
package.json
JavaScript API

NSOLID_TRACING_ENABLED=1 NSOLID_OTLP=dynatrace NSOLID_OTLP_CONFIG='{"site":"<your-dynatrace-environment-id>","token":"<your-dynatrace-api-token>"}' nsolid index.js

{
  "name": "example",
  "version": "0.0.0",
  "description": "N|Solid configuration example",
  "main": "index.js",
  "nsolid": {
    "command": "localhost:9001",
    "tracingEnabled": true,
    "otlp": "otlp",
    "otlpConfig": { "url": "http://localhost:4318", "protocol": "http" }
  }
}

nsolid.start({
  app: 'example',
  appVersion: '0.0.0',
  command: 'localhost:9001',
  tracingEnabled: true,
  otlp: 'datadog',
  otlpConfig: { zone: 'eu', key: '<your-datadog-api-key>', url: 'http://localhost:4318' }
})

Standard OpenTelemetry exporter variables

With NSOLID_OTLP=otlp, you can omit NSOLID_OTLP_CONFIG and configure the exporter with the standard OpenTelemetry environment variables instead:

OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT
OTEL_EXPORTER_OTLP_PROTOCOL (and the _TRACES_ / _METRICS_ variants): grpc or http/protobuf (default). http/json applies to metrics only; traces are always sent as protobuf over HTTP.
OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_CERTIFICATE, OTEL_EXPORTER_OTLP_CLIENT_KEY, OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, OTEL_EXPORTER_OTLP_COMPRESSION, OTEL_EXPORTER_OTLP_TIMEOUT, OTEL_EXPORTER_OTLP_INSECURE (and their _TRACES_ / _METRICS_ variants)

NSOLID_TRACING_ENABLED=1 NSOLID_OTLP=otlp OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 nsolid index.js

Run nsolid --help to see the full list of variables supported by your runtime version.

Connect to a StatsD endpoint

`NSOLID_STATSD`

To send N|Solid metrics to a StatsD daemon, set NSOLID_STATSD to its address. The format is [udp://|tcp://]host[:port]. The protocol defaults to UDP and the port to 8125. A bare number is treated as a port on localhost. Only UDP and TCP are supported.

Environment
package.json
JavaScript API
N|Solid Console

NSOLID_STATSD=localhost:8125 nsolid index.js

Use TCP instead of UDP:

NSOLID_STATSD=tcp://statsd.example.com:8125 nsolid index.js

{
  "name": "example",
  "version": "0.0.0",
  "description": "N|Solid configuration example",
  "main": "index.js",
  "nsolid": {
    "command": "localhost:9001",
    "statsd": "localhost:8125"
  }
}

nsolid.start({
  app: 'example',
  appVersion: '0.0.0',
  command: 'localhost:9001',
  statsd: 'localhost:8125'
})

You can set the StatsD information in the configuration modal. To open it, click Process Configuration in the single process view:

Single process information panel

In this modal you can view and change NSOLID_STATSD, NSOLID_STATSD_BUCKET, and NSOLID_STATSD_TAGS:

Configuration modal

StatsD bucket names

StatsD metrics are reported using "buckets". The right format depends on your reporting frontend and may take some experimentation.

By default, N|Solid prefixes bucket names with nsolid.${env}.${app}.${hostname}.${shortId}., followed by the name of the metric. In this string:

env is the value of the NODE_ENV environment variable if set, otherwise the env property of the nsolid section in package.json. Defaults to prod.
app is the value of the NSOLID_APP environment variable (NSOLID_APPNAME is accepted as an alias and takes precedence), otherwise the app property of the nsolid section in package.json, otherwise the name property in package.json, otherwise process.title if your application changed it. Defaults to untitled application.
hostname is the value of the NSOLID_HOSTNAME environment variable if set, otherwise the hostname property of the nsolid section in package.json. Otherwise, the value of os.hostname() is used.
shortId is the first 7 characters of the random alphanumeric ID the N|Solid Agent creates at startup. Use it to identify individual processes. The full 40-character ID is available as id.

By default, your StatsD data is sent to the collector in this format:

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
...

All metrics are sent as gauges (|g). The string metrics user and title aren't sent.

StatsD tags

Some backends, such as Datadog, support tags for metrics.

By default, N|Solid adds no tags to process-level metrics. Per-thread metrics always carry threadId:<id> (and threadName:<name> if the thread is named) as DogStatsD-style tags.

`NSOLID_STATSD_BUCKET` and `NSOLID_STATSD_TAGS`

To change the bucket prefix or add tags to your StatsD data, use NSOLID_STATSD_BUCKET and NSOLID_STATSD_TAGS (or the statsdBucket and statsdTags properties of the nsolid section in package.json).

Both settings support substitution of the variables listed above: env, app, hostname, shortId, and id. Write them in template-literal style, for example ${app}. The default bucket prefix is written as nsolid.${env}.${app}.${hostname}.${shortId}.

NSOLID_STATSD_TAGS also supports ${tags}, which inserts the N|Solid tags configured for the process.

StatsD tags are a comma-separated string that your backend can decode. Check your StatsD provider's documentation to find out whether it supports tags and what format it expects.

Substitution follows these rules:

Variable names are case-insensitive (${shortId} and ${shortid} are equivalent).
Periods (.) in substituted values are replaced with hyphens (-), so a hostname like web.example.com becomes web-example-com. In tags, every period in the resulting string is replaced.

Environment
package.json
JavaScript API
N|Solid Console

NSOLID_STATSD=localhost:8125 NSOLID_STATSD_BUCKET='COOLCORP.${env}.${app}.${hostname}.${shortId}' NSOLID_STATSD_TAGS='env:${env},${tags}' nsolid index.js

{
  "name": "example",
  "version": "0.0.0",
  "description": "N|Solid configuration example",
  "main": "index.js",
  "nsolid": {
    "command": "localhost:9001",
    "statsd": "localhost:8125",
    "statsdBucket": "COOLCORP.${env}.${app}.${hostname}.${shortId}",
    "statsdTags": "env:${env},app:${app}"
  }
}

nsolid.start({
  app: 'example',
  appVersion: '0.0.0',
  command: 'localhost:9001',
  statsd: 'localhost:8125',
  statsdBucket: 'COOLCORP.${shortId}',
  statsdTags: 'env:${env},app:${app}'
})

You can set the StatsD information in the configuration modal. To open it, click Process Configuration in the single process view:

Single process information panel

In this modal you can view and change NSOLID_STATSD, NSOLID_STATSD_BUCKET, and NSOLID_STATSD_TAGS:

Configuration modal

Configuration reference

Each table lists the environment variable, the equivalent key for the nsolid section of package.json and for nsolid.start(), the default, and a description. Settings marked "env only" have no package.json or JavaScript equivalent.

Connection

Environment variable	Key	Default	Description
`NSOLID_SAAS`	`saas`	none	N\|Solid SaaS token. Connects over gRPC with TLS on port 443. Ignored if `NSOLID_COMMAND` is set.
`NSOLID_GRPC`	`grpc`	none	`host:port` of a self-hosted N\|Solid Console's gRPC endpoint (Console default port 50051). A bare number means `localhost:<port>`. N\|Solid Runtime 5.4.0 and later; requires N\|Solid Console 6.1.0 or later.
`NSOLID_GRPC_INSECURE`	env only	`0` (TLS on)	Set to `1` to connect to a gRPC endpoint without TLS. Must be an integer. Ignored for N\|Solid SaaS.
`NSOLID_GRPC_CERTS`	env only	bundled root CAs	Path to a PEM file with the CA certificates to trust for gRPC TLS.
`NSOLID_COMMAND` (legacy alias `NSOLID_COMMAND_REMOTE`, which takes precedence)	`command`	none	Address of the Console's ZeroMQ command channel (default port 9001). A bare number means `localhost:<port>`.
`NSOLID_DATA` (legacy alias `NSOLID_DATA_REMOTE`, which takes precedence)	`data`	supplied by the Console	ZeroMQ data channel (default port 9002). Normally provided during the handshake.
`NSOLID_BULK` (legacy alias `NSOLID_BULK_REMOTE`, which takes precedence)	`bulk`	supplied by the Console	ZeroMQ bulk channel (default port 9003). Normally provided during the handshake.
`NSOLID_PUBKEY` (legacy alias `NSOLID_STORAGE_PUBKEY`, which takes precedence)	`pubkey`	built-in default key	The Console's 40-character CurveZMQ public key. Set this if you generated new keys for your Console (see `nsolid-cli generate-keypair`).
`NSOLID_DISABLE_IPV6`	`disableIpv6`	`false`	Disable IPv6 for ZeroMQ connections, for hosts that don't support it.

Identity

Environment variable	Key	Default	Description
`NSOLID_APP` (alias `NSOLID_APPNAME`, which takes precedence)	`app`	package.json `name`, then `process.title` if changed, then `untitled application`	Application name shown in the Console.
(none)	`appVersion` in `nsolid.start()`	package.json `version`	Application version.
`NSOLID_TAGS`	`tags` (comma-separated string or array)	none	Tags used to filter processes in the Console. Up to 20 tags, each 2 to 140 bytes.
`NSOLID_HOSTNAME`	`hostname`	`os.hostname()`	Overrides the reported hostname.
`NODE_ENV`	`env`	`prod`	Environment name. Reported as `nodeEnv` and available as `${env}` in StatsD templates.
`NSOLID_PACKAGE_JSON`	env only	nearest package.json above the main script	Path of the package.json to read N\|Solid configuration from. An empty string disables package.json lookup.

Tracing

Environment variable	Key	Default	Description
`NSOLID_TRACING_ENABLED`	`tracingEnabled`	`false`	Generate spans for HTTP client and server requests, DNS lookups, and custom OpenTelemetry spans. Can be changed from the Console.
`NSOLID_TRACE_SAMPLE_RATE`	`traceSampleRate`	`1.0`	Fraction of traces to sample, from `0.0` to `1.0`. Invalid values are ignored. N\|Solid 6.3.0 and later.
`NSOLID_TRACING_MODULES_BLACKLIST`	`tracingModulesBlacklist` (string or array)	none	Comma-separated core modules to exclude from automatic instrumentation: `dns`, `http` (covers HTTP client and server).

Assets and profiling

Environment variable	Key	Default	Description
`NSOLID_ASSETS_ENABLED`	`assetsEnabled`	`true`	Set to `0` or `false` to block CPU profiles, heap profiles, heap samples, and heap snapshots, including continuous profiling. Can be changed from the Console or with `nsolid.enableAssets()` and `nsolid.disableAssets()`. N\|Solid 6.1.0 and later.
`NSOLID_DISABLE_SNAPSHOTS`	`disableSnapshots`	`false`	Disable heap snapshots for the process. Once on, it can't be turned off.
`NSOLID_REDACT_SNAPSHOTS`	`redactSnapshots`	`false`	Redact all string values from heap snapshots.
`NSOLID_CONT_CPU_PROFILE`	`contCpuProfile`	`false`	Continuous CPU profiling. Profiles are delivered only over gRPC (`NSOLID_GRPC` or `NSOLID_SAAS`) connections. While continuous profiling is on, the runtime rejects on-demand CPU profiles over gRPC, whether they come from the Console, `nsolid-cli profile`, or `nsolid.profile()`.
`NSOLID_CONT_CPU_PROFILE_INTERVAL`	`contCpuProfileInterval`	`30000`	Length of each continuous-profile window, in milliseconds.

Metrics

Environment variable	Key	Default	Description
`NSOLID_INTERVAL`	`interval`	`5000`	Metrics collection and reporting interval, in milliseconds. (The default changed from 3000 to 5000 in N\|Solid 6.2.0.)
`NSOLID_BLOCKED_LOOP_THRESHOLD`	`blockedLoopThreshold`	`200`	Time, in milliseconds, a single event loop iteration can run before the process is reported as blocked.
`NSOLID_PROMISE_TRACKING`	`promiseTracking`	`false`	Track promises, which enables the `promiseCreatedCount` and `promiseResolvedCount` metrics. Can be changed from the Console.
`NSOLID_DISABLE_PACKAGE_SCAN`	`disablePackageScan`	`false`	Don't scan `node_modules` directories at startup. Only packages the application actually loads are reported.
`NSOLID_TRACK_GLOBAL_PACKAGES`	`trackGlobalPackages`	`false`	Also scan the global module paths (`require('module').globalPaths`).

StatsD

Environment variable	Key	Default	Description
`NSOLID_STATSD`	`statsd`	none	StatsD address, `[udp://\|tcp://]host[:port]`. UDP and port 8125 by default.
`NSOLID_STATSD_BUCKET`	`statsdBucket`	`nsolid.${env}.${app}.${hostname}.${shortId}`	Bucket prefix template.
`NSOLID_STATSD_TAGS`	`statsdTags`	none	Tag template string (DogStatsD format).

OTLP

Environment variable	Key	Default	Description
`NSOLID_OTLP`	`otlp`	none	Endpoint type: `otlp`, `datadog`, `dynatrace`, or `newrelic`.
`NSOLID_OTLP_CONFIG`	`otlpConfig`	none	JSON configuration for the selected type. See `NSOLID_OTLP` and `NSOLID_OTLP_CONFIG`.
`OTEL_EXPORTER_OTLP_*`	env only	OpenTelemetry defaults	Standard OpenTelemetry exporter settings, used when `NSOLID_OTLP=otlp` and `NSOLID_OTLP_CONFIG` is not set.

Advanced

Environment variable	Key	Default	Description
`NSOLID_DELAY_INIT`	env only	`0`	Delay, in milliseconds, before the agent starts after the process starts.
`NSOLID_IISNODE`	`iisNode`	`false`	Set when running under iisnode, so the runtime reports the real main script.
`NSOLID_GRPC_KEYLOG`	env only	off	For debugging only: writes TLS session keys to `./nsolid-tls-keylog-<pid>.log`. N\|Solid 6.2.0 and later.

Configuration methods​

Running with the agent disabled​

Connect to N|Solid SaaS​

Connect to a self-hosted N|Solid Console​

Connect to an OpenTelemetry endpoint​

NSOLID_TRACING_ENABLED​

NSOLID_OTLP and NSOLID_OTLP_CONFIG​

Standard OpenTelemetry exporter variables​

Connect to a StatsD endpoint​

NSOLID_STATSD​

StatsD bucket names​

StatsD tags​

NSOLID_STATSD_BUCKET and NSOLID_STATSD_TAGS​

Configuration reference​

Connection​

Identity​

Tracing​

Assets and profiling​

Metrics​

StatsD​

OTLP​

Advanced​

Configuration methods

Running with the agent disabled

Connect to N|Solid SaaS

Connect to a self-hosted N|Solid Console

Connect to an OpenTelemetry endpoint

`NSOLID_TRACING_ENABLED`

`NSOLID_OTLP` and `NSOLID_OTLP_CONFIG`

Standard OpenTelemetry exporter variables

Connect to a StatsD endpoint

`NSOLID_STATSD`

StatsD bucket names

StatsD tags

`NSOLID_STATSD_BUCKET` and `NSOLID_STATSD_TAGS`

Configuration reference

Connection

Identity

Tracing

Assets and profiling

Metrics

StatsD

OTLP

Advanced