Documentation forSolarWinds Observability SaaS

Configure the Node.js Library (legacy)

This topic applies to versions earlier than version 14 of the Node.js Library. If you are using version 14, see Configure the Node.js Library.

The Node.js Library provides many settings that can be used to modify the library's behavior, control security options, or disable individual instrumentation.

Set configuration options

The Service key is the only required configuration, everything else is optional. Configuration options can be set by defining a system environment variable, modifying configuration options in a JSON file, or programmatically modifying an object. Not all configuration options are available to be set programmatically or using the JSON config file.

If the same configuration option is set in multiple locations, the setting is applied with the following precedence:

  1. System environment variable

  2. JSON configuration

  3. Programmatic configuration

Using the JSON config file, configuration options can be applied to the full Node.js Library or to each "probe", or the sub-component instrumentation, so that you can disable instrumentation or disable collecting backtraces on a per-probe basis. Store the JSON configuration data in a file named either solarwinds-apm-config.json or solarwinds-apm-config.js at the root of your app, and it will get loaded when the solarwinds-apm module starts up. An example is included in the library package, and you can see the full probe options in the probe-default.js file that is distributed with the library.

To apply certain settings programmatically, modify the object returned when requiring solarwinds-apm. For example:

const apm = require('solarwinds-apm')
apm.hostnameAlias = 'apm-host-east'

See the Node.js readme for more information.

Commonly used configuration options

The following is a list of the commonly used instrumentation configuration options. For more details, please refer to the library's configuration guide.

Service key

The Service key is used to identify your account and the service being instrumented. It is shown in the Add Data dialog when you add the new service.

It is a required configuration and should be in the form of YourApiToken:YourServiceName. Replace YourApiToken with the SolarWinds Observability API token (ingestion type) generated for this service, and replace YourServiceName with your chosen name for this service. See API Tokens.

The service name is also called the entity's service ID in SolarWinds Observability SaaS. The service name can also be seen in the Overview tab in the service entity's Entity Explorer details view. Editing the display name of the service entity in SolarWinds Observability SaaS does not affect the Service key.

Config file property

serviceKey

System environment variable

SW_APM_SERVICE_KEY

Required

Yes

History

Introduced with version 11.0.0-prerelease of the Node.js Instrumentation Library.

Examples

  • Config file property

    "serviceKey": "ABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123ab:my-service"

  • System environment variable

    export SW_APM_SERVICE_KEY="ABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123abcABC123ab:my-service"

Hostname alias

An optional logical/readable hostname that can be used to easily identify the host.

Config file property

hostnameAlias

System environment variable

SW_APM_HOSTNAME_ALIAS

Default

Unset

History

Introduced with version 11.0.0-prerelease of the Node.js Instrumentation Library.

Examples

  • Config file property

    "hostnameAlias": "apm-host-east"

  • System environment variable

    export SW_APM_HOSTNAME_ALIAS=apm-host-east

Proxy

Configure this if a proxy needs to be used to communicate with the SolarWinds APM collector. The format should either be http://<proxyHost>:<proxyPort> for a proxy server that does not require authentication, or http://<username>:<password>@<proxyHost>:<proxyPort> for a proxy server that requires basic authentication.

While HTTP is the only type of connection supported, the traffic to SolarWinds APM collector is still encrypted using SSL/TLS.

Config file property

proxy

System environment variable

SW_APM_PROXY

Default

no default

History

Introduced with version 11.0.0-prerelease of the Node.js Instrumentation Library.

Examples

  • Config file property

    "proxy": "http://proxy.example.com:8080"

  • System environment variable

    export SW_APM_PROXY=http://proxy.example.com:8080

Trusted certificate path

The library and its native extension use the system trusted CA certificates to verify the TLS connection to the collector. To override the default, define the trusted certificate path configuration option with an absolute path to a specific trusted certificate file in PEM format.

System environment variable

SW_APM_TRUSTEDPATH

JSON configuration key

trustedPath

Required

No

Examples

  • System environment variable

    export SW_APM_TRUSTEDPATH=/path/to/cacert.pem

  • JSON configuration key

    "trustedPath": "/path/to/cacert.pem"

Automatic insertion of Trace ID into logs

Enables the automatic insertion of the trace ID into supported log packages.

Application logs for your service entity are not included in the data sent by APM libraries. Configure your server or application to send application logs to SolarWinds Observability SaaS. See Add logs from services.

Valid settings are: false - never insert, true or 'traced' - insert when traced, 'sampledOnly' - insert only when the trace is sampled, 'always' - insert an all-zeroes dummy value if not tracing. There are two options which enable the feature for different loggers:

bunyan, pino and winston

The object {sw: {traceId: '...'}} will be inserted into the logger’s metadata. The way that appears in the log varies with the logging package and version of the package.

Config file property

insertTraceIdsIntoLogs

Default

false

History

Introduced with version 11.0.0-prerelease of the Node.js Instrumentation Library.

Example

  • Config file property

    "insertTraceIdsIntoLogs": true

morgan

The string trace_id=... span_id=... trace_flags=... will be appended to logged messages. The library achieves this by modifying the morgan log format for predefined formats. To insert using custom formats use the :trace token.

Config file property

insertTraceIdsIntoLogs

Default

false

History

Introduced with version 11.0.0-prerelease of the Node.js Instrumentation Library.

Example

  • Config file property

    "insertTraceIdsIntoLogs": true

Agent log level

Configure the level(s) at which the library writes log messages, these are normally seen in the webserver logs and will be prefixed with the log level issuing the message, e.g., solarwinds-apm:error. The log levels are not strictly levels - they are individual settings (see https://github.com/visionmedia/debug). They can be set via the environment variable SW_APM_LOG_SETTINGS or in the code using logLevel. If the SW_APM_LOG_SETTINGS environment variable is not set it will default to enabling error and warn; if SW_APM_LOG_SETTINGS is set to empty it will suppress all library log messages.

Config file property

logLevel

System environment variable

SW_APM_LOG_SETTINGS

Default

error,warn

History

Introduced with version 11.0.0-prerelease of the Node.js Instrumentation Library.

Examples

  • Config file property

    "logLevel": "error,warn,info"

  • System environment variable

    export SW_APM_LOG_SETTINGS=error,warn,info

Addon log level

Increase or decrease the log level of the C++ addon used by the library. It takes the following values: 0 fatal, 1 error, 2 warning, 3 info (the default), 4 debug low, 5 debug medium, 6 debug high. Increase the logging verbosity to one of the debug levels to get more detailed information sent to stderr.

Config file property

None. The addon’s debug level can only be specified by environment variable.

System environment variable

SW_APM_DEBUG_LEVEL

Default

3

History

Introduced with version 11.0.0-prerelease of the Node.js Instrumentation Library.

Example

  • System environment variable

    export SW_APM_DEBUG_LEVEL = 6

The scripts are not supported under any SolarWinds support program or service. The scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.