Sample configurations of the RUM SDK for web and HTML5 - Application Real-Time Monitoring Service

The Real User Monitoring (RUM) SDK for web and HTML5 of Application Real-Time Monitoring Service (ARMS) provides a wide variety of custom configurations to meet your business requirements. This topic describes the common SDK configurations of web and HTML5 applications for reference purposes.

SDK parameters

Parameter	Type	Description	Required	Default value
pid	string	The application ID.	Yes	-
endpoint	string	The address to which monitoring data is reported.	Yes	-
env	string	The environment of the application. Valid values: prod: production environment gray: canary release environment pre: pre-release environment daily: daily environment local: local environment	No	prod
version	string	The version of the application.	No	-
user	object	The user settings. By default, the user ID (user.id) is generated by the RUM SDK.	No	-
spaMode	string	Specifies whether to monitor page events and report page views again. The parameter is applicable to a single-page application (SPA). Valid values: hash history auto false	No	false
beforeReport	function	The function that is called before reporting data to modify or block the reported data.	No	-
reportConfig	object	The data reporting settings. For more information, see the reportConfig parameters section.	No	-
sessionConfig	object	For more information about the configurations of sessions, such as sampling and storage, see the SessionConfig section.	No	-
collectors	object	The Collector settings.	No	-
parseViewName	function	The function used to parse the view name (view.name). The input parameter is the URL of the page.	No	-
parseResourceName	function	The function used to parse the resource name (resource.name). The input parameter is the URL of the resource.	No	-
evaluateApi	function	The function used to parse API events. For more information, see the EvaluateApi parameters section.	No	-
filters	object	The event filter settings. For more information, see the filters parameters section.	No	-
whiteScreen	object	The function used to configure white screen monitoring. For more information, see the WhiteScreen parameters section.	No	-
properties	object	The custom properties that take effect on all events. For more information, see the properties parameters section.	No	-

If you use Alibaba Cloud Content Delivery Network (CDN) to access the application, make sure that the application resides in the global namespace RumSDK.default.

const ArmsRum = window.RumSDK.default;
// Before you use the RUM SDK, make sure that the SDK has been loaded.
// If the__rum configuration is not defined before the SDK is loaded, you can initialize the configuration here.
ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
});
// Initialization through an NPM package or CDN loading is the same.
ArmsRum.setConfig('env', 'pre');

User parameters

Parameter	Type	Description	Required	Default value
id	string	The user ID, which is generated by the SDK and cannot be modified.	No	-
tags	string	The tags.	No	-
name	string	The username.	No	-

Example

Note

If you want to use your own account system, we recommend that you change the username (user.name) or tags (user.tags) instead of the user ID (user.id). Overwriting the user ID affects the unique visitor (UV) data.

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  user: {
    name: 'your user.name',
    tags: 'your user.tags',
  },
});

reportConfig parameters

Parameter

Type

Description

Required

Default value

flushTime

number

The interval at which data is reported.

Valid values: 0 to 10000.

3000

maxEventCount

number

The maximum number of data entries reported at a time.

Valid values: 1 to 100.

Example

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  reportConfig: {
    flushTime: 0, // Specify that data is immediately reported.
    maxEventCount: 50, // Specify the maximum number of data entries reported at a time.
  },
});

sessionConfig parameters

Parameter	Type	Description	Required	Default value
sampleRate	number	The sampling rate. Valid values: 0 to 1. The value 0.5 specifies a 50% sampling rate.	No	1
maxDuration	number(ms)	The maximum duration of a session. Default value: 24 hours.	No	86400000
overtime	number(ms)	The timeout period of a session. Default value: one hour.	No	3600000
storage	string	The storage location of session-related data. Valid values: cookie localStorage	No	localStorage

The storage parameter stores user.id and session information:

_arms_uid: the unique user ID (user.id).
_arms_session: the semantic session information.
- sessionId: the unique session ID.
- sampled: specifies whether sampling is triggered.
- startTime: the start timestamp of the session.
- lastTime: the timestamp when the session was last active.

`${sessionId}-${sampled}-${startTime}-${lastTime}`

Example

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  sessionConfig: {
    sampleRate: 0.5, // The sampling rate is 50%.
    maxDuration: 86400000,
    overtime: 3600000,
    storage: 'cookie',
  },
});

collectors parameters

The SDK uses Collectors, such as api and static Resource, to collect page monitoring data.

