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.
To install the Node.js Agent on Windows:
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.2.0, we recommend installing the 4.2.0 Node.js Agent:
To install the latest agent use:
The domain packages.appdynamics.com must be unblocked on your corporate firewall, otherwise the fetch will fail with error code 403. Another workaround is to run the npm install command on a machine with access to packages.appdynamics.com (must be using same OS & Node version as the target machine) and unpackaging the module on the machine where it will be installed.
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 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.
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.
This is the complete list of settings in the require statement that you insert into your application code. Not all these settings are required.
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.
debug: true|false - Optional: defaults to false. Turn this option on for logging and troubleshooting.
If you are configuring the Node.js Agent to send default transaction data to the Analytics Agent, add a setting for the analytics host and port using the following format:
The Analytics Agent may be reporting on the same or different host and port than the Node.js agent. In either case it must be configured here if you are using this feature.
For more information see Configuring Transaction Analytics.
On Windows, the Node.js Agent requires three additional ports. See Special Procedures for Node.js Agent on Windows for more information.
If you have not provided the required settings in the require statement, the agent uses the values of the following environment variables if those variables are set. If both are set, the require statement value takes precedence over the environment variable.
|Environment Variable||Maps to|
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":
creates nodes named "Server1-0", "Server1-1", "Server1-2" . . .
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:
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.
If your application uses an external process manager, such as PM2, you need to launch the proxy component manually. See Set Up A Multi-Tenant Proxy for Node.js Agents for information on how to arrange that.
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:
See Node.js Versions in Node.js Supported Environments to learn how to determine the latest Node.js version supported by the Agent.
There is an agent log and a proxy log for each application.
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.
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: