API参考 - 应用实时监控服务ARMS

本页索引

数据上报类接口：api() | error() | speed() |sum() | avg() |resource() |event()|
方法类接口：setConfig() | setPage() | setCommonInfo()|custom()

`api()`

调用api()接口来上报页面的API调用成功率。

SDK默认会监听页面的AJAX请求并调用此接口上报。如果页面的数据请求方式是JSONP或者其他自定义方法（例如客户端SDK等），可以在数据请求方法中调用api()方法手动上报。

说明如果要调用此接口，建议在SDK配置项中将disableHook设置为true。更多信息，请参见disableHook。

api()语法：

__bl.api(api, success, time, code, msg, begin, traceId, sid)

或者

__bl.api({api: xxx, success: xxx, time: xxx, code: xx, msg: xx, begin: xx, traceId: xx, sid: xx})

表 1. `api()`调用参数
参数	类型	描述	是否必选	默认值
api	String	接口名	是	无
success	Boolean	是否调用成功	是	无
time	Number	接口耗时	是	无
code	String/Number	返回码	否	''
msg	String	返回信息	否	''
begin	Number	API请求开始时间戳	否	''
traceId	String	EagleEye-TraceID的值	否	''
sid	String	EagleEye-SessionID的值	否	''

api()使用示例：

var begin = Date.now(),
    url = '/data/getTodoList.json',
    traceId = window.__bl && __bl.getTraceId('EagleEye-TraceID'),
    sid = window.__bl && __bl.getSessionId('EagleEye-SessionID');
// 备注：请求的header部分请加入EagleEye-TraceID、EagleEye-SessionID
fetch(url, {
    headers: {
        'EagleEye-TraceID': traceId,
        'EagleEye-SessionID': sid
    }
}).then(function (result) {
    var time = Date.now() - begin;
    // 上报接口调用成功
    window.__bl && __bl.api(url, true, time, result.code, result.msg, begin, traceId, sid);
    // do something ....
}).catch(function (error) {
    var time = Date.now() - begin;
    // 上报接口调用失败
    window.__bl && __bl.api(url, false, time, 'ERROR', error.message, begin, traceId, sid);
    // do something ...
});

[回到顶部]

`error()`

调用error()接口来上报页面中的JS错误或使用者想关注的异常。

一般情况下，SDK会监听页面全局的Error并调用此接口上报异常信息，但由于浏览器的同源策略往往无法获取错误的具体信息，此时就需要使用者手动上报。

error()语法：

__bl.error(error, pos)

表 2. `error()`调用参数
参数	类型	描述	是否必选	默认值
error	Error	JS的Error对象	是	无
pos	Object	错误发生的位置，包含以下3个属性。	否	无
pos.filename	String	错误发生的文件名	否	无
pos.lineno	Number	错误发生的行数	否	无
pos.colno	Number	错误发生的列数	否	无

error()使用示例1：监听页面的JS Error并上报。

window.addEventListener('error', function (ex) {
    // 一般事件的参数中会包含pos信息。
    window.__bl && __bl.error(ex.error, ex);
});

error()使用示例2：上报一个自定义的错误信息。

window.__bl && __bl.error(new Error('发生了一个自定义的错误'), {
    filename: 'app.js', 
    lineno: 10, 
    colno: 15
});

error()使用示例3：上报一个自定义类型的错误信息。

__bl.error({name:'CustomErrorLog',message:'this is an error'}, {
    filename: 'app.js', 
    lineno: 10, 
    colno: 15
});

[回到顶部]

`speed()`

调用speed()用于上报页面中的一些自定义的关键时间节点。

speed()的语法：

__bl.speed(point, time)

表 3. `speed()`调用参数
参数	类型	描述	是否必选	默认值
point	Enum	测速关键字，必须是 s0~s10	是	无
time	Number	耗时（毫秒），默认是当前时间-页面起始时间	否	Date.now() - startTime

使用示例：

__bl.speed('s0');
__bl.speed('s1', 1024);

[回到顶部]

`sum()`

调用sum()方法，可以自定义上报的日志，它通常被用于统计业务中特定事件发生的次数。通过sum()方法上报的数据，您可以在自定义统计页面查看：

自定义事件发生的趋势图。
发生该事件的PV或UV统计。
维度分布信息。

sum()语法：

__bl.sum(key, value)

表 4. `sum()`调用参数
参数	类型	描述	是否必选	默认值
key	String	事件名	是	无
value	Number	单次累加上报量	否	1

sum()使用示例：

__bl.sum('event-a');
__bl.sum('event-b', 3);

[回到顶部]

`avg()`

调用avg()可以自定义上报的日志，它通常被用于计算业务中特定事件发生的平均次数或平均值。通过avg()方法上报的数据，您可以在自定义统计页面查看：

自定义事件发生的趋势图。
发生该事件的PV或UV统计。
维度分布信息。

avg()语法：

__bl.avg(key, value)

表 5. `avg()`调用参数
参数	类型	描述	是否必选	默认值
key	String	事件名	是	无
value	Number	统计上报量	否	0

avg()使用示例：

__bl.avg('event-a', 1);
__bl.avg('event-b', 3);

[回到顶部]

`resource()`

调用resource()用于业务方主动上报资源加载数据。

resource()语法：

__bl.resource(data, sampling)

表 6. `resource()`调用参数
参数	类型	描述	是否必选	默认值
data	Object	需要上报的数据	是	无
sampling	String	采样率	否	1

