This page applies to an earlier version of the AppDynamics App IQ Platform.
For documentation on the latest version, see the 4.4 Documentation.

Skip to end of metadata
Go to start of metadata

This topic describes how to install the Node.js Agent using npm.


AppDynamics Controller

To use the AppDynamics Node.js Agent, you need an AppDynamics account on a running v4.0+ controller.

You can use the AppDynamics SaaS controller. If you do not already have an account on the SaaS controller you can sign up for a subscription here

Or you can use an on-premise controller that is installed at your site. You can download the Controller from the AppDynamics Download Center, and then follow these instructions on how to install it.

You need to know the controller host and port to complete the agent installation. Check your welcome email from AppDynamics for the host and port if you signed up for a SaaS account.


You need write access to the Node.js project.

Installing the Node.js Agent

To install the latest version you can run 'npm install appdynamics' for each application you want to monitor, but we recommend matching the agent version to your AppDynamics Controller version:

npm install appdynamics@<version>

For example, if your AppDynamics controller version is 4.0.0, we recommend installing the 4.0.0 Node.js Agent:

npm install appdynamics@4.0.0

Then paste the following require statement in your application. Replace the variables with the values for your setup:

  controllerHostName: '<controller host name>',
  controllerPort: <controller port number>, 
  controllerSslEnabled: false,  // Set to true if controllerPort is SSL
  accountName: 'AppDynamics_account_name', // Required for SaaS accounts
  accountAccessKey: 'AppDynamics_account_key', // Required for SaaS accounts
  applicationName: 'your_app_name',
  tierName: 'choose_a_tier_name', 
  nodeName: 'choose_a_node_name', 

AppDynamics recommends that you insert the AppDynamics require statement as the very first line of your application source code, before any other require statement. Or, if your first line of code is a require statement of another script that contains the require(“appdynamics”) call before any other require()s, that works too.

If your deployment makes it difficult to follow this recommendation, you can insert the statement elsewhere. Keep in mind that the require(“appdynamics”) should occur as early as possible and must occur before require() is called for any core or third party module that AppDynamics needs to hook into or instrument. 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; i.e. 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.

Testing the Installation

  1. Stop and restart your application.

  2. Run some traffic through the application.

  3. Wait a few minutes.

  4. Log into your controller.

  5. Select the newly instrumented application.

  6. You should see metrics reported in the flow maps.

Advanced Instructions

Node.js Agent Settings

This is the complete list of settings in the require statement that you insert into your application code. Not all these settings are required.

  • controllerHostName: the ip address or host name of your controller. SaaS customers receive this url in their welcome email from AppDynamics. On-premise customers set them when they install the controller.
  • controllerPort: 8080
  • controllerSslEnabled: set to true if connecting to the controller via SSL. Otherwise remove this line.
  • accountName: your username on the SaaS controller or multi-tenant on-premise controller. SaaS customers receive this their welcome email from AppDynamics. If you have a single-tenant controller, remove this line.
  • accountAccessKey: your account access key on the SaaS controller or multi-tenant on-premise controller. SaaS customers receive this their welcome email from AppDynamics. If you have a single-tenant controller, remove this line.
  • applicationName: name that represents the entire application in the AppDynamics console
  • tierName: name that represents your Node.js app or service in the flow maps
  • nodeName: name of the Node.js process to be monitored by this agent. See Node Names.
  • noNodeNameSuffix: Optional: Set to true if you do not want the agent to add a suffix  (-0, -1, -2, etc.) to the node name. See Node Names.
  • proxyHost, proxyPort: Set these options to route data to the controller through a proxy server. The proxyHost is the host name or IP address of the proxy server. The proxyPort is the proxy server's HTTP or HTTPS port, whichever you are using. If you set the host you must set the port as well.
    New in 4.0.3
    proxyUser, proxyPasswordFile
    Configure the prosy user name and password file if the proxy server requires credentials.
  • btEntryPointDelayDisabled: true|false - Optional: defaults to false. Setting to true can accelerate the startup of business transactions, but it can adversely affect drilldown in distributed transactions.

  • maxProcessSnapshotsPerPeriod: integer - Optional: defaults to 2. Number of automatic process snapshots allowed in processSnapshotCountResetPeriodSeconds seconds (see below).

  • processSnapshotCountResetPeriodSeconds: Optional: defaults to 60. Frequency, in seconds, at which the automatic process snapshot count is reset to 0.

  • autoSnapshotDurationSeconds: Optional: defaults to 10. Length, in seconds, of automatically-triggered process snapshots.
  • proxyAutolaunchDisabled: true|false - Optional: default to false. Set to true if you need to manually launch the proxy for this agent. See Run the Proxy Daemon Manually for Node.js Agents. 
  • proxyCtrlDir: directory path for the directory containing the domain control socket, which the agent uses to start an AppDynamics node. Optional: set by the agent. Set manually if you are setting up a multi-tenant proxy. See Set Up A Multi-Tenant Proxy for Node.js Agents.
  • rootTmpDir: directory path for the root of the directory that stores the agent's files. Optional: defaults to /tmp/appd.
  • tmpDir: directory path for the sub directory of the root directory for the monitored node. Optional: defaults to a hash of the controller info for the instrumented node.
  • debug: true|false - Optional: defaults to false. Turn this option on for logging and troubleshooting.

