Related pages:

This page provides instructions on how to install the Node.js Agent in the Java proxy mode.

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 and 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 to determine the appropriate version of Windows and install the Visual C++ Redistributable for Visual Studio 2015.

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 in the Java proxy mode, run the following command: 

npm install --appd_include_java_proxy=true appdynamics
CODE

To run the Node.js Agent on Windows with the Java proxy, see Run the Node.js Agent on Windows.

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, 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',
  proxy: true
 });
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

When running the Node.js Agent with the Java proxy, configure the script/mechanism that stops an instrumented Node.js instance to use the SIGTERM signal if possible. SIGKILL (kill -9) prevents the resources for the agent's Java proxy from being released.

When running the Node.js Agent in the multi-tenant mode, you must manually shut down the Java proxy after stopping your Node.js 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. 

Running the Node.js Agent with the Java proxy does not require a manual launch of the proxy. Running the Node.js Agent with the Java proxy and an external process manager (such as PM2) for your application requires a manual launch of the proxy component. 

See Sharing a Proxy Among Node.js Agents.