其中data的object对于字段有要求，具体如下：

begin: performance fetchStart的时间戳。
dom: DOM解析耗时，domInteractive - responseEnd。
load: 页面完全加载时间, loadEventStart - fetchStart。
res: 上报的资源加载数据，为Array格式。performance.getEntriesByType('resource')。
dl: 当前的page URL。

说明

如果想主动上报，需要把静默上报resource部分关掉（在config中设置sendResource: false），否则有可能一次访问中上报多次resource，会有重复信息。
上报的内容获取到的标识，建议用__bl.session, 该值对应着sid，一次PV会有一个该标识，如果一次PV上报多次，该值是一样的。

[回到顶部]

`event()`

调用event()用于统计业务场景中的自定义事件或任务的频次、成功率、耗时等信息。

event()语法：

__bl.event({key: 'xxx', success: xxx, time: xxx})

表 7. `event()`调用参数
参数	类型	描述	是否必选	默认值
key	String	事件名	是	无
success	Boolean	事件成功与否	否	true
time	Number	事件耗时（ms）	否	0
c1	String	自定义补充字段	否	无
c2	String	自定义补充字段	否	无
c3	String	自定义补充字段	否	无

event()使用示例：

__bl.event({
  key: 'submit-xxx',
  success: false,
  time: 100
});

[回到顶部]

`setConfig()`

在SDK初始完成后调用setConfig()接口来重新修改部分配置项，关于SDK配置项的详细信息，请参见SDK配置项。

setConfig()语法：

__bl.setConfig(next)

表 8. `setConfig()`调用参数
参数	类型	描述	是否必选	默认值
next	Object	需要修改的配置项以及值	是	无

setConfig()使用示例：修改disableHook禁用API自动上报。

__bl.setConfig({
    disableHook: true
});

[回到顶部]

`setPage()`

调用setPage()接口来重新设置页面的page name（默认会触发重新上报PV）。此接口一般用于单页面应用，更多信息，请参见SPA页面上报。

setPage()语法：

__bl.setPage(page, sendPv)

表 9. `setPage()`调用参数
参数	类型	描述	是否必选	默认值
page	String	新的page name	是	无
sendPv	Boolean	是否上报PV，默认会上报。	否	true

setPage()使用示例：

// 设置当前页面的page name为当前的URL hash，并重新上报PV
__bl.setPage(location.hash);

// 仅设置当前页面的page为'homepage'，但不触发PV上报
__bl.setPage('homepage', false);

[回到顶部]

`setCommonInfo()`

调用setCommonInfo()用于设置公共字段。

setCommonInfo()语法：

__bl.setCommonInfo(obj)

setCommonInfo()其中入参是object，示例如下：

__bl.setCommonInfo({
  name: 'xxx',
  common: 'xxx'
});

说明该方法建议object信息不要太大，否则容易导致get请求超长，从而导致请求失败的问题。

[回到顶部]

`custom()`

调用custom()用于上报自定义业务信息。

custom()语法：

__bl.custom(obj, sampling)

表 10. `custom()`调用参数
参数	类型	描述	是否必选	默认值
obj	Object	业务信息	是	''
sampling	Number	采样率	否	''

custom()示例如下：

__bl.custom({
  key1: 'xxx', // value必须为length<=20的string
  key2: 'xxx'
}, 10); // 10表示采样率为1/10

说明该方法建议object信息不要太大，否则容易导致get请求超长，从而导致请求失败的问题。

[回到顶部]

创建多实例方法

创建多实例请使用NPM包方式，现在正式版NPM包已发布，NPM包：alife-logger 。

Web页面

使用方法：

const BrowerLogger = require('alife-logger');
const bl2 = BrowerLogger.createExtraInstance(props); // 通过createExtraInstance 创建实例
bl2.custom({
  key: 'biz',
  msg: 'msg info'
});

说明其中props为Object，具体的参数与SDK的config基本保持一致。

如果新实例只上报自定义信息：

var props = {
  pid: 'xxxx', //新实例需要上报的站点
  region: 'cn',
  page: '',
  uid: ''
}

Weex页面

使用方法：

const WeexLogger = require('alife-logger/weex');
const wl2 = WeexLogger.createExtraInstance(props); // 通过createExtraInstance 创建实例
wl2.custom({
  key: 'biz',
  msg: 'msg info'
});

说明其中props为Object，具体的参数与SDK的config基本保持一致。

如果新实例只上报自定义信息：

var props = {
  pid: 'xxxx', //新实例需要上报的站点
  region: 'cn',
  sendRequest: function(data, imgUrl) {
    // 发送Get日志方案
  },
  postRequest: function(data, imgUrl) {
    // 发送POST日志方案
  }
}

小程序页面

使用方法：

import MiniProgramLogger from 'alife-logger/miniprogram'; // 具体路径根据是钉钉小程序、支付宝小程序及其他类小程序来选择对应的路径
const MiniInstance = MiniProgramLogger.createExtraInstance({
  pid: 'xxxinstance',
  uid: 'userxxx', // 用来设置用户uid，统计UV信息
  region: 'cn', // region为cn、sg分别表示是日志上报到中国服务器、还是新加坡服务器，如不配置默认是中国服务器
  // 基础小程序监控需要手动传入rpc(方法实现按照实际业务来写)
  sendRequest: (url, resData) => {
    // 发送方法
  }
});