Node Names

Individual Nodes

By default, the agent uses the value configured for nodeName as a prefix and adds a dash and a number to it to form the node name. For example, if you instrument a single node with the following setting:


the node is named "MyNode-0". This convention is used to accommodate node naming in an environment where the number after the dash represents an increasing number for each worker process running on the machine.

If you are not running multiple worker processes, and you want the name to be just "MyNode" with no dash or number, set noNodeNameSuffix to true.

For example, the following settings name the node "MyNode":


Clustered Nodes on a Single Machine


Clustered Nodes on Multiple Machines


creates nodes named "Server1-0", "Server1-1", "Server1-2" .  .  .


Older Node.js Versions

If your Node.js version is 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"

Instrumenting a Cluster of Node.js processes

If you are launching a cluster of Node.js processes to implement your app, add the appdynamics require statement to the master process code and to the code of each of the worker processes.

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

npm ERR! System Linux 2.6.18-348.16.1.el5
npm ERR! command "<your command>"
npm ERR! cwd <path>
npm ERR! node -v v0.10.32
npm ERR! npm -v 1.4.28
npm ERR! code ENOTSUP
npm ERR!
npm ERR! Additional logging details can be found in:
npm ERR!     <path>/npm-debug.log
npm ERR! not ok code 0

Check the AppDynamics release notes to find out the latest Node.js version supported by the agent.

If you need an agent for an unsupported version, contact AppDynamics Support about getting an agent for 0.8.X and 0.10.X versions of Node.js that is compatible with your environment.


There is an agent log and a proxy log for each application.

Node.js Agent Log

If the agent is running in debug mode, the agent component logs to stdout/stderr. This log contains the transactions that the agent processes and sends to the proxy. This log is available in the same location to which stdout/stderr streams are directed from the monitored application.

If debug mode is not enabled, no agent log is generated.

You may set debug mode in the require statement that instruments your Node.js application. See Node.js Agent Settings.

Proxy Log

The proxy logs the transactions that it accepts from the agent and sends to the Controller. The proxy generates logs whether or not the agent is running in debug mode.

When the agent component launches the proxy, it displays in the agent log the directory path to which the proxy is logging. By default the proxy log is in /tmp/appd/logs.

Installing 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 machine agent's controller-info.xml file, the Node.js Agent will fail to register.

To avoid this problem:

  • Install the Node.js Agent before you install the Machine Agent.
  • Do not specify the tier and node in the machine agent controller-info.xml, where it is optional. The Machine Agent will pick up the tier and node from the app agent configuration.
  • No labels