SDK reference

Methods in this topic

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

Use SDK configuration items

You can use SDK configuration items by using one of the following methods:

• When you install a Browser Monitoring agent to a page, add parameters to config based on your requirements.

  For example, in the following sample code, aside from the default pid parameter, the enableSPA parameter for single page applications (SPAs) 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://sdk.rum.aliyuncs.com/v1/bl.js","__bl");
  </script>                    

• After a page is initialized, call the setConfig method in the JavaScript code to modify the configuration items.

  The __bl.setConfig(next) method accepts the following parameter:

  Parameter	Type	Description	Required	Default value
  next	Object	The configuration item and its value that you want to modify.	Yes	None

pid

[Back to Top]

uid

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

__bl.setConfig({
    uid: 12345
});        

[Back to Top]

tag

[Back to Top]

page

[Back to Top]

setUsername

This configuration item is used to create a function. This function is used to obtain a username as a string. After the username is obtained, you can implement end-to-end session tracing and query sessions based on the username to troubleshoot issues.

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

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

[Back to Top]

enableSPA

[Back to Top]

parseHash

In single-page application (SPA) scenarios (see SPA page data reporting), if enableSPA is set to true, the parseHash parameter parses the URL hash into the Page field when a hashchange event occurs.

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]';
}           

Typically, you do not need to modify this parameter. However, if you want to use a custom page name to report page-specific data, or if the URL hash is complex, you can modify this configuration item. Example:

// Define the mapping between URL hashes and page names.
var PAGE_MAP = {
    '/': 'homepage',
    '/contact': 'contact us',
    '/list': 'data list',
    // ...
};
// Call the SDK method after the page is loaded.
window.addEventListener('load', function (e) {
    // Call the setConfig method to modify the SDK configuration item.
    __bl.setConfig({
        parseHash: function (hash) {
            key = hash.replace(/\?.*$/, '');
            return PAGE_MAP[key] || 'unknown page';
        }
    });
});

[Back to Top]

disableHook

[Back to Top]

ignoreUrlCase

[Back to Top]

urlHelper

When a page URL is similar to http://example.com/projects/123456 (where the number after projects is the project ID), reporting example.com/projects/123456 as the page prevents pages from being clustered into a single category when you view the data. In this case, to ensure that similar pages are clustered, you can use the urlHelper parameter to filter out non-critical characters, such as the project ID in this example.

Default value

The default value of this configuration item is the array in the following sample code. In most cases, you do not need to modify the value:

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

