APM Node.js Agent

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

How to Access the Product Documentation

The DX Application Performance Management product documentation can be accessed from DX Application Performance Management platform. Goto Help and search for "Node.js Agent". We expect this will not only allow easier access to specific information, but also improve our ability to respond with improvements and enhancements.

License

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

An active license agreement for DX 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 Broadcom, you may not use this product.

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 Infrastructure Agent and reports events to it. You deploy the Probe Agent using the Node Package Manager (NPM).

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$ node 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 ./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 Infrastructure 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(<infrastructure-agent-host>, <infrastructure-agent-port>, <probe-name>);

Where:

<infrastructure-agent-host> is the the host address of the Infrastructure Agent, usually this address is localhost.

<infrastructure-agent-port> is the port of the Infrastructure 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-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 Infrastructure 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.

(Optional) A script is also provided to update config.json file with local config.json

The scripts adds or updates property in config.json based on local config.

Keep the backup of config JSON before you take the latest version of ca-apm-probe.

If ca-apm-probe is installed Globally then run:

$ cd to/your/app/root
my-app$ node config-json-update <local config json path>

If ca-apm-probe is installed Per Application then run:

my-app$ node ./node_modules/bin/config-json-update <local config json path>

Version History

• 1.10.83-beta.2
  • Published on: 06/30/2020
  • Some bug fixes
  • vulnerability fix
  • Added a script to update config.json
• 1.10.83
  • Published on: 05/14/2020
  • Added support for GraphQL
  • Improved NodeJS compatibility to 12.x
  • Some minor bug fixes
• 1.10.81
  • Published on: 05/14/2019
  • Added support for Attribute Decoration
  • Added support for postgresql
  • Added support for koa-route, koa-router middleware
• 1.10.80
  • Published on: 03/19/2019
  • Adds support for node 10.x
  • Bug fixes
    • Sustenance metrics issue for node versions above 10.x
• 1.10.72
  • Published on: 07/19/2018
  • Minor bug fixes for http backend
• 1.10.71
  • Published on: 06/08/2018
  • Enhanced application to infrastructure correlation for containerized Node.js applications
• 1.10.70
  • Published on: 04/19/2018
  • Minor enhancements and Readme update
• 1.10.54
  • Published on: 12/07/2017
  • Added support for node 8 (probe has been tested up to node version 8.9.2)
• 1.10.53
  • Published on: 08/04/2017
  • Added support for custom application naming
• 1.10.52
  • Published on: 06/15/2017
  • Added support for mongodb driver 2.1.x (includes support for mongoose)
  • Added new platform and run time metrics (supported with Collector Agent version 10.5.2)
• 1.10.32
  • Published on: 05/01/2017
  • Minor bug fixes on http backend
• 1.10.31
  • Published on: 12/06/2016
  • Added support for node 4.x and node 6.8.x runtimes
• 1.10.30
  • Published on: 10/21/2016
  • Bug fixes and minor enhancements:
    • App Map correlation bug fix
• 1.10.21
  • Published on: 04/27/2016
  • Minor bug fixes
• 1.10.20
  • Published on: 04/25/2016
  • Added support for node 4.3.x runtime
• 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