Parameter	Type	Description	Required	Default value
perf	boolean \| object	Tracks the performance data of the application.	No	true
webvitals	boolean \| object	Tracks the Web Vitals data of the application.	No	true
api	boolean \| object	Tracks API requests.	No	true
staticResource	boolean \| object	Tracks static resource requests.	No	true
consoleError	boolean \| object	Tracks Console errors.	No	true
jsError	boolean \| object	Tracks JavaScript errors.	No	true
action	boolean \| object	Tracks user behavior.	No	true

Example

In the following example, the collection of user interaction data is disabled.

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  collectors: {
    action: false,
  },
});

EvaluateApi parameters

The evaluateApi function provides custom parsing for XMLHttpRequest and fetch events.

Parameter	Type	Description
options	object	The request parameters, including url, headers, and data. The parameters depend on the request method.
response	object	The response body of the request.
error	Error	The error. This parameter is optional and is available only when the request fails.

This function can be asynchronously called. Promise<IApiBaseAttr> is returned. The following table describes IApiBaseAttr.

Parameter	Type	Description	Required
name	string	The API name, which is generally a converged URL and can be up to 1,000 characters in length. Assume that the URL is `/list/123`, the name field is displayed as `/list/$id`. Important This field takes precedence over what is returned by the parseResourceName function.	No
message	string	A brief string used to describe the API, which can be up to 1,000 characters in length.	No
success	number	Indicates whether the request is successful. Valid values: 1: The request is successful. 0: The request failed. -1: The status of the request is unknown.	No
duration	number	The total duration of the API.	No
status_code	number \| string	The status code.	No
snapshots	string	The snapshot. Note A snapshot stores information about reqHeaders, params, and resHeaders. You can customize the fields that a snapshot is composed of. Snapshots are mainly used to troubleshoot exceptions. A snapshot cannot be configured as a filter condition for query or aggregation because it has no index. It can only be a string with up to 5,000 characters.	No

Example

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  evaluateApi: async (options, response, error) => {
    let respText = '';
    // Check the result of the request.
    if (response && response.text) {
      respText = await response.text();
    }
    // The returned fields will overwrite the default content. If the fields are not returned, the default content is used.
    return {
      name: 'my-custom-api',
      success: error ?  0 : 1,
      // Optional.
      snapshots: JSON.stringify({
        params: 'page=1&size=10', // The input parameter.
        response: respText.substring(0, 2000), // The returned value.
        reqHeaders: '', // The request header.
        resHeaders: '', // The response header.
      }),
      properties: {
        prop_msg: 'custom msg',
        prop_num: 1,
      },
    };
  },
});

filters parameters

The filters parameters exclude resource or exception events that do not need to be reported.

Parameter	Type	Description	Required
resource	MatchOption \| MatchOption[]	Excludes events related to static resources and API such as XMLHttpRequest or fetch that do not need to be reported.	No
exception	MatchOption \| MatchOption[]	Excludes exception events that do not need to be reported.	No

MatchOption

type MatchOption = string | RegExp | ((value: string) => boolean);

string: matches any URLs that start with the specified value. Example: https://api.aliyun.com. In this case, https://api.aliyun.com/v1/resource can be matched.
RegExp: specifies a regular expression and URL.
function: uses a function to determine whether a URL is matched. If true is returned, the URL is matched.

When the input is MatchOption[], the preceding conditions are evaluated in order, and it will be excluded if any condition is met.

Example

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  filters: {
    // Exclude exception events.
    exception: [
      'Test error', // Error messages starting with 'Test error'.
      /^ Script error\.?$/, // Error messages matching the regular expression.
      (msg) => {
        return msg.includes('example-error');
      },
    ],
    // Exclude resource or API events.
    resource: [
      'https://example.com/', // Resource starting with 'https://example.com/'
      /localhost/i,
      (url) => {
        return url.includes('example-resource');
      },
    ],
  },
});

whiteScreen parameters

The whiteScreen parameter is supported only by browsers, such as Chrome 40 and IE 9+.

Parameter	Type	Description
detectionRules	`Array<DetectionRule>`	Specify one or more rules to detect the browser based on the sequence in which the rules are configured and the delay.

DetectionRule

