This topic describes how to install the Node.js Agent using npm.
To use the AppDynamics Node.js Agent, you need an AppDynamics account on a running v4.1+ 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.
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:
For example, if your AppDynamics controller version is 4.1.0, we recommend installing the 4.1.0 Node.js Agent:
To install the latest agent use:
Then paste the following require statement in your application. 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.
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 therequire(“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
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.
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 controller. Whether the account name is required for a single-tenant on-premise controller depends on the versions of controller and agent. See Account Name and Access Key Requirements for details.
- accountAccessKey: your account access key on the controller
- 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.
Configure the the proxy username 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.
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:
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:
Check the AppDynamics release notes to find out the latest Node.js version supported by the agent.
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 can set debug mode in the require statement that instruments your Node.js application. See Node.js Agent Settings.
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 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.