rtview-nodemon v1.0.3

rtview-nodemon - RTView Node.js Monitoring Agent

The rtview-nodemon package contains the RTView Node.js Monitoring Agent. This can be used in a Node.js application to transmit monitoring data about the performance of a Node.js process to an RTView DataServer. Monitoring data can include CPU and memory utilization, server access and response times, as well as custom monitoring metrics.

RTView is a real-time data management, visualization and analytics engine provided by SL Corporation (www.sl.com). It is used by organizations worldwide as a key component of mission-critical monitoring and control systems built around various middleware, infrastructure, telemetry and IoT data sources.

The RTView DataServer is the data management component that provides in-memory caching and archival to persistent storage. Data stored there may be consumed by displays, dashboards, reports and alerts provided by a visualization and analytics tool such as RTView Cloud. The rtview-nodemon package provides a simple way to send Node.js monitoring data to the RTView DataServer. Other RTView components, such as RTView Cloud or RTView Enterprise can be used to view the data and to correlate the data with metrics collected from other monitoring sources.

The JavaScript API in this package enables users to:

• Initialize and activate monitoring within a Node.js application with a single line of code.
• Configure the address of an RTView DataServer to which metrics will be transmitted.
• Define custom monitoring metrics to be transmitted to the RTView DataServer.

This document assumes that you have access to an RTView DataServer for Infrastructure and an RTView installation for viewing the monitoring data collected. For convenience, at the end of this document, instructions are included for installing and configuring these components if necessary:

• Create an account on RTView Cloud for viewing the monitoring data.
• Download and run an RTView DataServer on your local computer for storing and retrieving monitor metrics.
• Configure RTView Cloud to reference your RTView DataServer and view the monitoring data.

Installation of rtview-nodemon

The rtview-nodemon package is a Node module which can be installed using npm:

npm install rtview-nodemon

Alternatively, the package.json file could be edited to include the lines below, and a simple call to 'npm install' will suffice.

"dependencies": {
    "rtview-nodemon": ""
}

Usage

To monitor a Node.js application in RTView, an instance of the rtview-nodemon package is 'required'. Near the top of your program file, use one of the following methods to make an instance, and to specify the target RTView DataServer to receive the monitoring metrics.

Examples for use in a non-clustered application:

Method 1, if the RTView DataServer host and port are directly accessible:

var rtv = require('rtview-nodemon');
rtv.start({ 'app' : app, 'id' : 'your_app_ID',
    'host':'required_if_not_localhost', 'port':'required_if_not_3275' });
	

Method 2, to send data via the 'rtvpost' servlet that forwards data to the RTView DataServer:

var rtv = require('rtview-nodemon');
rtv.start({ 'app' : app, 'id' : 'your_app_ID',
    'url':'localhost:3270/rtvpost' });        // or 'anyserver/rtvpost' if on port 80
	

The 'app' argument is the instance of the 'express' package that the Node.js application invokes. The rtview-nodemon package currently requires this in order to monitor key server metrics. If your application does not use express, simply create an instance like this:

const app = require('express')();

Example for use in a clustered application, (using host and port method), you need to add the 'cluster' argument:

var rtv = require('rtview-nodemon');

if (cluster.isMaster) {
    rtv.start({'app':app, cluster:cluster, 'id':your_app_ID, 
	'host':'required_if_not_localhost', 'port':'required_if_not_3275' }); 
} else {
    // note - 'app' only required for Master process
    rtv.start({'cluster': cluster, 'id':your_app_ID,
	'host':'required_if_not_localhost', 'port':'required_if_not_3275' });
}

Required argument fields:

'app'  : This is the reference to your express app object (ex: var app = express();
	 In a clustered node app, it is only required for the master node )
	
'id'   : This is the label used by `rtview-nodemon` to identify your node app instance
	 in the RTView Node Monitor displays.

Optional argument fields:

'cluster' : If you are running a clustered Node.js app, this is the reference to the cluster object.
	Ex: var cluster = require('cluster'); Omit if non-clustered.

'host' : The host name or IP address of your RTView Node Monitor installation (default = 'localhost').

'port' : The port number of your RTView Node Monitor installation (default = 3275). 
	
'url' : Instead of host and port, a http URL may be supplied as the target for the monitor metrics.  
	The default URL provided by the RTView Node Monitor Package is 'localhost:3270/rtvpost'.
	This can be used instead of the 'host' and 'port' arguments.

'poll' : Polling interval (in milliseconds). Default is 10000 (10 seconds). Minumum allowed is 4000.

'debug : true'  - setting this will send all monitoring metrics to the console that app was run from.
	These are the same metrics that are sent to the RTView caches for display.

Hostnames:

By default, Nodemon will display a node application's hostname as it is reported by either the OS or the container it is running within. There are two methods provided that will allow for the display of a user-specified hostname:

1) setting an environment variable
2) passing a command line argument.

Usage:
The environment variable is RTVHTTP_HOST
ex: RTVHTTP_HOST=YourHostname

The command line argument is -rtvhttp_host
ex: node server -rtvhttp_host=YourHostname

Note that the command line argument will always take precedence over the environment variable.

Additional API Functions:

trim(); : Provides a means to remove variable data from URLs sent to Nodemon. 
This allows for more accurate grouping and analysis of URL response times.
trim() takes as a parameter an array of URL strings.
ex: rtv.trim(['/url/example1/', '/url/example2/']);

usage:
Where a URL may be "/email/download/emails/2016712323@ed32as.corp.apex.com.am/ABC123",
calling trim(['email/download/emails/']) will send only that base URL to Nodemon,
ignoring all text that follows it.

Create an RTView Cloud account

An RTView Cloud account provides access to the browser displays for viewing the monitoring data collected by the rtview-nodemon package.

• In a browser, go to RTView Cloud.
• Click on Start Free Trial to create your account (skip if you have an account already).
• Login to your RTView Cloud account.

Note that you are automatically placed into your own private organization (e.g. JohnSPrivateOrg).

Download and run the RTView DataServer for Infrastructure Monitoring

Perform the following steps to download and run the RTView DataSeerver for Infrastructure:

• From your RTView Cloud account, click on the ? icon at upper right to go to the Support page.
• Select Downloads and elect to download the RTView DataServer for Infrastructure to your computer.
• Unzip the downloaded RTViewDataServer_?.?.?.?.zip file to a directory of your choice.
• Open a Command Window or Linux Shell in that directory.

To start the RTView DataServer for Infrastructure:

cd RTViewDataServerInfra

start_server          (or ./start_server.sh in Linux)

The RTView DataServer is now ready to receive data at the following http URL:

http(s)://localhost:3270/rtvpost

At any time you can stop the server:

stop_server           (or ./stop_server.sh in Linux)

Configure RTView to View the Node.js Monitoring Data

Once your application is running and transmitting data to the RTView DataServer for Infrastructure, you can use RTView Cloud to view the monitoring information. Do the following:

• In your RTView Cloud account, select the Data tab at the top of the page.
• Select Add RTView Server, and enter a name such as MY-NODEMON-DATA and the URL of the http access point for the DataServer that you are running. If on the same machine as your browser, you can simply enter http://localhost:3270/rtvquery. Modify as needed if you are viewing from a different machine.
• Select the "Gear" icon at upper right and choose Packages.
• In the dialog that comes up, select the Node.js package.

At this point, you are ready to view the monitoring data. Select the View tab, followed by the Components tab on the second row. Here you will be able to select the Application / Web Servers section and see the Node.js Monitoring pages. View the multiple displays that are avaialble, and if all is configured properly, you should see lots of monitoring data.