Help APM APM for Node.js Custom Instrumentation

Custom instrumentation for Node.js applications

By default, the APM Insight Node.js agent captures incoming web requests like http, https, http2, and other similar ones. To gain more granularity, you can use the custom instrumentation APIs. This helps you analyze specific transactions or code blocks in your applications.

APIs, as well as their functionality and syntax, are covered below.

Note: To use custom instrumentation in your Node.js applications, you must have the APM Insight module installed. Use the following command to load the APM Insight module in your application:

var apminsight = require('apminsight')

API's to 

  1. Monitor web/background transactions
  2. Monitor custom components
  3. Track handled errors
  4. Instrument app parameters
  5. Track custom parameters

Monitor web/background transactions:

  • By default, incoming web requests are automatically collected by the agent and displayed under the Web transactions tab. However, other client-server communications, like socket connections, are not monitored by the agent. Such transactions can be monitored using an API.
  • The agent does not monitor background transactions by default. You can monitor background transactions by instrumenting them with the API below.
  • You can also customize the names of your transaction or skip transactions from monitoring using the given APIs.
  • When you instrument web or background transactions, they must be followed by the End transaction API.

API to instrument web transactions

Syntax:

apminsight.startWebTransaction(txnName, handler)
txnName : string value
handler : handler is the function, that will be executed once txn is created

Example:

var 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);  

Output:

web transactions

API to instrument background transactions

Syntax:

apminsight.startBackgroundTransaction(txnName, handler)
txnName : string value
handler : handler is the function, that will be executed once txn is created

Example:

var apminsight = require('apminsight');
function doBackground(){
setInterval( function(){
apminsight.startBackgroundTransaction('routine', function(){
doSomething().........
apminsight.endTransaction();
}
}, 5000);
}

Output:

background transactions

API to change/customize transaction name

Syntax:

apminsight.setTransactionName(customTxnName)
cusTxnName : string value

Example:

var 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);

API to ignore transactions

Syntax:

apminsight.ignoreCurrentTransaction()

Example:

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

End transaction API

Syntax:

apminsight.endTransaction()

Monitor custom components

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.

API to track custom components

Syntax:

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

Example 1- 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);

Example 2- 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);

Output:

components

Track handled errors

All async i/o errors and unhandled errors are captured by the agent in general. This API comes in handy for 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.

API to track handled errors

Syntax:

apminsight.trackError(err)
err : Error object

Example:

var 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);

Output:

exceptions

Instrument app parameters

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.

API to instrument app parameters

incrementCustomMetric: This API collects the sum of custom metrics.

Syntax:

apminsight.incrementCustomMetric(metricName, metricValue)
metricName : string value
metricValue : optional, if it is not present then metric will incremented by 1

Example:

var 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);

averageCustomMetric: This API collects the average of custom metrics.

Syntax:

apminsight.averageCustomMetric(metricName, metricValue)

metricName : string value
metricValue : number

Example:

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

Output:

custom metrics

Track custom parameters

To give contextual meaning to traces, you can add additional parameters which can help you identify the context of the transaction trace.
Contextual metrics can be anything, a session id, user id or certain method parameters which can help you identify the specific information about a transaction trace.
You can add a maximum of 10 parameters to a transaction trace, these parameters can be viewed under Trace Summary

Syntax to track custom params

Syntax:

apminsight.addParameter("key", value);

Key - Name of the parameter

Value - Parameter of the value. It can be of any type, internally agent converts them to string.

Example:


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


OUTPUT:

The added parameter values will be displayed under the Custom parameters section of Trace details tab as follows:

custom parameters

 

Was this document helpful?
Thanks for taking the time to share your feedback. We’ll use your feedback to improve our online help resources.

Help APM APM for Node.js Custom Instrumentation