By default, this setting replaces numeric identifiers that follow a path segment. For example, bothxxxx/00001 andxxxx/00002 becomexxxx/**, just as an original URL likexxxx/123456 would.

Value types

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

• String orRegExp (regular expression): Removes the matched part of the URL string.

• Object<rule, target>: An object with rule and target keys. These are passed as arguments to the JavaScript String.prototype.replace() method. For details, see the String.prototype.replace() documentation.

• Function: A function that accepts the original URL string as an argument. Its return value is used as the final page value.

• Array: An array containing multiple rules, where each rule can be any of the types described above.

[Back to Top]

apiHelper

This parameter is used to remove non-key characters in page URLs when page-specific data about API operations is automatically reported. The usage and function of this parameter are the same as those of urlHelper.

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'}                    

This default setting filters out trailing numbers in API URL paths, such as in xxxx/123456.

If you need to report parameters from the query string (the part of an API URL after the ?), such as the pid parameter in https://arms.console.aliyun.com/apm?pid=fr6fbgbeot, you must use manual reporting:

• Call the ignore method to disable automatic data reporting. For more information, see ignore.

• Call the api() method to manually report the page-specific data about API operations. For more information, see api().

[Back to Top]

parseResponse

This configuration item is used to parse the data returned when the page-specific data of API operations is automatically reported.

Default value

The following sample code shows the default configurations:

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 default function parses the response to extract the msg and code properties. While this function is suitable for most applications, you can override it if it does not meet your business requirements.

[Back to Top]

ignore

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 sample code shows the default configurations:

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

ignoreUrls

The ignoreUrls property specifies URLs to ignore. Logs from URLs that match a specified pattern are not reported. The value can be a string, regular expression, function, or an array containing these types. Example:

__bl.setConfig({
                ignore: {
                    ignoreUrls: [
                    'http://host1/',  // string
                    /.+?host2.+/,     // regular expression
                    function(str) {   // function
                        if (str && str.indexOf('host3') >= 0) {
                            return true;   // Do not report
                        }
                        return false;      // Report
                    }]
                }
            });                    

ignoreApis

The ignoreApis property specifies APIs to ignore. Calls to APIs that match a specified pattern are not monitored. The value can be a string, regular expression, function, or an array containing these types. Example:

__bl.setConfig({
                ignore: {
                    ignoreApis: [
                    'api1','api2','api3', // string
                    /^random/,  // regular expression
                    function(str) { // function
                        if (str && str.indexOf('api3') >= 0) return true;   // Do not report
                        return false;   // Report
                    }]
                }
            });                    

ignoreErrors

The ignoreErrors property specifies JS errors to ignore. JS errors that match a specified pattern are not reported. The value can be a string, regular expression, function, or an array containing these types. Example:

__bl.setConfig({
                ignore: {
                    ignoreErrors: [
                    'test error', // string
                    /^Script error\.?$/, // regular expression
                    function(str) { // function
                        if (str && str.indexOf('Unknown error') >= 0) return true;   // Do not report
                        return false;   // Report
                    }]
                }
            });            

ignoreResErrors

The ignoreResErrors property specifies resource errors to ignore. Resource errors that match a specified pattern are not reported. The value can be a string, regular expression, function, or an array containing these types. Example:

__bl.setConfig({
                ignore: {
                    ignoreResErrors: [
                    'http://xx/picture.jpg', // string
                    /jpg$/, // regular expression
                    function(str) { // function
                        if (str && str.indexOf('xx.jpg') >= 0) return true;   // Do not report
                        return false;   // Report
                    }]
                }
            });

[Back to Top]

disabled

[Back to Top]

sample

Benefits:

• Reduces costs by reporting only sampled API data. We recommend that you identify 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:

• You can set this configuration item to randomly select and report performance logs and logs about successful API operations. This reduces the volume of reported data and the workloads. When ARMS processes the reported logs in the background, ARMS restores the data based on the sampling configurations. In this way, metrics such as the JS error rate or API failure rate are not affected by sampling and remain accurate. However, when you set this parameter, you may be unable to obtain the detailed data such as the API details.

• The default value of sample is 1. Valid values are integers from 1 to 100. The sampling rate is 1/sample. For example, 1 means 100% sampling, 10 means 10% sampling, and 100 means 1% sampling.

[Back to Top]

pvSample

Benefits:

• Reduces costs by reporting only sampled PV data.

• Reduces the performance overhead of data collection.

Description:

• You can set this configuration item to randomly select and report PV logs. This reduces the volume of reported data and the workloads. When ARMS processes the reported logs in the background, ARMS restores the data based on the sampling configurations. In this way, metrics such as the JS error rate are not affected by sampling and remain accurate.

• The default value of pvSample is 1. The sampling rate is 1/pvSample. For example, a value of 1 means 100% sampling, 10 means 10% sampling, and 100 means 1% sampling.

[Back to Top]

sendResource

If the sendResource parameter is set to true, the static resources on the page are reported when the page's load event triggers. If a page loads slowly, you can view its static resource waterfall chart on the Session Traces page to find the cause.

The following code provides an example on how to set 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://sdk.rum.aliyuncs.com/v1/bl.js","__bl");
</script>            

[Back to Top]

useFmp

[Back to Top]

enableLinkTrace

[Back to Top]

release

[Back to Top]

environment

[Back to Top]

behavior

[Back to Top]

autoSendPerf

[Back to Top]

c1\c2\c3

In addition to the preceding configuration items, the ARMS SDK provides three custom configuration items that you can configure fields to meet your business requirements. After you configure the fields, the fields values are included in all reported logs.

[Back to Top]