Documentation forSolarWinds Observability

Install the Node.js Library (legacy)

This topic applies to versions earlier than version 14 prerelease of the Node.js Library. To install version 14 prerelease, see Install the Node.js Library.

The Node.js Library is distributed as the npm package solarwinds-apm. Install the package, require it in your application, and automatically get visibility into the frameworks and components used by your application.

Before you start

Verify the following to ensure the library can collect and transmit data:

  • The platform where your APM library will be installed is supported.

  • Your application components are supported by the library.

  • Your firewall configuration permits TCP/HTTPS/TLS outbound connections to apm.collector.xx-yy.cloud.solarwinds.com (where xx-yy is determined by the URL you use to access SolarWinds Observability, described in Data centers and endpoint URIs) using port 443. See Firewall or access control requirements.

    If your firewall or access control requirements do not allow such connections, configure the library to send data through a proxy.

Do not run other APM libraries alongside the SolarWinds Observability Node.js Library. Remove other APM libraries from your Node.js application before using the SolarWinds Observability Node.js Library.

Install the library

The library requires a C++ addon package called solarwinds-apm-bindings.

Our C++ addon currently supports Linux only. The library can be installed on other platforms such as OS X but will run in "no-op" mode where it does not emit trace data or metrics.

The C++ addon is compiled into a binary with system and Node.js version dependencies, so the installed library package on one platform cannot just be copied onto a different platform; instead, the library must be installed specifically on each different platform.

Installation steps

The library can be installed via the standard npm command, for example:

npm install --save solarwinds-apm

You may need to use npm's --unsafe-perm option to work around the "cannot run in wd" error when npm install is run as the root user (which may be the default in a docker container). For example:

npm install --unsafe-perm --save solarwinds-apm

Enable the library

The library requires a service key to connect to your account, and must be required into your application code.

Service key

The library requires a service key to connect to your account. This is set via the SW_APM_SERVICE_KEY environment variable or the serviceKey config file property. When using the environment variable, make sure it is available in the environment where your application is running:

export SW_APM_SERVICE_KEY="api-token-here:your-service-name"

A service key is composed of an API token with write permissions and the name of the service you're installing on. Our onboarding flow provides the full service key, or check the API Tokens page to grab a token and fill the service name yourself.

Load the library

To load the library into your application use one of the two following methods:

  • Require solarwinds-apm in your application start command (run time). This is the recommended method.

    Example:

    node -r solarwinds-apm <app.js>
  • Require solarwinds-apm in your entry point file before any other require() calls (build time).

    Example:

    // must be first require
    require('solarwinds-apm')
    const express = require('express')
    const app = express()
    app.get('/', (req, res) => res.send('Hello World!'))
    app.listen(3000, () => console.log('Example app listening on port 3000!'))

You can find more troubleshooting information in the Installation warning section of the library README file.

Remove the library

Make sure your application entry point file no longer requires solarwinds-apm, and then uninstall it with:

npm uninstall --save solarwinds-apm

Azure App Service

Deploying applications with the SolarWinds Observability Node.js Library to Azure App Service on Linux has been tested using the vscode's Azure App Service extension, the azure CLI client "az", and the local git repository method. No special processing is required, but make sure that you don't change the default which is that the build is done by the deployment engine.

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.