SDK methods - Application Real-Time Monitoring Service - Alibaba Cloud Documentation Center

Browser Monitoring SDKs provide methods to report data and modify SDK configurations.

Methods in this topic

Methods for data reporting: api(), error(), sum(), avg(), reportBehavior(), and performance().
Methods for SDK configuration modification: setConfig(), setPage(), setCommonInfo(), and addBehavior().

`api()`

You can call the api() method to report the success rate of API calls on a page.

By default, the SDK listens to Asynchronous JavaScript and XML (AJAX) requests on the page and calls this method to report data. If data on the page is requested by using JSON with Padding (JSONP) or other custom tools such as the client SDK, you can call the api() method in the data request for manual reporting.

Note

To call this method, we recommend that you set the disableHook parameter to true in the SDK configurations. For more information, see disableHook.

Syntax of 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})

Table 1. Request parameters of `api()`
Parameter	Type	Description	Required	Default value
api	String	The name of the method.	Yes	None
success	Boolean	Specifies whether the call is successful.	Yes	None
time	Number	The amount of time consumed by the call.	Yes	None
code	String/Number	The status code.	No	None
msg	String	The response information.	No	None
begin	Number	The time when the API call started. The value is a timestamp.	No	None
traceId	String	The value of EagleEye-TraceID.	No	None
sid	String	The value of EagleEye-SessionID.	No	None

Example of api():

var begin = Date.now(),
    url = '/data/getTodoList.json',
    traceId = window.__bl && __bl.getTraceId('EagleEye-TraceID'),
    sid = window.__bl && __bl.getSessionId('EagleEye-SessionID');
// Specify EagleEye-TraceID and EagleEye-SessionID in the request header.
fetch(url, {
    headers: {
        'EagleEye-TraceID': traceId,
        'EagleEye-SessionID': sid
    }
}).then(function (result) {
    var time = Date.now() - begin;
    // Report that the call is successful.
    window.__bl && __bl.api(url, true, time, result.code, result.msg, begin, traceId, sid);
    // do something ....
}).catch(function (error) {
    var time = Date.now() - begin;
    // Report that the call fails.
    window.__bl && __bl.api(url, false, time, 'ERROR', error.message, begin, traceId, sid);
    // do something ...
});

[Back to Top]

`error()`

You can call the error() method to report JavaScript (JS) errors or exceptions that you want to capture on a page. You can view the details of JS errors on the JS Error Diagnosis page of Browser Monitoring.

Generally, the SDK listens to global errors on the page and calls this method to report exceptions. However, error details are usually out of reach due to the same-origin policy of the browser. In this case, you must manually report such errors.

Syntax of error():

__bl.error(error, pos)

Table 2. Request parameters of `error()`
Parameter	Type	Description	Required	Default value
error	Error	The JS error object.	Yes	None
pos	Object	The location where the error occurs. The location contains the following attributes: pos.filename, pos.lineno, and pos.colno.	No	None
pos.filename	String	The name of the file where the error occurs.	No	None
pos.lineno	Number	The number of the line where the error occurs.	No	None
pos.colno	Number	The number of the column where the error occurs.	No	None

Example 1 of error(): Listen to and report JS errors on a page.

window.addEventListener('error', function (ex) {
    // Event parameters usually contain location information. 
    window.__bl && __bl.error(ex.error, ex);
});

Example 2 of error(): Report a custom error.

window.__bl && __bl.error(new Error('A custom error has occurred.'), {
    filename: 'app.js', 
    lineno: 10, 
    colno: 15
});

Example 3 of error(): Report a custom error.

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

[Back to Top]

`sum()`

You can call the sum() method to customize the logs to be reported. The logs are used to count how many times a specific event occurs in a business scenario. You can view the following data reported by calling the sum() method on the Custom Statistics page:

Note

After you report data, it is displayed on the Custom Statistics page a few minutes later.

Trend chart of custom events
Page views (PVs) and unique visitors (UVs) of an event
Dimension distribution information

Syntax of sum():

__bl.sum(key, value)

Table 4. Request parameters of `sum()`
Parameter	Type	Description	Required	Default value
key	String	The name of the event.	Yes	None
value	Number	The number of reported items at a time.	No	1

Example of sum():

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

[Back to Top]

`avg()`

You can call the avg() method to customize the logs to be reported. The logs are used to count how many times a specific event occurs on average in a business scenario. You can view the following data reported by the avg() method on the Custom Statistics page:

Trend chart of custom events
PVs and UVs of an event
Dimension distribution information

Syntax of avg():

__bl.avg(key, value)

Table 5. Request parameters of `avg()`
Parameter	Type	Description	Required	Default value
key	String	The name of the event.	Yes	None
value	Number	The number of reported items.	No	0

Example of avg():

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

[Back to Top]

`reportBehavior()`

You can call the reportBehavior() method to immediately report the current behavior queue.

If you do not manually call this method, when a JS error occurs, the current behavior queue is automatically reported. The maximum size of a queue is 100. If the queue contains more than 100 behavior records, behavior records are discarded from the header of the queue.

Note

To call this method, you must set the behavior parameter to true in the SDK configurations.

Syntax of reportBehavior():

__bl.reportBehavior()

The reportBehavior() method does not have request parameters.

[Back to Top]

`performance()`

Important

This method is applicable only to web clients.

After the onLoad method is called, the performance() method is called to report custom performance metrics other than the default performance metrics.

Note

You can call this method only after the onLoad method is called. Otherwise, the call fails because the collection of default performance metrics is incomplete. The performance() method can be called only once during each PV.

How to call the performance() method:

Set the autoSendPerf parameter to false to disable automatic reporting of performance metrics and wait for manual reporting.
Call the __bl.performance(Object) method to manually report custom performance metrics. In this process, the default performance metrics are automatically reported.

