Integrate web applications into RUM - Application Real-Time Monitoring Service

The Real User Monitoring (RUM) sub-service of Application Real-Time Monitoring Service (ARMS) monitors web and HTML5 applications by using JavaScript or npm packages to collect performance metrics and track exceptions. This helps you improve the user experience of your applications.

Important

RUM has been available for commercial use since 00:00:00 (UTC +8) on June 24, 2024. For more information, see Billing. To obtain technical support, join the DingTalk group chat (ID: 67370002064).

Add the app

Log on to the ARMS console.
In the left-side navigation pane, choose User Experience Monitoring > Application List. In the top navigation bar, select a region.
On the Applications page, click Add Application.
In the Create Application panel, click Web & H5.
In the Web & H5 panel, enter an application name and description, and then click Create.
Note
The name must be unique.
Then, an address to which monitoring data is reported (endpoint) and an application ID (pid) are automatically generated in the STEP2 section.
In the STEP2 section, select a method and install the OpenRUM SDK.
Synchronous loading through CDN
Copy the following code and paste it to the first line in the <body> of the HTML page.
Note
Replace the pid and endpoint parameters in the following code with the address and application ID.
```
<script>
  window.__rum = {
    pid: "your app id",
    endpoint: "your endpoint"
  };
</script>
<script type="text/javascript" src="https://sdk.rum.aliyuncs.com/v2/browser-sdk.js " crossorigin></script>
```
Asynchronous loading through CDN
Copy the following code and paste it to the first line in the <body> of the HTML page.
Note
Replace the pid and endpoint parameters in the following code with the address and application ID.
```
<script>
  !(function(c,b,d,a){c[a]||(c[a]={});c[a]={
    pid: "your app id",
    endpoint: "your endpoint"
  };
  with(b)with(body)with(insertBefore(createElement("script"),firstChild))setAttribute("crossorigin","",src=d)
  })(window, document, "https://sdk.rum.aliyuncs.com/v2/browser-sdk.js ", "__rum");
</script>
```
npm package
1. Introduce the npm package.
```
npm install @arms/rum-browser --save
```
2. Initialize the application.
  Note
  Replace the pid and endpoint parameters in the following code with the address and application ID.
```
import ArmsRum from '@arms/rum-browser';
ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint"
});
```
Usage notes:
- Asynchronous loading: It is also known as non-blocking loading. The browser continues to process subsequent pages regardless of whether JavaScript loading is completed. We recommend that you use this method if you require high page performance.
  Important
  When you use asynchronous loading, ARMS cannot capture JavaScript errors or resource loading errors before the OpenRUM SDK is initialized.
- Synchronous loading: It is also known as blocking loading. The browser does not continue to process subsequent pages until the JavaScript loading is completed. We recommend that you use synchronous loading if you need to continuously capture JavaScript errors and resource loading errors.
- npm package: npm packages can be used to reduce the number of scripts loaded on a page, control the traffic flow, and select RUM as a separate module for subsequent processing.

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	-	The environment of the mini program. 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 OpenRUM SDK.	No	-
collectors	object	The Collector settings.	No	-
beforeReport	function	The function that is called before reporting data to modify or block the reported data.	No	noop
reportConfig	object	The data reporting settings.	No	{ flushTime: 3000, maxEventCount: 50 }
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	-
whiteScreen	object	The function used to configure white screen monitoring. For more information, see the WhiteScreen configuration section.	No	-

User parameters

Parameter	Type	Description	Required	Default value
id	string	The user ID, which is generated by the OpenRUM 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: getYourUserName(),
    tags: getYourTags(),
  }
});

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

Note

Overwriting the user ID affects the UV data.

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

Collectors parameters

OpenRUM 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 describes IApiBaseAttr.

Field	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 to describe the API, which can be up to 1,000 characters in length.	No
success	number	Indicates whether the request is successful. 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 endpint",
  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,
      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.
      })
    }
  }
});

whiteScreen parameters

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

Parameter	Type	Description	Default value
detectionRules	Array	Specify one or more rules to detect the browser based on the sequence in which the rules are configured and the delay.	None
target	String	Specify the elements to be detected. Detection is performed in the area that matches the selector.	None
test_when	Array	Specify the events that can trigger the detection. `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	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	Define the detection method. Valid values: `HAS_CONTENT`: a built-in method used to check whether nodes exist and contain textContent. `SCREENSHOT`: a built-in method used to obtain the white screen rate through canvas screenshots. Custom detection function: uses elements as input parameters. Boolean values are returned. A value of false indicates that a white screen is detected. A value of true indicates that a white screen is not detected.	None
configOptions	Object	Options of the tester parameter: `colorRange`: specifies the range of colors to be detected. The default value (255, 255, 255) indicates the white color. `fillColor`: specifies the color to be filled. By default, elements such as images, videos, canvas, SVG files, and iframe, are filled with color blocks when screenshots are taken. The color cannot be any color configured by the colorRange field. `horizontalOffset`: specifies the horizontal offset from the target area when screenshots are taken. `verticalOffset`: specifies the vertical offset from the target area when screenshots are taken. `pixels`: specifies the number of pixels to be randomly sampled in screenshots. Default value: 10 x 10. `threshold`: specifies a threshold value. If the number of pixels is greater than the value, a white screen is detected. `dpr`: specifies the screenshot ratio. `debug`: specifies whether to enable the debug mode. In debug mode, the printed detection information is shown in the developer tools. `ignoreUrlList`: lists the URLs to be ignored. If the page URL exists in the list, screenshots are not taken. `ignoreElements`: lists the elements to be ignored. If a screenshot contains one of these elements, no detection is performed.	Default values of the SCREENSHOT method: colorRange: ['rgb(255, 255, 255)'] fillColor: 'rgba(0, 100, 200, 255)' horizontalOffset: 0 verticalOffset: 0 pixels: 10 threshold: 0.8 dpr: 0.3 debug: false ignoreUrlList: [] ignoreElements: []

Example

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpint",
  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,
      }
    }],
  }
});

SDK API

OpenRUM SDK provides 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.

Field	Type	Description	Required	Default value
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	-

ArmsRum.sendCustom({
  type: 'CustomEvnetType1',
  name: 'customEventName2',
  group: 'customEventGroup3',
  value: 111.11
});

sendException

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

Field	Type	Description	Required	Default value
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	-

ArmsRum.sendCustom({
  // Required.
  name: 'customErrorName',
  message: 'custom error message',
  // Optional.
  file: 'custom exception filename',
  stack: 'custom exception error.stack',
  line: 1,
  column: 2
});

sendResource

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

Field	Type	Description	Required	Default value
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. 1: The request is successful. 0: The request failed. -1: The status of the request is unknown.	No	-
method	string	The method of the request.	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	-

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

Add the app

Synchronous loading through CDN

Asynchronous loading through CDN

npm package

SDK parameters

User parameters

Example

reportConfig parameters

Example

Collectors parameters

Example

EvaluateApi parameters

Example

whiteScreen parameters

Example

SDK API

getConfig

setConfig

sendCustom

sendException

sendResource