Instrument Node.js Applications
AppDynamics Pro Documentation
Version 4.0.x
Page 1
Instrument Node.js Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Install the Node.js Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Uninstall the Node.js Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Upgrade the Node.js Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Run the Proxy Daemon Manually for Node.js Agents . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Up A Multi-Tenant Proxy for Node.js Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Node.js Supported Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
AppDynamics for Node.js Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3
7
13
13
13
14
15
17
Page 2
Instrument Node.js Applications
On this page:
Before You Begin
Instrument Your Node.js Application
Related pages:
AppDynamics Essentials
Install the Node.js Agent
Upgrade the Node.js Agent
Uninstall the Node.js Agent
Node.js Supported Environments
AppDynamics for Node.js Architecture
Watch the video:
Quick Install: Node.js Agent
Use the instructions on this page to install the Node.js Agent using the Agent Download Wizard in
the Controller. This installer configures your agents with the values that you supply in the wizard.
This is the simplest way to install the agent.
If you downloaded the agent from npm, use the instructions in Install the Node.js Agent to
instrument your application manually. This page includes a complete list of all the Node.js Agent
settings that can be used in the AppDynamics require statement.
Before You Begin
1. Confirm you have access to a controller, the web application where you monitor your
application performance:
If you use a SaaS controller, AppDynamics sent you the controller host in your
Welcome Email.
If you use the on-premise controller, you supplied the host and port at install time.
2. Verify you have root access to run the install.
3. Verify support for your environment at Node.js Supported Environments.
Instrument Your Node.js Application
There are four steps to instrument your Node.js application and begin monitoring:
1. Setup: Use the Agent Download Wizard to set up the agent.
2. Install and Configure: Run the install script and configure the connection to the controller.
3. Apply Load: Restart your application and apply load to activate instrumentation.
4. View Your Application: Log on to the Controller to monitor application performance.
Copyright © AppDynamics 2012-2015
Page 3
Set up the Node.js Agent
The Agent Download Wizard walks you through configuration steps and helps you download the
agent.
Show me the Download Agent Wizard steps...
1. Log on to the Controller and
click the Agent Download
Wizard tab.
The download wizard configures the
agent with information to connect to the
Controller.
2. Click Node.js, then click Ne
xt.
3. The Controller Location URL
window displays the
connection info for the
Controller. Click Next.
Click SSL to enable SSL
encryption between the agent
and the Controller. Enter the
SSL port. For AppDynamics
SaaS, the SSL port is 443.
Copyright © AppDynamics 2012-2015
Page 4
4. Enter an application name
or, click an existing application
name if one exists. Then click
Next.
For new users, it is OK to use
the default "MyApp". You can
change it later when know
more about how you want to
organize your applications in
AppDynamics.
5. Enter a tier name. Then click
Next.
For new users, it is OK to use
the default "MyTier". You can
change it later when know
more about how you want to
organize your applications in
AppDynamics.
Copyright © AppDynamics 2012-2015
Page 5
Install and Configure
1. From the root directory of
your Node.js application run this
command: npm install
appdynamics
2. Insert the require statement
generated by the wizard in the
application source code at the
first line of the main module
(such as the server.js file),
before any other require
statements. You can copy the
code in the wizard and paste it
directly into your application.
Each require statement is
especially generated for your
app based on the values you
configured in the previous setup
steps.
Now you're ready to restart your application and put some load on it.
Apply load to your application
1. Restart your application
2. Apply load to your application.
The agent instruments the application code and reports metrics back to the Controller.
You're ready to begin monitoring.
View your application
Log on to the Controller to see
your application in action.
From here, you can install more
Copyright © AppDynamics 2012-2015
Page 6
agents or you can begin
monitoring your application. The
links below will help you get
started:
Install the Node.js Agent
On this page:
Requirements
Installing the Node.js Agent
Testing the Installation
Advanced Instructions
Resolving Installation Issues for Node.js
Logs
Installing the Machine Agent on a Node.js Node
Related pages:
Upgrade the Node.js Agent
Uninstall the Node.js Agent
This topic describes how to install the Node.js Agent using npm.
Requirements
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 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.
Copyright © AppDynamics 2012-2015
Page 7
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 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:
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',
});
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.
Copyright © AppDynamics 2012-2015
Page 8
Testing the Installation
1.
2.
3.
4.
5.
6.
Stop and restart your application.
Run some traffic through the application.
Wait a few minutes.
Log into your controller.
Select the newly instrumented application.
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 i
s 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
Copyright © AppDynamics 2012-2015
Page 9
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:
nodeName=MyNode
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":
nodeName=MyNode
noNodeNameSuffix=true
Clustered Nodes on a Single Machine
If the agent detects that you are instrumenting nodes in a cluster on a single machine (and noNod
eNameSuffix=false, which is the default) it numbers the first node in the cluster using the suffix
"-0" and then auto-numbers the suffixes for the remaining node names. For example, with this
setting:
Copyright © AppDynamics 2012-2015
Page 10
nodeName=MyNode
the clustered nodes are named "MyNode-0", "MyNode-1", "MyNode-2", . . . for multiple worker
processes on the same machine.
Clustered Nodes on Multiple Machines
The agent begins numbering the node name suffixes at -0 on each new machine.
If you are instrumenting clusters of worker processes on different machines, specify different node
Name prefixes for each server. For example, for the cluster on the first server, the following
setting:
nodeName=Server1
creates nodes named "Server1-0", "Server1-1", "Server1-2" . . .
For the cluster on the second server, the following setting:
nodeName=Server2
creates nodes named "Server2-0", "Server2-1", "Server2-2" . . .
And so on for the remaining servers.
Keep in mind that each applicationName/nodeName combination must be unique.
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
Copyright © AppDynamics 2012-2015
Page 11
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
npm
npm
npm
npm
npm
npm
npm
npm
npm
ERR!
ERR!
ERR!
ERR!
ERR!
ERR!
ERR!
ERR!
ERR!
ERR!
System Linux 2.6.18-348.16.1.el5
command "<your command>"
cwd <path>
node -v v0.10.32
npm -v 1.4.28
code ENOTSUP
Additional logging details can be found in:
<path>/npm-debug.log
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. By default the proxy log is in /tmp/appd/logs.
Copyright © AppDynamics 2012-2015
Page 12
Installing 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.
Do not specify the tier and node in the machine agent controller-info.xml, where it is
optional. The Standalone Machine Agent will pick up the tier and node from the app agent
configuration.
Uninstall the Node.js Agent
To uninstall the Node.js Agent:
1. From the application root directory of the application from which you want to uninstall the
agent enter:
npm uninstall appdynamics
2. Remove the "require("appdynamics")" statement from your Node.js applications.
Upgrade the Node.js Agent
If you are upgrading both the Controller and agents, first upgrade the Controller and then upgrade
the agents.
Also, if you are upgrading multiple agents in your monitored environment, upgrade the agents for
the tiers on which business transactions originate last. For more information about this
requirement, along with Controller and agent compatibility information, see Agent - Controller
Compatibility Matrix.
To upgrade the app agent:
1. Stop the Node.js application.
2. From the root directory of the application for which you want to upgrade the agent, uninstall
the old version of the agent by entering:
npm uninstall appdynamics
3. From the same directory install the new version by entering:
npm install appdynamics@<version>
The version is the three-digit version number of the new version that you are installing; for
example, 3.9.1.
4. Restart the Node.js application.
Copyright © AppDynamics 2012-2015
Page 13
Run the Proxy Daemon Manually for Node.js Agents
By default, when the Node.js Agent starts up, it automatically executes the runproxy shell script.
This script runs the Java proxy daemon that handles communication between the Node.js Agents
and the controller. See AppDynamics for Node.js Architecture for information about how the Java
proxy daemon fits into the Node.js Agent architecture.
Automatic startup of the proxy works for the great majority of situations. However, you can
suppress the automatic startup of this script and run it manually. You would do this if you are
running a cluster of Node.js nodes on the same machine and you want to reduce overhead by
having them report to a single proxy. In this case, you need to configure the agents for a single
proxys and for manual proxy launch. Then you need to launch the proxy manually. See:
Execute the runProxy Script Manually
Set Up A Multi-Tenant Proxy for Node.js Agents
Set Up A Multi-Tenant Proxy for Node.js Agents
On this page:
Multi-tenant Setup
Limits on Agents Sharing a Proxy
Related pages:
Execute the runProxy Script Manually
Set User Preferences
By default, if you are running multiple agents, each agent automatically launches its own Java
proxy to communicate with the controller.
In this single-tenant scenario, each agent has its own proxy control directory. In the require
statement for each agent, the proxy control directory is set to a unique path (a unique
app/tier/node combination). The agent creates these directories automatically.
This results in a configuration in which each agent has its own proxy. The Node.js Agents will
auto-launch their proxies when they start up.
If you want to run multiple Node.js Agents on the same machine, you can reduce your overhead
by setting up the agents to report to a single multi-tenant Java proxy. In this case, you would need
to start that proxy manually and create the mutli-tenant proxy directory manually. This
configuration is appropriate for Node.js processes running in cluster mode.
Multi-tenant Setup
To set up a multi-tenant proxy, you need to configure the proxy control directory. This directory
contains the domain control socket, which the agent uses to start an AppDynamics node. This
Copyright © AppDynamics 2012-2015
Page 14
directory is where the agent gets the configuration for the node. The permissions on this directory
must be readable and executable by the application user that the application and writable by the
proxy user.
To configure agents for a multi-tenant proxy
1. Configure each agent for manual launch of the proxy. To do this, in the require statement of
each agent, set the proxyAutoLaunchDisabled setting to true.
2. Manually create a single proxy control directory for use by all the agents that will share the
proxy.
3. In the AppDynamics require statement for all the agents reporting to the proxy,
set proxyCtrlDir to the directory that you created in step 2.
4. Verify that each agent reporting to the multi-tenant proxy is configured with a unique node
name.
5. Manually launch the multi-tenant proxy before you start the agents, passing the agent
control directory set in step 3 as the proxyCommunicationDir argument to the runproxy
script. See Run the Node.js Proxy Daemon Manually . AppDynamics recommends that you
launch the proxy on system startup.
Limits on Agents Sharing a Proxy
The proxy is set up to handle a maximum of 10 agents reporting to a single proxy. The proxy.out
file, visible if you are running in debug mode, indicates if the proxy is running out of heap. You may
need to adjust the maxHeapSize and maxPermSize settings in the runproxy script if you have
more than ten agents reporting to a single proxy. Contact AppDynamics Support if you need to
change these settings.
Node.js Supported Environments
On this page:
Node.js Versions
Operating Systems
Transaction Naming
HTTP Exit Points
Database Exit Points
Cache Exit Points
Related pages:
Configure Transaction Detection for Node.js
Supported Platform Matrix for the Node.js Agent
Node.js Versions
Supported Node.js Versions
Copyright © AppDynamics 2012-2015
Page 15
0.8
0.10; 0.10.38 and earlier
Operating Systems
Supported Operating System
Linux 32-bit
Linux 64-bit
Mac OSX v10.9.2
Transaction Naming
Entry Type
Default Transaction Naming
Node.js Web
URI
HTTP Exit Points
Supported HTTP Exit Points
Node.js HTTP client library
See http://nodejs.org/api/http.html for information about the Node.js HTTP client library.
Database Exit Points
Supported Database Exit Points
MongoDB
MySQL
PGSQL
Riak
Riak backends are automatically detected, but they are displayed as HTTP backends in the
flowmaps.
Cache Exit Points
Supported Cache Exit Points
Memcached
Redis
Copyright © AppDynamics 2012-2015
Page 16
AppDynamics for Node.js Architecture
The AppDynamics Node.js Agent instruments your application running one or more Node.js
processes. Instrumentation enables the agent to discover, map and track metrics for business
transactions, application services, and backends in your Node.js application. Typically there is a
one-to-one correspondence between a process and a Node.js application but sometimes an
application consists of multiple processes.
This agent communicates with a Java proxy dameon that handles the communication between
the Node.js Agent and the AppDynamics Controller. The proxy reports the performance metrics to
the Controller, where the data is stored, baselined, and analyzed. You can access this
performance data interactively using the Browser UI or programmatically using the AppDynamics
REST API.
The proxy component is automatically started when you start the Node.js Agent.
Copyright © AppDynamics 2012-2015
Page 17