solarwinds-apm

solarwinds-apm

The new OpenTelemetry-based SolarWinds APM Node.js library. Currently supports Node.js ^18.19.0, ^20.8.0, 22 and 24.

This library automatically instruments a wide set of frameworks and libraries, see the Module Compatibility table for details.

Installation and Setup

npm install --save "solarwinds-apm" "@opentelemetry/api@^1.9.0"

Install using your package manager then follow the configuration guide. Make sure to install the matching version of @opentelmetry/api as it is required for the library to work. The two packages should be updated at the same time and kept in sync.

The library can then be initialised either from the command line or the environment.

node --import solarwinds-apm script.js

export NODE_OPTIONS="--import solarwinds-apm"

npm start

Legacy mode

With the 15.0.0 release, major parts of the library were rewritten in pure JavaScript to replace the previously used native library. The new codebase makes it possible to run the library on platforms other than Linux, however it is not compatible with AppOptics and some niche features might be unimplemented. The legacy code can be turned back on manually by setting the SW_APM_LEGACY environment variable to true.

Custom Instrumentation and Metrics

Unlike previous non-OpenTelemetry version, all manual instrumentation and metrics collection are handled through the OpenTelemetry API using the @opentelemetry/api packages. The OpenTelemetry JS documentation for manual instrumentation provides instructions (note that solarwinds-apm takes care of the initial registration of all components), and the SDK docs are available to see all that the API provides.

An example of using manual instrumentation APIs in tandem with the library is available in the main repository.

Waiting at Startup

The library needs to perform some initialisation work before it's able to collect traces. If startup time is not a concern, it's possible to wait for the library to be ready before doing anything else.

import { waitUntilReady } from "solarwinds-apm"
// or
const { waitUntilReady } = require("solarwinds-apm")

// wait up to 10 seconds
await waitUntilReady(10_000)

Custom Transaction Names

Transaction names are automatically derived from various trace attributes by solarwinds-apm. However it is also possible to override the automatic name by calling setTransactionName from any code within the transaction.

import { setTransactionName } from "solarwinds-apm"
// or
const { setTransactionName } = require("solarwinds-apm")

function calledFromWithinTransaction() {
  setTransactionName("custom-transaction")
}

Flushing pending telemetry data

The library internally batches data before sending it to the platform to be more efficient. However in some scenarios it is desirable to force the data to be sent immediately. Calling forceFlush does exactly this.

import { forceFlush } from "solarwinds-apm"
// or
const { forceFlush } = require("solarwinds-apm")

// by the time this resolves the data will have been sent
await forceFlush()

Migrating from 14.x.x

Any use of the --require solarwinds-apm or --loader solarwinds-apm/loader flags must be replaced by --import solarwinds-apm. The waitUntilReady function now returns a promise instead of blocking, which might require code which uses it to be refactored.

Migrating from legacy versions

When migrating from older versions not built on top of OTel, @opentelemetry/api@^1.9.0 must be added as an extra dependency. The config file will also need to be renamed and updated as some of the fields have changed, see the configuration guide for details. Manual instrumentation and metrics will also need to be migrated to use the OTel API, except for the instrument and pInstrument methods which are provided by the @solarwinds-apm/compat package to facilitate migrating.

- const { instrument, pInstrument } = require("solarwinds-apm")
+ const { instrument, pInstrument } = require("@solarwinds-apm/compat")

Diagnostic script

A script that checks for common issues and prints a full report is available in this repository. Simply copy its contents to a JavaScript file in the same directory as the instrumented application and run it from the same place as the application. The printed report can be very large so it can be useful to pipe the output to a file. For instance, node diagnostic.js > report. It is also possible to require the script directly from within an instrumented application to ensure it runs it the same environment. For instance, adding the line require("./diagnostic.js").