Applications Manager's APM Insight Node.js agent captures incoming web requests like http, https, http2, and other similar ones by default. To gain more granularity, you can use the custom instrumentation APIs to analyze specific transactions or code blocks in your applications.
To use custom instrumentation in your Node.js applications, you must have the APM Insight module installed. Use the below command to load the APM Insight module into your application:
var apminsight = require('apminsight')Following are the list of APIs that are used to analyze various transactions/code blocks in your applications:
By default, incoming web requests are automatically collected by the agent and displayed under the 'Web Transactions' in 'Transactions' tab. However, other client-server communications, like socket connections, are not monitored by the agent. Also, it does not monitor background transactions by default.
With the help of APIs, you can monitor, customize or skip various web or background transactions. Below are the list of APIs that can be used to instrument web/background transactions:
Note: When you instrument web or background transactions, they must be followed by the End transaction API.
Using this API, you can monitor web transactions by instrumenting them as below:
apminsight.startWebTransaction(txnName, handler)
txnName : string value
handler : handler is the function, that will be executed once txn is createdvar apminsight = require('apminsight');
var app = require('express')();
var http = require('http').Server(app);
var io = require('socket.io')(http);
/* this request will be collected automatically*/
app.get('/', function(req, res){
res.sendFile(__dirname + '/index.html');
});
/*need to use custom instrumentation for socket communication*/
io.on('connection', function(socket){
apminsight.startWebTransaction('/message', function(){
doSomething()
........ apminsight.endTransaction();
});
});
http.listen(3000); Using this API, you can monitor background transactions by instrumenting them as below:
apminsight.startBackgroundTransaction(txnName, handler)
txnName : string value
handler : handler is the function, that will be executed once txn is createdvar apminsight = require('apminsight');
function doBackground(){
setInterval( function(){
apminsight.startBackgroundTransaction('routine', function(){
doSomething().........
apminsight.endTransaction();
}
}, 5000);
}Using this API, you can customize the names of your transaction by instrumenting them as below:
apminsight.setTransactionName(customTxnName)
cusTxnName : string valuevar apminsight = require('apminsight');
var app = require('express')();
var http = require('http').Server(app);
/* this request will be collected automatically with txn name /admin*/
app.get('/admin', function(req, res){
/* txn name will be changed to /homepage*/
apminsight.setTransactionName('/homepage');
res.sendFile(__dirname + '/index.html');
});
http.listen(3000);
Using this API, you can skip transactions from monitoring by instrumenting them as below:
apminsight.ignoreCurrentTransaction()var apminsight = require('apminsight');
var app = require('express')();
var http = require('http').Server(app);
var io = require('socket.io')(http);
app.get('/logout', function(req, res){
/* this request will be ignored */
apminsight.ignoreCurrentTransaction();
res.sendFile(__dirname + '/index.html');
});
http.listen(3000);
apminsight.endTransaction()The agent captures default framework components, classes, and methods. However, user-defined classes and methods can be monitored only by instrumenting them with the following API. These details can be viewed under the 'Traces' tab. Also, if any transaction involving a database operation is called in the instrumented class or method, those details will be reflected in the 'Database' tab.
apminsight.startTracker(trackerName, componentName, handler, cb)
trackerName : string value
componentName : string value
handler : handler is the function, that will be executed
cb : optional param, if it is present then it will be treated as asynchrous tracker
Without cb:
var apminsight = require('apminsight');
var app = require('express')();
var http = require('http').Server(app);
app.get('/', function(req, res){
apminsight.startTracker('readFile', 'FS', function(){
res.sendFile(__dirname + '/index.html');
});
});
http.listen(3000);With cb:
var apminsight = require('apminsight');
var app = require('express')();
var http = require('http').Server(app);
app.get('/', function(req, res){
apminsight.startTracker('readFile', 'FS', function(cb){
doSomething()......
cb();
}, function(){
// send response
});
});
http.listen(3000);
All async I/O errors and unhandled errors are captured by the agent in general. This API helps you to track handled errors. For instance, if you have handled errors using the try-catch method, such errors can be notified via this API, and the notified errors are associated with its corresponding transaction. The captured errors can be viewed under 'Errors' as well as the 'Traces' tab.
apminsight.trackError(err)
err : Error objectvar apminsight = require('apminsight');
var app = require('express')();
var http = require('http').Server(app);
/* this request will be collected automatically*/
app.get('/', function(req, res){
try{
fetchAndSendResponse();
}catch(err){
apminsight.trackError(err)
sendErrorResponse();
}
});
http.listen(3000);Using App Parameters, you can monitor important parameters, like the size and frequency of a variable or an operation in your application. To understand how App Parameters work, refer here.
This API collects the sum of custom metrics.
apminsight.incrementCustomMetric(metricName, metricValue)
metricName : string value
metricValue : optional, if it is not present then metric will incremented by 1var apminsight = require('apminsight');
var app = require('express')();
var http = require('http').Server(app);
app.get('/buy', function(req, res){
apminsight.incrementCustomMetric('products', req.product.count);
res.sendFile(__dirname + '/index.html');
});
http.listen(3000);
This API collects the average of custom metrics.
apminsight.averageCustomMetric(metricName, metricValue)
metricName : string value
metricValue : number
var apminsight = require('apminsight');
var app = require('express')();
var http = require('http').Server(app);
app.get('/pay', function(req, res){
apminsight.averageCustomMetric('amount', req.amount);
res.sendFile(__dirname + '/index.html');
});
http.listen(3000);apminsight.addParameter("key", value);where,
key - Name of the parameter.
value - Value of the Parameter. It can be of any type, however, agent converts them to string internally.
var apminsight = require('apminsight');
var app = require('express')();
var http = require('http').Server(app);
app.get('/', function(req, res){
apminsight.addParameter("User Detail", "APM User");
apminsight.addParameter("User ID", 408);
res.sendFile(__dirname + '/index.html');
});
http.listen(3000);