Configuration
There are multiple ways to send configuration to the N|Solid Runtime:
- Environment-based
- File-based config
- JavaScript runtime configuration
Each of these three options can be used in the same way with the same outcome and it is entirely up to your requirements for implementation.
The default configuration of N|Solid will only start up the agent partially, the Agent thread will start, but it will not perform any automated checks or attempt to send any observability data anywhere without an endpoing configured.
To connect to an N|Solid Console Server, the minimum configuration for starting the N|Solid Agent with observability in place is the NSOLID_SAAS
or NSOLID_GRPC
or NSOLID_COMMAND
address for either your N|Solid SaaS Server instance, or your on-premise N|Solid Console Server. This will enable it to handshake and successfully complete the connection and the N|Solid Console Server will complete the networking setup configuration.
NSOLID_GRPC
is supported starting with N|Solid 6.1.0 for gRPC connections to the N|Solid Console Server. Earlier versions of N|Solid do not support this configuration. You can use NSOLID_GRPC
instead of NSOLID_COMMAND
to connect to the N|Solid Console Server, leveraging the gRPC protocol instead of the legacy ZeroMQ protocol.
Running with the Agent Disabled
If no configuration options are set for any of NSOLID_SAAS
, NSOLID_GRPC
, NSOLID_COMMAND
, NSOLID_STATSD
, or NSOLID_OLTP
defined to instruct it where to send data, the agent is created but most functionality is disabled and the runtime will behave just like unmodified Node.js.
When running in this mode, the N|Solid JavaScript API will still be active, including the nsolid.start
function that can be used to configure and start the N|Solid Agent's communication channels.
Connecting to N|Solid Pro SAAS
The simplest way to start working with Observability data for your application is to use N|Solid SAAS. In this setup we start and operate a N|Solid Console Server in the cloud just for your systems and provide a connection string to configure the N|Solid Runtime to connect and authenticate to your dedicated server.
To find your NSOLID_SAAS
connection screen, log into NodeSource Accounts and copy the connection string provided. To visit your N|Solid Console Server, click the Visit Now link.
Any of these three techniques should cause your process to connect and be found in the N|Solid Pro Console.
Connecting to an on-premise N|Solid Console Server
To connect to a self-operated N|Solid Console Server you must specify the NSOLID_COMMAND
address where it listens for incoming agent connections. The N|Solid Console Server currently connects to the N|Solid Runtime on three different network ports in order to prioritize commands and data over bulk asset contents. Only the NSOLID_COMMAND
must be specified as the N|Solid Console Server will provide the other addresses during handshake over the NSOLID_COMMAND
channel.
NSOLID_GRPC
-- The address for the gRPC protocol for bidirectional communication between the Agent and the Console Server. Default port: 50051 (N|Solid 6.1.0 and later)NSOLID_COMMAND
-- The address for the "COMMAND" channel for bidirectional communication betwen the Agent and the Console Server. Default port: 9001NSOLID_DATA
-- The address for one-shot data replies that contain smaller payloads. Default port: 9002NSOLID_BULK
-- The address for large, multi-chunk streamed content such as Heap Snapshots or CPU Profies. Default port: 9003
Connecting to an OpenTelemetry endpoint
There are three key configuration variables necessary to fully enable OpenTelemetry.
NSOLID_TRACING_ENABLED
Tracing is not enabled by default. To do so at startup, this flag must be set to a true value. Tracing can be enabled and disabled during the life of the process remotely in the N|Solid Pro UI.
With tracing enabled, if the N|Solid Agent has an N|Solid Console connection, it will automatically start sending trace data.
:::important
Even if you aren't connecting to a N|Solid Console Server, you must enable tracing to send OTLP data to other configured endpoints.
:::
NSOLID_OTLP
and NSOLID_OTLP_CONFIG
To configure additional endpoints, the NSOLID_OTLP
and NSOLID_OTLP_CONFIG
are used to specify where and how to send the traces.
NSOLID_OTLP
defines the type of endpoint we're exporting the traces to. Current options are:
datadog
dynatrace
newrelic
otlp
NSOLID_OTLP_CONFIG
defines the configuration for the type of endpoint selected in NSOLID_OTLP
. This table provides examples of the configuration object for each type of endpoint:
Endpoint Type | Keys | Format |
---|---|---|
datadog |
zone, key, url |
{ zone: 'us' | 'eu', key: 'your_datadog_key', url: 'otlp_endpoint_url' } |
dynatrace |
site, token |
{ site: 'you_dynatrace_size', token: 'your_dynatrace' } |
newrelic |
zone, key |
{ zone: 'us' | 'eu', key: 'your_datadog_key' } |
otlp |
url, protocol |
{ url: 'otlp_endpoint_url', protocol: 'http' | 'grpc' } |
Connecting to a STATSD endpoint
NSOLID_STATSD
To send N|Solid metrics to a StatsD endpoint, all that is required is the url configured as NSOLID_STATSD
StatsD metrics are reported using "buckets". This format 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 theNSOLID_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 theNSOLID_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, orprocess.title
if it has been set. Defaults to"untitled application"
if not otherwise supplied.hostname
is the value of theNSOLID_HOSTNAME
environment variable if it exists, or the"hostname"
property of the"nsolid"
section in package.json if it exists. Otherwise, the value ofos.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 asid
if required.
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.
NSOLID_STATSD_BUCKET
and NSOLID_STATSD_TAGS
To alter the default configuration for bucket and tag decorators for your StatsD data, you can use the NSOLID_STATSD_BUCKET
and NSOLID_STATSD_TAGS
variables.
Both NSOLID_STATSD_BUCKET
and NSOLID_STATSD_TAGS
support variable substitution for the keys listed in the table above. In the config string use ${template}
literal style quoting to susbstitute those values.
For example: The default bucket prefix would be specified as follows: "nsolid.${env}.${app}.${hostname}.${shortId}"
.
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 statsd provider documentation to find out if tags are supported and what you should set them to.