Parameter	Type	Required	Description	Default value
target	`String`	Yes	Specify the elements to be detected. Detection is performed in the area that matches the selector.	None
test_when	`Array`	Yes	Specify the events that can trigger the detection. Valid values: `LOAD`: Page loading is complete. `ERROR`: A global JavaScript error has occurred. `ROUTE_CHANGE`: The route history or hash character has been changed. `LEAVE`: The page is about to be closed.	None
delay	`Number`	No	Specify the period of time that the system has to wait after events except for `ERROR` and `LEAVE` occur. Then, the detection starts. The parameter is used with the test_when parameter. Unit: milliseconds.	`0`
tester	`String \| Function`	Yes	Define the detection method. Valid values: `HAS_CONTENT`: a built-in method used to check whether nodes exist and contain textContent. `SAMPLE`: a built-in method used to set sampling points and determine whether the topmost DOM element at the sampling points is included in the given element collection to calculate the white screen rate. `SCREENSHOT`: a built-in method used to take canvas screenshots and compare pixels to calculate the white screen rate. Custom detection function: uses elements as input parameters. `CustomTesterResult` or `Promise<CustomTesterResult>` values are returned. Information about the CustomTesterResult type is below the table.	None
ignoreUrlList	`Array<String>`	No	The list of page URLs that do not need to be detected.	`[]`
configOptions	`ConfigOptions`	No	Options of the `tester` parameter:	See the `ConfigOptions parameters` section.

CustomTesterResult:

type CustomTesterResult = {
  /**
   * Indicates whether content exists. `true` indicates that content exists. Otherwise, a white screen has occurred. 
   */
  hasContent: boolean;

  /**
   * Error message
   */
  message?: string;

  /**
   * Snapshot data of the exception
   */
  snapshot?: Record<string, any>;
}

ConfigOptions

ConfigOptions parameters are available only to the associated detection methods.

Parameter	Type	Associated method	Description	Default value
colorRange	`Array<Srting>`	`SCREENSHOT`	A set of colors considered as a white screen. It determines whether the current pixel block is "fully white" during pixel comparison. Format: `rgb(r, g, b)`.	`['rgb(255, 255, 255)']`
fillColor	`String`	`SCREENSHOT`	The fill color. During screenshotting, color block filling is applied to elements such as images, videos, canvases, SVGs, and iframes. The fill color cannot be any of the colors configured by the `colorRange` parameter.	`'rgba(0, 100, 200, 255)'`
horizontalOffset	`Number`	`SCREENSHOT`	The horizontal offset of the left edge of the white screen detection area relative to the left edge of the target element. It is used to filter the left menu of the target element.	`0`
verticalOffset	`Number`	`SCREENSHOT`	The vertical offset of the top edge of the white screen detection area relative to the top edge of the target element. It is used to filter the top bar of the target element.	`0`
pixels	`Number`	`SCREENSHOT`	The size of the pixel blocks used for white screen detection. The size of each block is `pixels × pixels`.	`10`
threshold	`Number`	`SCREENSHOT` `SAMPLE`	The white screen rate threshold. If the white screen rate exceeds the threshold, a white screen has occurred.	`0.8`
dpr	`Number`	`SCREENSHOT`	The scaling ratio of the snapshot image.	`0.3`
ignoreElements	`Array<Srting>`	`SCREENSHOT`	The Cascading Style Sheets (CSS) selectors of elements to be ignored when taking screenshots for detection.	`[]`
sampleMethod	`1 \| 2 \| 3`	`SAMPLE`	The sampling method. Valid values: `1`: cross sampling `2`: intersecting cross sampling `3`: rice sampling	`2`
checkPoints	`Number`	`SAMPLE`	The number of radial sampling points. For cross sampling or intersecting cross sampling, the total number of sampling points is `4 × checkPoints +1`. For rice sampling, the total number of sampling points is `8 × checkPoints +1`.	`10`
whiteBoxElements	`Array<Srting>`	`SAMPLE`	A list of CSS selectors for white screen elements. When the top-level DOM element at a sampling point matches any of these selectors, the white screen count is incremented.	`[]`
debug	`Boolean`	`SCREENSHOT` `SAMPLE`	Specifies whether to enable debug mode. In debug mode, the printed detection information is shown in the developer tools.	`false`

Examples

SCREENSHOT

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: 'SCREENSHOT',
      configOptions: {
        colorRange: ['rgb(255, 255, 255)', 'rgb(0, 0, 0)'],
        threshold: 0.9,
        pixels: 10,
        horizontalOffset: 210,
        verticalOffset: 50,
      },
    }],
  },
});

SAMPLE

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: 'SAMPLE',
      configOptions: {
        sampleMethod: 2,
        checkPoints: 10,
        threshold: 0.9,
        whiteBoxElements: ['.el-skeleton'],
      },
    }],
  },
});

