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:

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.

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 Standalone 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 Standalone 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 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.

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 (gear) icon in the upper right corner of the AppDynamics UI, then click License.

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; 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.

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”) should occur as early as possible in the code.

Test the Configuration

To verity 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 (e.g., 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 master and worker processes. This scenario does not require a manual launch of the proxy.