Requirements

AppDynamics Controller

To use the AppDynamics Node.js Agent, you need an AppDynamics account on a running v3.9+ 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 an on-premise controller from here, 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.

Permissions

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 3.9.0, we recommend installing the 3.9.0 Node.js Agent:

npm install appdynamics@3.9.0

Then paste the following in your application as the very first line of your application source code, before any other require statement. Replace the variables with the values for your setup:

require("appdynamics").profile({
  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', 
 });

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.

• controller host name: 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.
• controller port: 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: prefix to the name of the instrumented Node.js process(es) on a single machine.
  There can be multiple nodes. The agent uses this setting as the prefix to the node name and then auto-numbers the suffixes for the remaining nodes on the same machine to create the node name that you see in the AppDynamics UI. For example, if you set this value to MyNode, nodes are named MyNode-0, MyNode-1, MyNode-2 . . . for multiple worker processes on the same machine.
  If you have only one process to monitor, the node is still named MyNode-0 according to this convention. To suppress the -0 suffix use noNodeNodeNameSuffix.
  If you have clusters of worker processes on different machines, the agent begins numbering the suffixes at -0 on each machine. In this case you could specify different nodeName prefixes for each server to name the nodes according to the pattern Server1-0, Server1-1, Server1-2 .  .  ., then Server2-0, Server2-1, Server2-2 and so on.
  Each applicationName/nodeName combination must be unique.

• 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.
• noNodeNameSuffix: Optional: Set to true if you do not want the agent to add a suffix  (-0, -1, -2, etc.) to the node name. In this case multiple worker processes appear in AppDynamics as a single node.
• 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.

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.

3.9 Controller Temporarily Unavailable

If you cannot obtain a 3.9 controller, it is possible to get started using the agent with a 3.8.6 controller, until you can upgrade. For more information, contact omed@appdynamics.com for information on how to do this.

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.

Logs

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.

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.

Learn More

• Monitor Node.js Processes
• Monitor Node.js Business Transactions
• Upgrade the Node.js Agent
• Uninstall the Node.js Agent