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

We have found that there are some application requirements where it doesn't want to depend on node gyp (which needs Python).

We utilize Node gyp to gathers information like Event loop stats and GC stats that is not available at the Javascript layer. We have moved it to different module See Native Metric module for details. This module is optional with Probe agent.

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.

With optional native metric (dependent on node gyp)

$ npm install --global  ca-apm-probe

Without optional native metric (dependent on node gyp)

$ npm install --global  ca-apm-probe --no-optional

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.

With optional native metric (dependent on node gyp)

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

Without optional native metric (dependent on node gyp)

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

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

my-app$ node ./node_modules/ca-apm-probe/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.

With optional native metric (dependent on node gyp)

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

Without optional native metric (dependent on node gyp)

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

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>

Support for HTTP/HTTPS along with ARF

Probe agent default connects to Collector agent via ARF protocol but we can move it HTTP.

We have exposed few properties in config file to keep switching protocol configurable.

ConfigProperties	Environment Variables	Description
protocol	PROTOCOL	Possible value are arf and http. Default: arf
security.eanabled	SECURITY_ENABLED	If true and Protocol is http then HTTPS else HTTP protocol. Default: false
security.certPath	CERTPATH	If Protocol is http and want https connection, add certificate path for public key

(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/ca-apm-probe/bin/config-json-update <local config json path>

(Optional) ReactJs monitoring using Browser agent

To enable ReactJs monitoring, enable the react,autoinjectionEnabled properties in config.json The React application static index.html location has to be updated in htmlpath property in config.json The probe's script ca-apm-run.js should be run along with ReactJs application start script Example: "scripts": { "start": "node .\node_modules\ca-apm-probe\bin\ca-apm-run.js && react-scripts start" } The React pages performance is tracked using browser agent metrics

Version History

• 2.2.7
  • Published on: 10/30/2024
  • Added support for ReactJs monitoring
• 2.2.6
  • Published on: 12/07/2022
  • Removed the autoinjection dependency for corId in Browser agent
• 2.2.3
  • Published on: 06/17/2022
  • Support for Browser Agent with GraphQL
  • Standardize configuration property naming conventions
• 2.2.2
  • Published on: 03/22/2022
  • Added support for redis client(redis version: 2.8.x, 3.x)
  • Added Correlation support for Async calls
• 2.1.0
  • Published on: 01/27/2022
  • Added support for OracleDB.
  • Added support for Browser agent in HTTP/HTTPS modules.
• 2.0.4
  • Published on: 12/07/2021
  • ARF reconnection improvements on connection reset.
• 2.0.0
  • Published on: 08/03/2021
  • Added support for HTTP/HTTPS protocol. Default continues to be ARF.
• 1.11.00
  • Published on: 10/30/2020
  • Modularised Native metric module and made it optional
  • Upgraded all the dependencies to recent versions.
  • Added mssql support
  • Support Node 12.x
  • vulnerability fix
  • Some bug fixes
  • 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

Beta Version History

• 2.2.4-beta.6
  • Published on: 12/06/2022
  • Vulnerability fixes
  • Removed the autoinjection dependency for corId in Browser agent
• 2.2.4-beta.5
  • Published on: 10/17/2022
  • disabled apollo plugin by default. Enable only for apollo version > 2.14
• 2.2.4-beta.4
  • Published on: 10/15/2022
  • Fix for object properties runtime call.
• 2.2.4-beta.2
  • Published on: 09/30/2022
  • Added apollo plugin.
• 2.2.4-beta.1
  • Published on: 08/16/2022
  • Fixed graphql cookie issue.
• 2.2.3-beta.2
  • Published on: 06/01/2022
  • support ESM.
• 2.2.2-beta.1
  • Published on: 03/23/2022
  • support for latest GraphQl with upgraded Apollo Server Express(>= 3.6.3).
• 2.2.1-beta.7
  • Fixes for Browser Agent and GraphQL Async Transactions