Documentation forSolarWinds Observability SaaS

Configure the Node.js Library

This topic applies to version 14+ of the Node.js Library. If you are using an earlier version, see Configure the Node.js Library (legacy).

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

Configuration options are read from both the environment and an optional configuration file, with environment variables taking precedence over config file values.

All configuration options are optional except for the service key, which is always required.

Configuration file

When required, the package looks for the configuration file in the current working directory under three possible formats, in the following order:

  • solarwinds.apm.config.ts- TypeScript config, which supports all options. It requires a TypeScript loader such as ts-node or tsx.

  • solarwinds.apm.config.js- JavaScript config, which supports all options. .cjs and .mjs extensions are also accepted.

  • solarwinds.apm.config.json- JSON config. It does not support options that cannot exist in JSON, such as functions and custom classes.

It is also possible to use a custom name for the configuration file using the SW_APM_CONFIG_FILE environment variable. The file must have one of the three supported extensions or it will be ignored.

Type checking

The package exports a type for the config file that can be used to type check it when using TypeScript or to add a JSDoc type annotation when using JavaScript.

import type { Config } from "solarwinds-apm"

const config: Config = {
  // ...
}
export default config
/** @type {import('solarwinds-apm').Config} */
module.exports = {
  // ...
}

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.

By default, the service name portion of the service key is used (for example, my-service if the service key is SW_APM_SERVICE_KEY=api-token:my-service). If the OTEL_SERVICE_NAME or OTEL_RESOURCE_ATTRIBUTES environment variable is used to specify a service name, it takes precedence over the default.

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"

Collector

Config file property

collector

System environment variable

SW_APM_COLLECTOR

Description

Set the collector value to define an ingestion endpoint and override the default SolarWinds APM collector endpoint.

To find the endpoint URI for your organization's SolarWinds APM collector, see Data centers and endpoint URIs.

Required

No

History

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

Logging level

The Node.js Library and its underlying native extension library send debug output to stdout. To troubleshoot the Node.js Library, enable debug-level logging (debug or higher).

Config file property

logLevel

System environment variable

SW_APM_LOG_LEVEL

Valid values

verbose, debug, info, warn, error

Required

No

Default

info

History

Introduced with version 14 prerelease of the Node.js Instrumentation Library.

Examples

  • Config file property

    export SW_APM_LOG_LEVEL=debug

  • System environment variable

    "logLevel": "error"

Proxy

Starting with version 15 of the Node.js Library, this option only takes effect when legacy mode is used.

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

Starting with version 15 of the Node.js Library, this option only takes effect when legacy mode is used.

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.

Starting with version 15 of the Node.js Library, this option only takes effect when legacy mode is used.

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.

See also Enable OTLP log export section below.

Valid settings are: false (never insert) or true (insert if a valid span context is available).

Config file property

insertTraceContextIntoLogs

Default

false

History

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

Updated with version 14 of the Node.js Instrumentation Library.

Example

  • Config file property

    "insertTraceContextIntoLogs": true

Enable OTLP log export

Application logs can be automatically exported to SolarWinds Observability when a supported logging library is used by the instrumented service. This property can be used to enable or disable log export.

Config file property

exportLogsEnabled

System environment variable

SW_APM_EXPORT_LOGS_ENABLED

Required

No

Valid values

true or false

Default

false

History

Introduced with version 15 of the Node.js Instrumentation Library.

Examples

  • Config file property 
    "exportLogsEnabled": true

  • System environment variable

    export SW_APM_EXPORT_LOGS_ENABLED=true

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.