Node Application Metrics

Node Application Metrics monitoring and profiling agent

Node Application Metrics instruments the Node.js runtime for performance monitoring, providing the monitoring data via an API. Additionally the data can be visualized by using the Node Application Metrics Dashboard.

The data can also be visualized in Eclipse using the [IBM Monitoring and Diagnostics Tools - Health Center][1] client. Profiling data is available in Health Center, but is not yet available in the Dashboard. See https://www.ibm.com/developerworks/java/jdk/tools/healthcenter/ for more details.

Node Application Metrics provides the following built-in data collection sources:

Source	Description
Environment	Machine and runtime environment information
CPU	Process and system CPU
Memory	Process and system memory usage
GC	Node/V8 garbage collection statistics
Event Loop	Event loop latency information
Loop	Event loop timing metrics
Function profiling	Node/V8 function profiling (disabled by default)
HTTP	HTTP request calls made of the application
HTTP Outbound	HTTP requests made by the application
socket.io	WebSocket data sent and received by the application
LevelDB	LevelDB queries made by the application
MySQL	MySQL queries made by the application
MongoDB	MongoDB queries made by the application
PostgreSQL	PostgreSQL queries made by the application
MQTT	MQTT messages sent and received by the application
MQLight	MQLight messages sent and received by the application
Memcached	Data that is stored or manipulated in Memcached
OracleDB	OracleDB queries made by the application
Oracle	Oracle queries made by the application
StrongOracle	StrongOracle database queries made by the application
Redis	Redis commands issued by the application
Riak	Riak methods called by the application
Request tracking	A tree of application requests, events and optionally trace (disabled by default)
Function trace	Tracing of application function calls that occur during a request (disabled by default)

Performance overhead

Our testing has shown that the performance overhead in terms of processing is minimal, adding less than 0.5 % to the CPU usage of your application. The additional memory required is around 20 MB to gather information about your system and application.

We gathered this information by monitoring the sample application [Acme Air][3]. We used MongoDB as our datastore and used JMeter to drive load though the program. We have performed this testing with Node.js version 6.10.3

Getting Started

Pre-requisites:

