README
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 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. 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):
- the application directory
- the current working directory
- 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 isoff
. 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.
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: 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.
type
, config
)
appmetrics.enable(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 ofeventloop
,profiling
,http
,http-outbound
,mongo
,socketio
,mqlight
,postgresql
,mqtt
,mysql
,redis
,riak
,memcached
,oracledb
,oracle
,strong-oracle
,requests
andtrace
are currently supported. Astrace
is added to request data, bothrequests
andtrace
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
type
)
appmetrics.disable(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 ofeventloop
,profiling
,http
,mongo
,socketio
,mqlight
,postgresql
,mqtt
,mysql
,redis
,riak
,memcached
,oracledb
,oracle
,strong-oracle
,requests
andtrace
are currently supported.
type
, config
)
appmetrics.setConfig(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:
|