Example 1 of performance() (by using CDN):

window.onload = () => {
 setTimeout(()=>{
  __bl.performance({cfpt:100, ctti:200, t1:300, …});
 }, 1000); // Set a delay to ensure that the default performance data is collected. 
};

Example 2 of performance() (by using npm packages):

const BrowserLogger = require('alife-logger');
const __bl = BrowserLogger.singleton({pid:'Unique site ID'});
window.onload = () => {
 setTimeout(()=>{
  __bl.performance({cfpt:100, ctti:200, t1:300, …});
 }, 1000); // Set a delay to ensure that the default performance data is collected. 
};

Note

Descriptions of custom performance metrics:

cfpt: the custom first paint time
ctti: the first custom time to interact
t1 to t10: 10 custom performance metrics

[Back to Top]

`setConfig()`

You can call the setConfig() method to modify specific configuration items after the SDK initialization. For more information, see SDK reference.

Syntax of setConfig():

__bl.setConfig(next)

Table 8. Request parameters of `setConfig()`
Parameter	Type	Description	Required	Default value
next	Object	The parameter that you want to modify and the new parameter value.	Yes	None

Example of setConfig(): Change the value of the disableHook parameter to disable automatic API reporting.

__bl.setConfig({
    disableHook: true
});

[Back to Top]

`setPage()`

You can call the setPage() method to reset the page name of a page. By default, PV data is reported again. This method is typically used for single-page applications (SPAs). For more information, see Page data reporting of SPAs.

Note

When the PV data is reported again, existing data is not overwritten. A new data entry is added.

Syntax of setPage():

__bl.setPage(page, sendPv)

Table 9. Request parameters of `setPage()`
Parameter	Type	Description	Required	Default value
page	String	The new page name.	Yes	None
sendPv	Boolean	Specifies whether to report PV data. By default, PV data is reported.	No	true

Example of api():

Set the name of the current page to the current URL hash, and report PV data again.
__bl.setPage(location.hash);

// Set the name of the current page to homepage without triggering PV data reporting.
__bl.setPage('homepage', false);

[Back to Top]

`setCommonInfo()`

You can call the setCommonInfo() method to set common fields.

Syntax of setCommonInfo():

__bl.setCommonInfo(obj)

An object is passed in the setCommonInfo() method. Example of setCommonInfo():

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

Note

We recommend that you limit the size of the object for this method. Otherwise, the GET request is large in size and may fail.

[Back to Top]

`addBehavior()`

You can call the addBehavior() method to add a custom user behavior to the end of the current behavior queue.

The SDK maintains a user behavior queue with a maximum of 100 records. You can call the addBehavior() method to add a custom user behavior to the end of the current behavior queue. When a JS error occurs, the addBehavior() method reports the current behavior queue and clears the queue.

You can view user behaviors on the JS Error Diagnosis page. For more information, see Diagnose JS errors by backtracking user behaviors.

Note

To call this method, you must set the behavior parameter to true in the SDK configurations.

Syntax of addBehavior():

__bl.addBehavior(behavior)

Table 10. Request parameters of `addBehavior()`
Parameter	Type	Description	Required	Default value
data	Object	The behavior data. This parameter has the following two required fields: name: the behavior name of the STRING type. The name can be up to 20 characters in length. message: the behavior content of the STRING type. The value can be up to 200 characters in length.	Yes	None
page	String	The page where the behavior happens.	No	Value of the location.pathname parameter

Example of addBehavior():

_bl.addBehavior({
  data:{name:'string',message:'sting'},
  page:'string'
})

[Back to Top]

Create multiple instances

Use npm packages to create multiple instances. The official npm package alife-logger has been published.

Web pages

Example:

const BrowerLogger = require('alife-logger');
const bl2 = BrowerLogger.createExtraInstance(props); // Create instances by using the createExtraInstance method.
bl2.custom({
  key: 'biz',
  msg: 'msg info'
});

Note

The props parameter is of the Object type. The parameters contained in the props parameter are basically the same as those in the SDK configurations.

The new instances report only custom information:

var props = {
  pid: 'xxxx', // The ID of the site whose data the new instances need to report.
  region: 'cn',
  page: '',
  uid: ''
}

Weex pages

Example:

const WeexLogger = require('alife-logger/weex');
const wl2 = WeexLogger.createExtraInstance(props); // Create instances by using the createExtraInstance method.
wl2.custom({
  key: 'biz',
  msg: 'msg info'
});

Note

The props parameter is of the Object type. The parameters contained in the props parameter are basically the same as those in the SDK configurations.

The new instances report only custom information:

var props = {
  pid: 'xxxx', // The ID of the site whose data the new instances need to report.
  region: 'cn',
  sendRequest: function(data, imgUrl) {
    // Send the GET log scheme.
  },
  postRequest: function(data, imgUrl) {
    // Send the POST log scheme.
  }
}

Mini programs

Example:

import MiniProgramLogger from 'alife-logger/miniprogram'; // Specify the path based on the type of the mini-program, such as the DingTalk or Alipay mini-program. 
const MiniInstance = MiniProgramLogger.createExtraInstance({
  pid: 'xxxinstance',
  uid: 'userxxx', // The ID of the user, which is used to collect the UV data. 
  region: 'cn', // Specify whether the application to which logs are to be reported is deployed in China or Singapore. The value cn indicates China and the value sg indicates Singapore. If you do not specify this parameter, the value is set to cn. 
  // Specify the remote procedure call (RPC) method based on your business to perform browser monitoring of mini-programs. 
  sendRequest: (url, resData) => {
    // The sending method. 
  }
});