Documentation forSolarWinds Observability

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

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

    sw.hostnameAlias = 'apm-host-east'
  • System environment variable

    export SW_APM_HOSTNAME_ALIAS=apm-host-east 

Automatic insertion of Trace ID into logs

Enables the automatic insertion of the trace ID into supported log packages. 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

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