Related pages:

This page provides instructions on how to install the Node.js Agent.

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

Before You Begin

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

The Getting Started Wizard in the Controller generates the require statement for you. It populates the statement with the connection settings for the Controller and the values you provide for the wizard to model the Node.js application in AppDynamics.

For installation on Windows, see Supported Environment for your version of Windows and 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
CODE

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
CODE

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.

Use the Node.js Agent with the Machine Agent

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.

Install the Node.js Agent

To install the agent, run the install command in the directory of your application and 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 before running the install command.

Install via npm

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

To install the latest agent, run the following command: 

npm install appdynamics@next
CODE

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>
CODE

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

The version of npm that ships with Node.js v6 does not automatically run post-install scripts used by 4.5.12 and later versions of the agent. AppDynamics recommends using the latest Node.js version.

If Node.js v6 must be used, npm needs to be updated prior to installing the agent:

npm install -g npm
npm install appdynamics
CODE

Add the Require Statement

Paste the following require statement as the very first line of your application source code before any other require statement. Then, replace the variables with the values for your setup. To find your account name and access key, select Settings Settings Icon and then 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' 
 });
CODE

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.

Stop the Node.js Application

By default, closing the Node.js application stops the application.

Run with Other Profiling Tools

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

Instrument a Node.js Cluster

If your application uses the cluster module, place the appdynamics.profile require statement in both the primary and worker processes.

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}"
CODE

For example:

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

Resolve 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"}
...
CODE

See Node.js Supported Environments.