Appmetrics uses node-gyp to compile and build local binary libraries to enhance execution performance. If the following compilation and build logs contain errors, make sure you have the node-gyp pre-requisites installed (https://github.com/nodejs/node-gyp#installation). If you have them and the build still had errors, see if there are any related issues at https://github.com/RuntimeTools/appmetrics/issues). If there aren\'t, feel free to open a new issue to report the bug.

Installation

You can get Node Application Metrics from 3 different places:

• npmjs.org (install by running npm install appmetrics. Native libraries are prebuilt)
• Github (install from source by cloning the git repository. Requires a compiler)
• IBM SDK for Node.js (packaged with the SDK, native libraries are prebuilt)

Configuring Node Application Metrics

Node Application Metrics can be configured in two ways, by using the configuration file described below or via a call to configure(options).

Node Application Metrics comes with a configuration file inside the module installation directory (.../node_modules/appmetrics/appmetrics.properties). This can be used to configure connection options, logging and data source options.

Node Application Metrics will attempt to load appmetrics.properties from one of the following locations (in order):

1. the application directory
2. the current working directory
3. the appmetrics module installation directory

The default configuration has minimal logging enabled, will attempt to send data to a local MQTT server on the default port and has method profiling disabled.

Many of the options provide configuration of the Health Center core agent library and are documented in the Health Center documentation: Health Center configuration properties.

The following options are specific to appmetrics:

• com.ibm.diagnostics.healthcenter.data.profiling=[off|on] Specifies whether method profiling data will be captured. The default value is off. This specifies the value at start-up; it can be enabled and disabled dynamically as the application runs, either by a monitoring client or the API.

Running Node Application Metrics

Preloading appmetrics

In previous versions appmetrics came with an executable, node-hc, which could be used instead of the node command to run your application and load and start appmetrics. This has been removed in version 4.0.0, instead you can use:

$ node --require appmetrics/start app.js

to preload and start appmetrics, or in Node.js from versions 8.0.0 and 6.12.0 onwards, use the NODE_OPTIONS environment variable:

$ export NODE_OPTIONS="--require appmetrics/start"

Modifying your application to use appmetrics

If you locally install this module with npm then you will additionally have access to the monitoring data via the appmetrics API (see API Documentation).

To load appmetrics and get the monitoring API object, add the following to the start-up code for your application:

var appmetrics = require('appmetrics');
var monitoring = appmetrics.monitor();

The call to appmetrics.monitor() starts the data collection agent, making the data available via the API and to the Heath Center client via MQTT.

You should start your application using the node command as usual (not node-hc).

You must call require('appmetrics'); before the require statements for any npm modules you want to monitor. Appmetrics must be initialized first so that it can instrument modules for monitoring as they are loaded. If this is a problem due to the structure of your application you can require the module on the node command line by using -r or --require or by setting NODE_OPTIONS as described above to make sure it is pre-loaded.

Once you have loaded appmetrics you can then use the monitoring object to register callbacks and request information about the application:

monitoring.on('initialized', function (env) {
    env = monitoring.getEnvironment();
    for (var entry in env) {
        console.log(entry + ':' + env[entry]);
    };
});

monitoring.on('cpu', function (cpu) {
    console.log('[' + new Date(cpu.time) + '] CPU: ' + cpu.process);
});

Health Center Eclipse IDE client

Not supported on z/OS

Connecting to the client

Connecting to the Health Center client requires the additional installation of a MQTT broker. The Node Application Metrics agent sends data to the MQTT broker specified in the appmetrics.properties file or set via a call to configure(options). Installation and configuration documentation for the Health Center client is available from the [Health Center documentation in IBM Knowledge Center][2].

Note that both the API and the Health Center client can be used at the same time and will receive the same data. Use of the API requires a local install and application modification (see Modifying your application to use the local installation).

Further information regarding the use of the Health Center client with Node Application Metrics can be found on the [appmetrics wiki][3]: Using Node Application Metrics with the Health Center client.

API Documentation

appmetrics.configure(options)

Sets various properties on the appmetrics monitoring agent. If the agent has already been started, this function does nothing. * options(Object) key value pairs of properties and values to be set on the monitoring agent.

Property name	Property value type	Property description
applicationID	string	Specifies a unique identifier for the mqtt connection
mqtt	string['off'\|'on']	Specifies whether the monitoring agent sends data to the mqtt broker. The default value is 'on'
mqttHost	string	Specifies the host name of the mqtt broker
mqttPort	string['[0-9]*']	Specifies the port number of the mqtt broker
profiling	string['off'\|'on']	Specifies whether method profiling data will be captured. The default value is 'off'

appmetrics.start()

Starts the appmetrics monitoring agent. If the agent is already running this function does nothing.

appmetrics.stop()

Stops the appmetrics monitoring agent. If the agent is not running this function does nothing.

appmetrics.enable(type, config)

Enable data generation of the specified data type. Cannot be called until the agent has been started by calling start() or monitor(). * type (String) the type of event to start generating data for. Values of eventloop, profiling, http, http-outbound, mongo, socketio, mqlight, postgresql, mqtt, mysql, redis, riak, memcached, oracledb, oracle, strong-oracle, requests and trace are currently supported. As trace is added to request data, both requests and trace must be enabled in order to receive trace data. * config (Object) (optional) configuration map to be added for the data type being enabled. (see setConfig) for more information.

The following data types are disabled by default: profiling, requests, trace

appmetrics.disable(type)

Disable data generation of the specified data type. Cannot be called until the agent has been started by calling start() or monitor(). * type (String) the type of event to stop generating data for. Values of eventloop, profiling, http, mongo, socketio, mqlight, postgresql, mqtt, mysql, redis, riak, memcached, oracledb, oracle, strong-oracle, requests and trace are currently supported.

appmetrics.setConfig(type, config)

Set the configuration to be applied to a specific data type. The configuration available is specific to the data type. * type (String) the type of event to apply the configuration to. * config (Object) key value pairs of configurations to be applied to the specified event. The available configuration options are as follows:

Type	Configuration key	Configuration Value
http	filters	(Array) of URL filter Objects consisting of: pattern (String) a regular expression pattern to match HTTP method and URL against, eg. 'GET /favicon.ico$' to (String) a conversion for the URL to allow grouping. A value of '' causes the URL to be ignored.
requests	excludeModules	(Array) of String names of modules to exclude from request tracking.
trace	includeModules	(Array) of String names for modules to include in function tracing. By default only non-module functions are traced when trace is enabled.
advancedProfiling	threshold	(Number) millisecond run time of an event loop cycle that will trigger profiling

appmetrics.emit(type, data)

Allows custom monitoring events to be added into the Node Application Metrics agent. * type (String) the name you wish to use for the data. A subsequent event of that type will be raised, allowing callbacks to be registered for it. * data