Node.js 应用的自定义埋点
默认情况下，APM Insight Node.js 代理会采集传入的 Web 请求，如 http、https、http2 及其他类似请求。为获得更细粒度的数据，您可以使用自定义埋点 API，从而分析应用中的特定事务或代码块。
以下将介绍各 API 的功能和语法。
注意：要在 Node.js 应用中使用自定义埋点，您必须已安装 APM Insight 模块。使用以下命令在您的应用中加载 APM Insight 模块：
var apminsight = require('apminsight')可用于以下用途的 API：
监控 Web/后台事务：
- 默认情况下，传入的 Web 请求由代理自动采集，并显示在 Web 事务标签页下。但其他客户端-服务器通信（如 Socket 连接）则不会被代理监控。此类事务可使用 API 进行监控。
- 代理默认不监控后台事务。您可以通过以下 API 对后台事务进行埋点以实现监控。
- 您还可以使用提供的 API 自定义事务名称或跳过特定事务的监控。
- 对 Web 或后台事务进行埋点时，必须在其后调用结束事务 API。
用于埋点 Web 事务的 API
语法：
apminsight.startWebTransaction(txnName, handler)
txnName : string value
handler : handler is the function, that will be executed once txn is created
示例：
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); 输出：
用于埋点后台事务的 API
语法：
apminsight.startBackgroundTransaction(txnName, handler)
txnName : string value
handler : handler is the function, that will be executed once txn is created
示例：
var apminsight = require('apminsight');
function doBackground(){
setInterval( function(){
apminsight.startBackgroundTransaction('routine', function(){
doSomething().........
apminsight.endTransaction();
}
}, 5000);
}输出：
用于更改/自定义事务名称的 API
语法：
apminsight.setTransactionName(customTxnName)
cusTxnName : string value
示例：
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
语法：
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);
结束事务 API
语法：
apminsight.endTransaction()
监控自定义组件
代理会采集默认的框架组件、类和方法。但用户自定义的类和方法只能通过以下 API 进行埋点后才可监控。相关详情可在"追踪"标签页下查看。此外，如果在已埋点的类或方法中调用了涉及数据库操作的事务，这些详情将反映在"数据库"标签页中。
用于追踪自定义组件的 API
语法：
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
示例 1 - 不含 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);示例 2 - 含 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);
输出：
追踪已处理错误
代理通常会采集所有异步 I/O 错误和未处理的错误。此 API 适用于已处理的错误。例如，如果您使用 try-catch 方法处理了错误，此类错误可通过此 API 进行上报，上报的错误将与对应的事务关联。采集到的错误可在"错误"和"追踪"标签页下查看。
用于追踪已处理错误的 API
语法：
apminsight.trackError(err)
err : Error object
示例：
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);输出：
埋点应用参数
通过应用参数，您可以监控应用中某个变量或操作的大小和频率等重要参数。要了解应用参数的工作原理，请参阅此处。
用于埋点应用参数的 API
incrementCustomMetric：此 API 采集自定义指标的累计总和。
语法：
apminsight.incrementCustomMetric(metricName, metricValue)
metricName : string value
metricValue : optional, if it is not present then metric will incremented by 1
示例：
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：此 API 采集自定义指标的平均值。
语法：
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);输出：
追踪自定义参数
为了赋予追踪记录上下文含义，您可以添加额外参数，以帮助识别事务追踪记录的上下文。
上下文指标可以是会话 ID、用户 ID 或某些方法参数等，可帮助您识别事务追踪记录的具体信息。
您最多可为一个事务追踪记录添加 10 个参数，这些参数可在"追踪摘要"下查看。
追踪自定义参数的语法
语法：
apminsight.addParameter("key", value);
Key - 参数名称
Value - 参数的值，可为任意类型，代理在内部将其转换为字符串。
示例：
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);
输出：
添加的参数值将在追踪详情标签页的自定义参数部分显示，如下所示：
