Documentation forAppOptics

Install the Node.js Agent

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

Installing the Agent

The agent requires a C++ addon package called @appoptics/apm-bindings. Starting with agent version 10.0.0, on LTS versions of Node.js the node-pre-gyp package will be used during bindings installation to download the correct pre-compiled add-on binary. This eliminates the need for the system dependencies and speeds up the installation time.

If you are running an LTS version of Node.js and are installing version 10.0.0 or later of the agent, you can skip the dependencies section and go directly to the Install steps section below.

However, if you are not running an LTS version of Node.js or are installing an agent version prior to 10.0.0, the add-on must be compiled during bindings installation. Ensure the system Dependencies are met before you follow the Install steps.


If you are not running an LTS version of Node.js, or if you’re installing an agent version prior to 10.0.0, the add-on must be compiled during bindings installation thus you’ll need to ensure the following system dependencies are met.

  • gcc version 4.7 and above
  • for node-gyp: make and python 2.x (version 2.7 is recommended)

Note that some systems may provide multiple python versions, in which case you would need to specify the correct package name for python 2.7.

On Debian/Ubuntu:

sudo apt-get install g++ make python

On RHEL/CentOS/Amazon Linux:

sudo yum install gcc-c++ make python

On Alpine:

$ sudo apk add g++ make python

Our C++ addon currently supports Linux only. The agent will install 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 agent package on one platform cannot just be copied onto a different platform; instead, the agent must be installed specifically on each different platform.

Install steps

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

npm install --save appoptics-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). See NPM install failed with "cannot run in wd" (© 2020 Stack Exchange Inc, available at, obtained on October 26, 2020). For example:

npm install --unsafe-perm --save appoptics-apm

If you need to troubleshoot installation issues, you can force re-compilation of the bindings add-on on your system. After the agent install navigate to the bindings package directory under node modules and run the rebuild command:

cd node_modules/@appoptics/apm-bindings
npm run rebuild --verbose

Enabling the Agent

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

Service key

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

export APPOPTICS_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.

Loading the agent

To load the agent into your application, require appoptics-apm in your entry point file before any other require() calls, below is an example with a simple express application:

// must be first require
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 agent README file.

Removing the agent

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

npm uninstall --save appoptics-apm


To attach the AppOptics add-on to your Heroku application, refer the SolarWinds AppOptics add-ons instructions (©, available at, obtained on October 26, 2020). Then follow the Node.js agent steps to install and enable the agent.

Azure App Service

Deploying applications with the AppOptics APM agent 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.

When the APM Integrated Experience is enabled, AppOptics shares a common navigation and enhanced feature set with the other integrated experiences' products. How you navigate the product and access its features may vary from these instructions. For more information, go to the APM Integrated Experience documentation.

Disclaimer: Please note, any content posted herein is provided as a suggestion or recommendation to you for your internal use. This is not part of the SolarWinds software or documentation that you purchased from SolarWinds, and the information set forth herein may come from third parties. Your organization should internally review and assess to what extent, if any, such custom scripts or recommendations will be incorporated into your environment. You elect to use third party content at your own risk, and you will be solely responsible for the incorporation of the same, if any.

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.