CUSTOM

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  whiteScreen: {
    detectionRules: [{
      target: '#root',
      test_when: ['LOAD', 'ERROR', 'ROUTE_CHANGE', 'LEAVE'],
      delay: 5000,
      tester: async (element) => {
        // Custom detection function
        return {
          hasContent: false,
          message: 'Custom error message',
          snapshot: {
            // Custom key-value pairs
            checkPoints: 100,
            rate: 0.99,
            checkdata: '......',
          },
        };
      },
    }],
  },
});

properties parameters

Properties provided by RUM can be configured for all events.

Parameter	Type	Description	Required
[key: string]	string \| number	The key must be a string that conforms to the JSON specification. The maximum length of a key is 50 characters. The excess part of the key is truncated. If the value is a string, the maximum length is 2,000 characters. If the value is neither a string nor a number, the key-value pair is removed.	No

You can use evaluateApi, sendCustom, sendException, and sendResource to add properties to an event. The properties take effect only for the event.

Global properties and event properties are merged when they are stored. Event properties have a higher priority than global properties. If the same key is used when merging, the event properties overwrite the global properties. The number of key-value pairs cannot exceed 20 after merging. If the number exceeds 20, the pairs are sorted based on keys and the excess ones are removed.

Example

Globally configured properties are attached to all reported events.

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  properties: {
    prop_string: 'xx',
    prop_number: 2,
    // If the length of a key or value exceeds the limit, the excess part is removed.
    more_than_50_key_limit_012345678901234567890123456789: 'yy',
    more_than_2000_value_limit: new Array(2003).join('1'),
    // The following invalid key-value pairs are removed.
    prop_null: null,
    prop_undefined: undefined,
    prop_bool: true,
  },
});

Other parameters

RUM SDK allows you to configure common properties that are resolved based on IP addresses and UserAgent. Proactively configured fields have a higher priority than automatically resolved fields.

Parameter	Type	Description	Required
device	object	The device information.	No
os	object	The system and container information.	No
geo	object	The geolocation information.	No
isp	object	The carrier information.	No
net	object	The network information.	No

For more information about configuration items about the preceding fields, see the Common properties section of the "Log data" topic.

Example

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  geo: {
    country: 'your custom country info',
    city: 'your custom city info',
  },
});

SDK API

RUM SDKs provide APIs for modifying and reporting custom data and dynamically modifying SDK configurations.

getConfig

You can use the function to obtain the SDK configurations.

setConfig

You can use the function to modify the SDK configurations.

// Set the environment type.
ArmsRum.setConfig('env', 'pre');

// The following content may be overwritten.
const config = ArmsRum.getConfig();
ArmsRum.setConfig({
  ...config,
  version: '1.0.0',
  env: 'pre',
});

sendCustom

To report custom data, you must specify the type and name fields. The following table describes the parameters related to data reporting. You need to define the business semantics.

Parameter	Type	Description	Required
type	string	The type of the data.	Yes
name	string	The name of the data.	Yes
group	string	The group to which the data belongs.	No
value	number	The value of the data.	No
properties	object	The custom properties.	No

ArmsRum.sendCustom({
  // Required.
  type: 'CustomEvnetType1',
  name: 'customEventName2',
  // Optional.
  group: 'customEventGroup3',
  value: 111.11,
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});

sendException

To report custom exception data, you must specify the name and message fields.

Parameter	Type	Description	Required
name	string	The exception name.	Yes
message	string	The exception information.	Yes
file	string	The file where the occurs.	No
stack	string	The stack information about the exception.	No
line	number	The line where the exception occurs.	No
column	number	The column where the exception occurs.	No
properties	object	The custom properties.	No

ArmsRUM.sendException({
  // Required.
  name: 'customErrorName',
  message: 'custom error message',
  // Optional.
  file: 'custom exception filename',
  stack: 'custom exception error.stack',
  line: 1,
  column: 2,
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});

sendResource

To report custom resource data, you must specify the name, type, and duration fields.

Parameter	Type	Description	Required
name	string	The name of the resource.	Yes
type	string	The type of the resource. Examples: css, javascript, xmlhttprequest, fetch, api, image, and font.	Yes
duration	string	The response time.	Yes
success	number	Indicates whether the request is successful. Valid values: 1: The request is successful. 0: The request failed. -1: The status of the request is unknown.	No
method	string	The request method. Valid values:	No
status_code	number \| string	The status code.	No
message	string	The message returned.	No
url	string	The request URL.	No
trace_id	string	The trace ID.	No
properties	object	The custom properties.	No

ArmsRum.sendResource({
  // Required.
  name: 'getListByPage',
  message: 'success',
  duration: 800,
  // Optional.
  url: 'https://www.aliyun.com/data/getListByPage',
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});