The frontend monitoring feature of Application Real-Time Monitoring Service (ARMS) allows you to configure a variety of SDK parameters to meet additional requirements. For example, you can use these SDK parameters to ignore the reports of specific URLs, APIs, and JavaScript (JS) errors, aggregate pages by filtering non-key characters from URLs, and reduce reports and loads by using random sampling.

Methods in this topic

pid | uid | tag | page | setUsername | enableSPA | parseHash | disableHook | ignoreUrlCase | urlHelper | apiHelper | parseResponse | ignore | disabled | sample | sendResource | useFmp | enableLinkTrace | release | environment | behavior | c1\c2\c3 | autoSendPerf

Configure parameters of the frontend monitoring SDK

You can configure parameters of the frontend monitoring SDK in one of the following ways:

  • When you install an ARMS frontend monitoring agent to a page, add extra parameters to config.

    For example, in the following sample code, in addition to the default pid parameter, the enableSPA parameter for single-page application (SPA) is added to config.

    <script>
    !(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxxxxx",enableSPA:true};
    with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
    })(window,document,"https://retcode.alicdn.com/retcode/bl.js","__bl");
    </script>                    
  • After the page is initialized, call the setConfig method in the JS code to modify the parameters.

    The following table describes the parameters that the __bl.setConfig(next) method calls.

    Parameter Type Description Required Default value
    next Object The parameter and its value that you want to modify. Yes N/A

    The following code provides an example on how to modify the disableHook parameter to disable automatic API reporting:

    __bl.setConfig({
        disableHook: true
    });            

pid

Parameter Type Description Required Default Value
pid String The unique ID of the project, which is automatically generated by ARMS when it creates the site. Yes N/A

[Back to the top]

uid

Parameter Type Description Required Default Value
uid String The user ID, which identifies the user and can be manually configured to be retrieved based on the user ID. If you do not configure the settings, they are automatically generated by the SDK and updated semi-annually.
  • Weex scenario: Required
  • Other scenarios: not required
  • Weex scenario: None
  • Other scenarios: Automatically generated by SDKs

The following code provides an example on how to call the setConfig method to modify an SDK parameter:

__bl.setConfig({
    uid: 12345
});        

[Back to the top]

tag

Parameter Type Description Required Default Value
tag String The input tag. Each log carries a tag. No None

[Back to the top]

page

Parameter Type Description Required Default Value
page String The page name. No The key part of the current page URL is taken by default: host + pathname .

[Back to the top]

setUsername

Parameter Type Description Required Default Value
setUsername Function Lets you set up a method that needs to return a user name of type String. No None

This parameter is used to configure a method that returns a username as a string. After you configure this parameter, you can use the returned username to perform full link tracing on the user and query the sessions related to the user.

Note If the username cannot be obtained when the page starts to be loaded, you can set the return value to null rather than a temporary username. In general, the SDK calls the setUsername method to obtain the username when the SDK sends logs. However, if you set the return value to a temporary username, the SDK uses the temporary username and does not call setUsername to obtain the actual username.

The following code provides an example on how to call the setConfig method to modify an SDK parameter:

__bl.setConfig({
    setUsername: function () {
        return "username_xxx";
    }
});            

[Back to the top]

enableSPA

Parameter Type Description Required Default Value
enableSPA Boolean Listen to the hashchange event on the page and report the PV again. This method is applicable to single-page application scenarios. No (supported by Web scenarios only) false

[Back to the top]

parseHash

Parameter Type Description Required Default Value
parseHash Function And enableSPA Use with. No See below

In SPA scenarios, if the enableSPA parameter is set to true and the page triggers a hashchange event, the parseHash parameter is used to resolve the URL hash into page name. For more information about SPAs, see Page data reporting of SPAs.

Default value

The default value is obtained by using the following string processing method:

function (hash) {
    var page = hash ? hash.replace(/^#/, '').replace(/\?.*$/, '') : '';
    return page || '[index]';
}           

You do not need to modify this parameter in most cases. However, if you want to use a custom page name to report data or the URL hash is complex, you can modify this parameter. The following code provides an example:

// Define the mapping between the hash values and page names. 
var PAGE_MAP = {
    '/': 'Homepage',
    '/contact': 'Contact us',
    '/list': 'Data list',
    // ...
};
// Call an SDK method after the page is loaded. 
window.addEventListener('load', function (e) {
    // Call the setConfig method to modify an SDK parameter. 
    __bl.setConfig({
        parseHash: function (hash) {
            key = hash.replace(/\?.*$/, '');
            return PAGE_MAP[key] || 'Unknown page';
        }
    });
});

[Back to the top]

disableHook

Parameter Type Description Required Default Value
disableHook Boolean Disables the listener for AJAX requests. No false : By default, the listener is listened to and used for reporting the API call success rate.

[Back to the top]

ignoreUrlCase

Parameter Type Description Required Default Value
ignoreUrlCase Boolean Page URL case is ignored. No true : defaults to ignored.

[Back to the top]

urlHelper

Parameter Type Description Required Default Value
urlHelper * Replace the old parameter ignoreUrlPath , which is used to configure URL filtering rules. No See below

When a page URL is in a similar format as http://xxx.com/projects/123456 (the value that follows projects is the project ID) and xxx.com/projects/123456 is reported as a page, the page cannot be aggregated during data browsing. To implement page aggregation, set the urlHelper parameter to filter non-key characters in the page URLs, such as the project ID in this example.

Notice
  • The ignoreUrlPath parameter was used to configure URL filtering rules and is replaced by the urlHelper parameter. If you use the ignoreUrlPath parameter, the configuration still takes effect. If you use the ignoreUrlPath and urlHelper parameters at the same time, the configuration specified by the urlHelper parameter takes effect.
  • This parameter is valid only when the page URL is automatically obtained and used to indicate a page. This parameter is invalid if you manually modify the specified page by calling the setPage or setConfig method or the enableSPA parameter is set to true. For more information about the setConfig method, see API reference.

Default value

The default value of this parameter is the following array and does not need to be modified.

[
    // Replace all digits in the URL with asterisks (*). 
    {rule: /\/([a-z\-_]+)?\d{2,20}/g, target: '/$1**'},
    // Remove the forward slash (/) at the end of the URL. 
    /\/$/
]                    

The default value of this parameter filters out the numbers in strings such as xxxx/123456. For example, xxxx/00001 and xxxx/00002 are modified to xxxx/**.

Value type

The value of the urlHelper parameter can be of one of the following types:

  • String or RegExp (regular expression): The matched strings are removed.
  • Object<rule, target>: The object contains two keys: rule and target, which are the input parameters of the replace method of the JS string. For more information, see the String::replace method described in related JS tutorials.
  • Function: The original string is used as the input parameter for method execution, and the execution result is used to indicate a page.
  • Array: This type is used to set multiple rules. The type of each rule can be one of the preceding types.

[Back to the top]

apiHelper

Parameter Type Description Required Default Value
apiHelper * Replace the old parameter ignoreApiPath To configure API filtering rules. No See below

This parameter filters out non-key characters in API URLs when the results of API requests are automatically reported. The usage and function of this parameter are the same as those of urlHelper.

Notice The ignoreApiPath parameter was used to configure API filtering rules and is replaced by the apiHelper parameter. If you use the ignoreApiPath parameter, the configuration still takes effect. If you use the ignoreApiPath and apiHelper parameters at the same time, the configuration specified by the apiHelper parameter takes effect.

Default value

The default value of this parameter is an object and does not need to be modified.

{rule: /(\w+)\/\d{2,}/g, target: '$1'}                    

The default value of this parameter filters out the numbers in strings such as xxxx/123456.

If you need to report the parameter that follows ? in an API URL, such as the pid parameter in https://arms.console.aliyun.com/apm?pid=fr6fbgbeot, you can report such data in one of the following ways:

  • Call the ignore method to disable automatic data reporting. For more information, see ignore.
  • Call the api() method to manually report results of API requests. For more information, see api().

[Back to Top]

parseResponse

Parameter Type Description Required Default Value
parseResponse Function It is used to parse the data returned when the API is automatically reported. No See below

This parameter parses the data returned when the results of API requests are automatically reported.

Default value

The following code shows the default value of this parameter:

function (res) {
    if (!res || typeof res !== 'object') return {};
    var code = res.code;
    var msg = res.msg || res.message || res.subMsg || res.errorMsg || res.ret || res.errorResponse || '';
    if (typeof msg === 'object') {
        code = code || msg.code;
        msg = msg.msg || msg.message || msg.info || msg.ret || JSON.stringify(msg);
    }
    return {msg: msg, code: code, success: true};
}                    

The preceding code parses the returned data and tries to extract the msg and code parameters. For general applications, the default value of this parameter does not need to be modified. If the default value cannot meet your business requirements, you can set a new value.

[Back to the top]

ignore

Parameter Type Description Required Default Value
ignore Object Ignores Errors of the specified URL/API/JS. Logs that conform to rules are ignored and not reported, including sub-configuration items ignoreUrls , ignoreApis , ignoreErrors and ignoreResErrors . No See below

The value of the ignore parameter is an object that contains four properties: ignoreUrls, ignoreApis, ignoreErrors, and ignoreResErrors. You can set one or more properties of the parameter value.

Default value

The following code shows the default value of this parameter:

ignore: {
        ignoreUrls: [],
        ignoreApis: [],
        ignoreErrors: [],
        ignoreResErrors: []
    },                    

ignoreUrls

The ignoreUrls property is used to ignore reports from specific URLs. Logs from the URLs that comply with the specified rule are not reported. The value of this property can be a string (the String type), a regular expression (the RegExp type), a method (the Function type), or an array that includes the preceding three types. The following code provides an example:

__bl.setConfig({
                ignore: {
                    ignoreUrls: [
                    'http://host1/',  // Specify a string.
                    /.+?host2.+/,     // Specify a regular expression.
                    function(str) {   // Configure the method.
                        if (str && str.indexOf('host3') >= 0) {
                            return true; // The data is not reported.
                        }
                        return false; // The data is reported.
                    }]
                }
            });                    

ignoreApis

The ignoreApis property is used to ignore the reports from APIs that comply with a specified rule. The value of this property can be a string (the String type), a regular expression (the RegExp type), a method (the Function type), or an array that includes the preceding three types. The following code provides an example:

__bl.setConfig({
                ignore: {
                    ignoreApis: [
                    'api1','api2','api3', // Specify a string.
                    /^random/,  // Specify a regular expression.
                    function(str) { // Configure the method.
                        if (str && str.indexOf('api3') >= 0) return true;   // The data is not reported.
                        return false;   // The error is reported.
                    }]
                }
            });                    

ignoreErrors

The ignoreErrors property is used to ignore JS errors that comply with a specified rule. The value of this property can be a string (the String type), a regular expression (the RegExp type), a method (the Function type), or an array that includes the preceding three types. The following code provides an example:

__bl.setConfig({
                ignore: {
                    ignoreErrors: [
                    'test error', // Specify a string.
                    /^Script error\.?$/, // Specify a regular expression.
                    function(str) { // Configure the method.
                        if (str && str.indexOf('Unkown error') >= 0) return true;   // The error is not reported.
                        return false;   // The error is reported.
                    }]
                }
            });            

ignoreResErrors

The ignoreErrors property is used to ignore resource errors that comply with a specified rule. The value of this property can be a string (the String type), a regular expression (the RegExp type), a method (the Function type), or an array that includes the preceding three types. The following code provides an example:

__bl.setConfig({
                ignore: {
                    ignoreResErrors: [
                    'http://xx/picture.jpg', // Specify a string.
                    /jpg$/, // Specify a regular expression.
                    function(str) { // Configure the Method.
                        if (str && str.indexOf('xx.jpg') >= 0) return true;   // The error is not reported.
                        return false;   // The error is reported.
                    }]
                }
            });

[Back to the top]

disabled

Parameter Type Description Required Default Value
disabled Boolean Specifies whether to disable the log reporting function. No false

[Back to the top]

sample

Parameter Type Description Required Default Value
sample Integer The log sampling configuration. The value is an integer ranging from 1 to 100. For performance logs and successful API logs, follow the steps in 1/sample The proportional sampling of. For more information about metrics descriptions of performance logs and successful API logs, see Statistical metrics. No 1

Benefits of the sample parameter:

  • Reduces the amount of API data to be reported, which reduces the costs. We recommend that you specify the data that does not require monitoring by setting the ignore parameter. For more information, see ignore.
  • Reduces the performance overhead of data collection.

Description of the sample parameter:

  • You can configure this parameter to randomly sample and report performance logs and successful API logs to reduce the number of reports and the load. ARMS restores the data based on the sampling configuration when ARMS processes the reported logs in the background. This parameter does not affect the calculation of JS error rate and API failure rate. However, if you set this parameter, you may fail to obtain the required details when you query API details or the details of relevant data.

  • The default value of the sample parameter is 1. The valid values of this parameter are integers from 1 to 100. The sampling rate can be calculated by using the following formula: 1/Value of sample. For example, the parameter values 1, 10, and 100 indicate the sampling rates of 100%, 10%, and 1%.

Warning Sampling is randomly performed. If the number of reported items is small, this parameter may cause a large number of statistical result errors. We recommend that you use this parameter for the websites whose daily average page views (PVs) is more than 1 million.

[Back to the top]

sendResource

Parameter Type Description Required Default Value
sendResource Boolean Reports static resources on a page. No false

If the sendResource parameter is set to true, the static resources loaded to the current page are reported when the load event of the page is triggered. If the page loading speed is slow, you can view the waterfall chart of static resources on the Session Traces page to determine the cause.

The following code provides an example on how to configure the sendResource parameter:

<script>
!(function(c,b,d,a){c[a]||(c[a]={});c[a].config={pid:"xxxxxx",sendResource:true};
with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
})(window,document,"https://retcode.alicdn.com/retcode/bl.js","__bl");
</script>            
Note The value of this parameter is checked when the load event of the page is triggered. Therefore, set the sendResource parameter in config as shown in the preceding example. Do not call the setConfig method because this method may check the value of this parameter after the load event of the page is complete. In this case, the configuration of this parameter does not take effect.

[Back to the top]

useFmp

Parameter Type Description Required Default Value
useFmp Boolean Collect FMP(First Meaningful Paint, First valid rendering) data from the First screen. No false

[Back to the top]

enableLinkTrace

Parameter Type Description Required Default Value
enableLinkTrace Boolean For more information about tracing frontend and backend links, see Use the front-to-back tracing feature to diagnose API errors. No (supported only in Web scenarios, Alipay applets, WeChat applets, and DingTalk applets.) false

[Back to the top]

release

Parameter Type Description Required Default Value
release String The version of the application. We recommend that you configure to view the reports of different versions. No undefined

[Back to the top]

environment

Parameter Type Description Required Default Value
environment String The environment field. Valid values: prod, gray, pre, daily, and local, where:
  • prod indicates an online environment.
  • gray indicates a phased-release environment.
  • pre indicates a staging environment.
  • daily indicates a daily environment.
  • local indicates a local environment.
No prod

[Back to the top]

behavior

Parameter Type Description Required Default Value
behavior Boolean Whether to record the error user behavior to facilitate troubleshooting. No (supported only in Web scenarios and mini program scenarios) The Browser defaults to true The mini program defaults to false .

[Back to the top]

autoSendPerf

Parameter Type Description Required Default Value
autoSendPerf Boolean Specifies whether to allow automatic sending of performance logs. No true

[Back to the top]

c1\c2\c3

In addition to the preceding parameters, you may need to specify more information to handle business problems. Therefore, the ARMS SDK provides three parameters for which you can customize properties. After you configure a custom parameter, the properties of the parameter are included in each reported log.

Parameter Type Description Required Default Value
c1 String Custom service field. Each log carries the field. No None
c2 String Custom service field. Each log carries the field. No None
c3 String Custom service field. Each log carries the field. No None

[Back to the top]