PDFs


This page applies to an earlier version of the AppDynamics App IQ Platform.
See the latest version of the documentation.


On this page:

Related pages:

Your Rating:
Results:
PatheticBadOKGoodOutstanding!
69 rates

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

Or you can use an on-premise controller that is installed at your site. You can download the Controller from the AppDynamics Download Center 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.

Permissions

You need write access to the Node.js project.

Windows Installations

To install the Node.js Agent on Windows:

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.2.0, we recommend installing the 4.2.0 Node.js Agent:

npm install appdynamics@4.2.0

To install the latest agent use:

npm install appdynamics@next

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.

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' 
 });

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.

Testing the Installation

  1. Stop and restart your application.

  2. Run some traffic through the application.

  3. Wait a few minutes.

  4. Log into your controller.

  5. Select the newly instrumented application.

  6. 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 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.
    proxyUser, proxyPasswordFile
    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.

Analytics Settings

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:

  • analytics: {
        host: <analyticsHostName>,

        port: <analyticsPort>  }

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.

Windows Settings

On Windows, the Node.js Agent requires three additional ports. See Special Procedures for Node.js Agent on Windows for more information.

  • proxyCommPort: default = 10101
  • proxyRequestPort: default = 10102
  • proxyReportingPort: default = 10103

Environment Variables

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 VariableMaps to
APPDYNAMICS_CONTROLLER_HOST_NAME controllerHostName
APPDYNAMICS_CONTROLLER_PORTcontrollerPort
APPDYNAMICS_CONTROLLER_SSL_ENABLEDcontrollerSslEnabled
APPDYNAMICS_AGENT_ACCOUNT_NAMEaccountName
APPDYNAMICS_AGENT_ACCOUNT_ACCESS_KEYaccountAccessKey
APPDYNAMICS_AGENT_APPLICATION_NAMEapplicationName
APPDYNAMICS_AGENT_TIER_NAMEtierName
APPDYNAMICS_AGENT_NODE_NAMEnodeName

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

nodeName=MyNode

Clustered Nodes on Multiple Machines

nodeName=Server1

creates nodes named "Server1-0", "Server1-1", "Server1-2" .  .  .

nodeName=Server2

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

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:

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 ERR! System Linux 2.6.18-348.16.1.el5
npm ERR! command "<your command>"
npm ERR! cwd <path>
npm ERR! node -v v0.10.32
npm ERR! npm -v 1.4.28
npm ERR! code ENOTSUP
npm ERR!
npm ERR! Additional logging details can be found in:
npm ERR!     <path>/npm-debug.log
npm ERR! not ok code 0

See Node.js Versions in Node.js Supported Environments to learn how to determine the latest Node.js version supported by the Agent.

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

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