Install the Node.js Agent

On this page:

Related pages:

The Agent Download Wizard in the Controller provides the easiest way to get started quickly with the AppDynamics Node.js Agent. The wizard constructs a pre-configured require statement for the agent based on your input.

This page provides additional information and options for installing the Node.js Agent.

Prepare to Install the Node.js Agent

You must add a require statement to the source code of your Node.js application to install the Node.js agent. Therefore, in addition to a running AppDynamics Controller, you need to have write access to the application source code and the ability to restart the Node.js application to install the agent.

The Getting Started wizard in the AppDynamics controller can generate the require statement for you. It populates the statement with the connection settings for the controller and the values you provide to the wizard for modeling the Node.js application in AppDynamics.

For Installations on Windows:

Verify support for your version of Windows.
Install the Visual C++ Redistributable for Visual Studio 2015.

About Node.js Agent Node Identity

You configure the identify of a node.js application instance using the node name setting. By default, the agent uses the value configured for nodeName as a prefix and adds a dash and number as a suffix. For example, given the following setting:

nodeName=MyNode

The first node to start with this configuration would be named MyNode-0. Auto-numbered suffixes on node names are most useful for machines with more than one worker process.

If you are not running multiple worker processes, you can prevent auto-numbering in node names by setting noNodeNameSuffix to true. In the following example, the node would be named MyNode.

nodeName=MyNode
noNodeNameSuffix=true

If you are instrumenting worker processes on different machines, keep in mind that each application and node name combination must be unique. Therefore, be sure to specify different node name prefixes for each server, for example, by configuring nodeName=Server1 for the first server and nodeName=Server2 for the second server.

If you are instrumenting a Node.js application that uses the PM2 process manager, set the node suffix name to process.env.pm_id.

Running the Machine Agent on a Node.js Node

If you install the Machine Agent on the machine hosting the instrumented Node.js node and you specify the tier and node name in the controller-info.xml file of the machine agent, the Node.js Agent will fail to register.

To avoid this problem:

Install the Node.js Agent before you install the Machine Agent.
If you install the machine agent on the machine hosting the instrumented Node.js node, do not specify the application, tier or node name in the machine agent's controller-info.xml file. If you do, the Node.js Agent may fail to register.

Installing the Node.js Agent

To install the agent, run the npm installation command in each directory you want to monitor and then add a require command to add the agent module to your application.

If you are using Node.js 0.8.1 through 0.8.18, see Set User Agent for Node.js 0.8.1 through 0.8.18.

Installing via npm

Refer to Agent and Controller Compatibility to determine which versions of the AppDynamics Node.js agent are compatible with your controller.

To install the latest 4.5 agent, run the following command:

npm install appdynamics@next

If you know which specific version of the Node.js agent you want to install, you can specify it:

npm install appdynamics@<x.y.z>

If you are using npm 5, you must disable the lock file by setting package-lock=false in the npm configuration settings.

Installing Node.js with Java Proxy

To install Node.js with Java proxy run the following command at the time of agent install:

npm install appdynamics@<x.y.z> --appd_include_java_proxy=true

BASH

The version of npm that ships with Node.js v6 does not support automatically running the post-install scripts used by 4.5.12 and later versions of the agent. Using a new Node.js version is recommended. If Node.js v6 must be used, npm needs to be updated prior to installing the agent: npm install -g npm

Add the Require Statement

Paste the following require statement as the very first line of your application source code, before any other require statement. Replace the variables with the values for your setup. To find your account name and access key, click the settings () icon in the upper right corner of the AppDynamics UI, and then click License.

require("appdynamics").profile({
  controllerHostName: '<controller host name>',
  controllerPort: <controller port number>, 
  controllerSslEnabled: false,  // Set to true if controllerPort is SSL
  accountName: '<AppDynamics_account_name>',
  accountAccessKey: '<AppDynamics_account_key>', //required
  applicationName: 'your_app_name',
  tierName: 'choose_a_tier_name', 
  nodeName: 'choose_a_node_name' 
 });

For reference information on the settings, along with other settings you can use, see Node.js Settings Reference.

You can place the require statement as the first line in the require statement of another module that appears as the first line of code.

In this case, you would need to modify your point-of-entry source file; this it can be just a single line to the require() the file that you place the call to the agent into; for example, require(“<script-that-initializes-the-agent>”. You could also parameterize the profile() call to name different instances without having to have multiple versions of the agent initialization script.

If it is not possible to place the require statement as the first line of code, you can insert the statement elsewhere, but it must occur before the require() of any core or third party module that needs to be instrumented. In general, the require(“appdynamics”) statement should occur as early as possible in the code.

Test the Configuration

To verify the installation, restart the application and put load on it. The new node should appear in the flow map for the business application you specified in the configuration.

Stopping the Node.js Application

The script or other mechanism used to stop an instrumented Node.js instance should use the SIGTERM signal if possible.

Using SIGKILL (kill -9) will prevent resources for the agent's Java proxy to be properly released.

Running with Other Profiling Tools

The agent is incompatible with other profiling tools, such as running the node process with the --inspect flag.

Instrumenting a Node.js Cluster

If your application uses the cluster module, place the appdynamics.profile require statement in both the primary and worker processes. This scenario does not require a manual launch of the proxy.

If your application uses an external process manager, such as PM2, you need to launch the proxy component manually. See Sharing a Proxy Among Node.js Agents

Set User Agent for Node.js 0.8.1 through 0.8.18

If running a Node.js version between 0.8.1 and 0.8.18, inclusive, you need to set the user-agent npm property before you run the npm install command.

The syntax is:

npm config set user-agent "node/<version> {linux|darwin} {x64|i86}"

For example:

npm config set user-agent “node/v0.8.14 linux x64"

Resolving Installation Issues for Node.js

If you are trying to install the Node.js Agent on a version of Node.js that the agent does not support, the installation will fail and you will see a message similar to the following:

npm ERR! notsup Unsupported
npm ERR! notsup Not compatible with your version of node/npm: appdynamics@3.9.3
npm ERR! notsup Required: {"node":">=0.8.0 <=0.10.31"}
npm ERR! notsup Actual:   {"npm":"1.4.28","node":"0.10.32"}
...

See Node.js Versions in Node.js Supported Environments.