ca-apm-probe

APM Node.js Agent

The APM Node.js Agent monitors Node.js-based web applications.

How to Access the Product Documentation

The CA Application Performance Management product documentation is now available on a wiki platform. We expect this will not only allow easier access to specific information, but also improve our ability to respond with improvements and enhancements.

You can access the documentation from https://support.ca.com/ as usual. In place of a bookshelf displaying, the documentation wiki displays.

In the wiki, you can access the Node.js Agent documentation by selecting Implementing Agents, Node.js Agent.

License

NOTICE: This product is owned and/or licensed by CA Technologies (“CA”).

An active license agreement for CA Application Performance Management (“License Agreement”) is required for its use. Your use of this product is governed by the terms of the License Agreement. If you do not have an active License Agreement with CA, you may not use this product.

For details, please contact CA.

Usage

The Probe Agent is the component that runs inside the Node.js application process. The Probe Agent instruments the Node.js application at startup. This simple agent only interacts with the Collector Agent and reports events to it. You deploy the Probe Agent using the Node Package Manager (NPM).

The Collector Agent is a standalone Java process that collects data from the Probe Agent and transmits the data to the Enterprise Manager.

Click here for detailed installation information.

Install the Probe Agent Globally (No Code Changes)

You can quick install the Probe Agent globally using default values and without any code modifications. This method makes the Probe Agent available to all your Node.js applications.

$ npm install --global  ca-apm-probe

Then, run your app with it as you would with node:

$ cd my-app
my-app$ ca-apm-run <startup_script>

Install the Probe Agent Per Application (No Code Changes)

You can install the Probe Agent locally for each application. This method lets you selectively instrument and monitor each application.

$ cd to/your/app/root
my-app$ npm install --save ca-apm-probe

The Node.js Agent runs dynamically whenever you start your Node.js application. Start the Node.js application:

my-app$ ./node_modules/bin/ca-apm-run <startup-script>

Install and Manually Configure the Probe Agent as an Application Dependency (Code Change)

You can install and manually configure the Probe Agent. You can install and run the Probe Agent locally as an application dependency. Optionally, you can manually configure your Node.js application for monitoring. Use the npm command to install the Probe Agent and add it as a dependency of your application. This setup avoids any modification of the system and keeps all dependencies local to the application.

$ cd to/your/app/root`
$ npm install --save ca-apm-probe

Add the following first line to your application main entry point script (for example, server or server.js). Optionally, you can specify arguments. For example, if your Node.js Probe Collector Agent is running on a different host or port, you can specify corresponding arguments. Save and close the file.

var probe = require('ca-apm-probe').start(<collector-agent-host>, <collector-agent-port>, <probe-name>);

Where:

<collector-agent-host> is the the host address of the Collector Agent, usually this address is localhost.

<collector-agent-port> is the port of the Collector Agent.

<probe-name> is the name of the probe that the metrics will be reported under.

Important! Place the ca-apm-probe require statement as the first require statement in the code (above all the other require statements), for example:

var probe = require('ca-apm-probe').start();
……
var express = require('express');
var mongoose = require('mongoose');

Run your application as follows:

$ node <startup_script>

(Optional) Configure the APM Probe Agent

You can configure the properties for a Probe Agent by editing the config.json file. Follow these steps:

1. Go to the <INSTALL_DIR>/ca-apm-nodejs-probe directory.
2. Open the config.json file in a text editor.
3. Specify the values for the properties you want to configure:
   • probeName–Specifies the name of the Probe Agent as you want it to appear in the Enterprise Manager and Workstation/Webview/Team Center.
   • probeNameEnvKey–Specifies a probe name value for your environment variable.
   • port–Specifies the port number for the Collector Agent. The default value is 5005.
   • logFile–Specifies the log file location. The default value is ./logs/Probe-.log.
   • logLevel–Specifies the log level: debug|error|info|warn|disabled. The disabled value disables logging completely. The default value is info.
4. Save and close the file.
5. Restart the managed application.

Monitor Metrics

Click here to access wiki documentation for details.

Version History

• 1.10.13
  • Published on: 02/17/2016
  • Bug fixes and minor enhancements:
    • Fix line ending issue with Agent runner
• 1.10.12
  • Published on: 02/16/2016
  • Bug fixes and minor enhancements:
    • Report backend performance metrics even if the transaction context is broken
    • Flexible probe naming in cluster scenarios
    • Detect and handle multiple HTTP listener scenarios
• 1.10.11
  • Published on: 12/11/2015
  • Bug fixes and minor enhancements:
    • Node.js probe installation even if the native probe rebuild fails
• 1.10.10
  • Published on: 11/10/15
  • Initial release