SDK configuration reference

SDK Configuration

User configuration

Example

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

reportConfig parameters

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 configuration

The user ID and session information is stored in the local cache of the mini program:

• _arms_uid: the unique user ID (user.id).

• _arms_session: the semantic session information.

  • sessionId: the unique session ID.

  • sampled: indicates whether sampling was 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, // Specify a 50% sampling rate. 
    maxDuration: 86400000,
    overtime: 3600000,
  },
});

longTaskConfig configuration

Example

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  longTaskConfig: {
    maxEventCount: 4, // Report stuttering data up to 4 times within a single PV.
    renderThreshold: 100, // A setData operation that takes more than 100 milliseconds is considered a stutter.
  },
});

collectors parameters

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

Example

Shut down the listener for the user Click behavior.

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

evaluateApi parameters

The evaluateApi function provides custom parsing for API events, including request and httpRequest events.

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

Example

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  evaluateApi: async (options, response, error) => {
    const respText = JSON.stringify(response);

    // 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.
      })
    }
  }
});

filters parameters

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

MatchOption

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

• string: matches any URL that starts with the specified value. For example, https://api.aliyun.com can match https://api.aliyun.com/v1/resource.

• RegExp: Tests a URL against a specified regular expression.

• 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', // Filter error messages starting with 'Test error'.
      /^Script error\.?$/, // Specify a regular expression.
      (msg) => {
        return msg.includes('example-error');
      },
    ],
    // Exclude resource or API events
    resource: [
      'https://example.com/', // Filter resources starting with 'https://example.com/'.
      /localhost/i,
      (url) => {
        return url.includes('example-resource');
      },
    ],
  },
});

properties parameters

Properties provided by RUM can be configured for all events.

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 keys of event properties are the same as those of global properties, 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 the key or value exceeds the limit, the excess part is truncated.
    more_than_50_key_limit_012345678901234567890123456789: 'yy',
    more_than_2000_value_limit: new Array(2003).join('1'),
    // The following invalid key-value pairs will be removed.
    prop_null: null,
    prop_undefined: undefined,
    prop_bool: true,
  },
});

Dynamic configuration

RUM supports dynamic delivery of data collection and reporting configurations for the SDK. The SDK dynamically loads these configurations when the application starts. These configurations then overwrite the static configurations set during SDK initialization on an item-by-item basis. This feature is implemented in two parts: the console and the SDK.

Console configuration

First, you must configure the settings in the console. Navigate to Application Settings > SDK Configuration. After you complete and test the configuration, click Confirm and Update Dynamic Configuration. This pushes the configuration to a remote OSS endpoint for storage.

SDK configuration

To support dynamic configuration delivery, add the remoteConfig field to the SDK initialization configuration. During initialization, the SDK uses this field to retrieve the remote configuration from OSS and updates features, such as probes and reporting, based on the retrieved configuration.

import ArmsRum from '@arms/rum-miniapp';

ArmsRum.init({
  pid: "your app id",
  endpoint: "your endpoint",
  remoteConfig: {
    // The region where the web application is located, for example, ap-southeast-1 for Singapore.
    region: "cn-hangzhou"
  }
});

After the SDK retrieves the remote configuration, it immediately updates the features and stores the configuration in the local cache. This allows the SDK to prioritize the locally cached configuration during the next initialization.

Note that the SDK version must be 0.0.37 or later.

Other configurations

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

For more information about configuration items about the preceding parameters, see Common attributes.

Example

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

SDK API

The 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 modify the SDK configuration.

// Set a specific key
ArmsRum.setConfig('env', 'pre');

// Overwrite the following settings
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 parameters. The following table describes the parameters related to data reporting. You need to define the business semantics.

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 parameters.

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 parameters.

ArmsRum.sendResource({

  // The following are required.
  name: 'getListByPage',
  message: 'success',
  duration: 800,
  // The following are optional.
  url: 'https://www.aliyun.com/data/getListByPage',
  properties: {
    prop_msg: 'custom msg',
    prop_num: 1,
  },
});