APM Overview - Node.js - AppDynamics Documentation

48 Pages·2014·2.3 MB·English

APM Overview - Node.js
AppDynamics Pro Documentation

Version 3.9.
5
Page 1
APM Overview - Node.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
AppDynamics for Node.js Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Supported Environments and Versions for Node.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Install the Node.js Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Upgrade the Node.js Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Uninstall the Node.js Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Run the Proxy Daemon Manually for Node.js Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Set Up A Multi-Tenant Proxy for Node.js Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Configure AppDynamics for Node.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Configure Transaction Detection for Node.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Import and Export Transaction Detection Configuration for Node.js . . . . . . . . . . . 21
Configure Error Detection for Node.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Monitor Node.js Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Monitor Node.js Business Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Monitor Node.js Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
View Process Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Node.js Process Metrics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Process Snapshots and Business Transaction Snapshots . . . . . . . . . . . . . . . . . . 38
Monitor Node.js Backends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Troubleshoot Errors for Node.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Resolve AppDynamics Issues for Node.js . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
First Time Using the Node.js Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Page 2
APM Overview - Node.js
This information covers using and configuring the Node.js Agent.
For general information about AppDynamics see Application Intelligence Platform and AppDynami
cs Features.
Monitor Node.js
Applications
Troubleshoot Node.js
Application Problems
Supported Environments
and Versions for Node.js
Install the Node.js Agent

Configure AppDynamics
for Node.js
First Time Using the
Node.js Agent
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
Copyright © AppDynamics 2012-2014 Page 3
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.

Supported Environments and Versions for Node.js
Supported Platform Matrix for the Node.js Agent
Node.js Versions
Operating Systems
Transaction Naming
HTTP Exit Points
Database Exit Points
Cache Exit Points
Supported Platform Matrix for the Node.js Agent
Node.js Versions
Supported Node.js Versions
Copyright © AppDynamics 2012-2014 Page 4
0.8
0.10
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
Cache Exit Points
Supported Cache Exit Points
Memcached
Redis
Copyright © AppDynamics 2012-2014 Page 5
Install the Node.js Agent
Requirements
AppDynamics Controller
Permissions
Installing the Node.js Agent
Testing the Installation
Advanced Instructions
Node.js Agent Settings
Older Node.js Versions
Instrumenting a Cluster of Node.js processes
3.9 Controller Temporarily Unavailable
Resolving Installation Issues for Node.js
Logs
Node.js Agent Log
Proxy Log
Installing the Standalone Machine Agent on a Node.js Node
Learn More
Requirements
AppDynamics Controller
To use the AppDynamics Node.js Agent, you need an AppDynamics account on a running v3.9+
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.
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>
Copyright © AppDynamics 2012-2014 Page 6
For example, if your AppDynamics controller version is 3.9.0, we recommend installing the 3.9.0
Node.js Agent:
npm install [email protected]
Then paste the following in your application as the very first line of your application source code,
before any other require statement. 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',
});
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.
controller host name: 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.
controller port: 8080
controllerSslEnabled: set to true if connecting to the controller via SSL. Otherwise remove
this line.
Copyright © AppDynamics 2012-2014 Page 7
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: prefix to the name of the instrumented Node.js process(es) on a single
machine.
There can be multiple nodes. The agent uses this setting as the prefix to the node name and
then auto-numbers the suffixes for the remaining nodes on the same machine to create the
node name that you see in the AppDynamics UI. For example, if you set this value to
MyNode, nodes are named MyNode-0, MyNode-1, MyNode-2 . . . for multiple worker
processes on the same machine.
If you have only one process to monitor, the node is still named MyNode-0 according to this
convention. To suppress the -0 suffix use noNodeNodeNameSuffix.
If you have clusters of worker processes on different machines, the agent begins numbering
the suffixes at -0 on each machine. In this case you could specify different nodeName prefix
es for each server to name the nodes according to the pattern Server1-0, Server1-1,
Server1-2 . . ., then Server2-0, Server2-1, Server2-2 and so on.
Each applicationName/nodeName combination must be unique.
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.
noNodeNameSuffix: Optional: Set to true if you do not want the agent to add a suffix (-0,
-1, -2, etc.) to the node name. In this case multiple worker processes appear in
AppDynamics as a single node.
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.
Copyright © AppDynamics 2012-2014 Page 8
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.
3.9 Controller Temporarily Unavailable
If you cannot obtain a 3.9 controller, it is possible to get started using the agent with a 3.8.6
controller, until you can upgrade. For more information, contact [email protected] for
information on how to do this.
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:
Copyright © AppDynamics 2012-2014 Page 9
npm ERR! notsup Unsupported
npm ERR! notsup Not compatible with your version of node/npm:
[email protected]
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
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.
Copyright © AppDynamics 2012-2014 Page 10