ARMS 用户体验监控提供一系列SDK配置项,让您能够通过设置参数来满足额外需求。本文介绍小程序应用常用的 SDK 配置。
SDK 配置
参数 | 类型 | 描述 | 是否必填 | 默认值 |
参数 | 类型 | 描述 | 是否必填 | 默认值 |
pid | String | 应用ID | 是 | - |
endpoint | String | 上报地址 | 是 | - |
env | - | 应用环境:
| 否 | prod |
version | String | 应用版本 | 否 | - |
user | Object | User配置 | 否 | user.id由SDK默认生成 |
collectors | Object | 各Collector(采集器)配置 | 否 | - |
beforeReport | Function | 上报数据之前执行beforeReport,可以修改或阻止数据上报。 | 否 | noop |
reportConfig | Object | 上报配置 | 否 | { flushTime: 3000, maxEventCount: 20 } |
sessionConfig | Object | Session的采样、超时时间等配置,详细说明请参见sessionConfig 配置。 | 否 | - |
parseViewName | Function | 解析视图名称(view.name),入参为当前页面的URL。 | 否 | - |
parseResourceName | Function | 解析资源名称(resource.name),入参为当前资源的URL。 | 否 | - |
evaluateApi | Function | 自定义解析API事件,详细说明请参见evaluateApi配置。 | 否 | - |
filters | Object | 事件过滤配置,详情说明请参见filters 配置。 | 否 | - |
properties | Object | 自定义属性,可对所有事件生效,详情说明请参见properties 配置。 | 否 | - |
user 配置
参数 | 类型 | 描述 | 是否必填 | 默认值 |
参数 | 类型 | 描述 | 是否必填 | 默认值 |
id | String | 用户ID,不可修改。 | 否 | 由SDK默认生成 |
tags | String | 标签 | 否 | - |
name | String | 名称 | 否 | - |
示例
如果需要关联业务自有账号体系,建议使用user.name或者user.tags ,而不是修改user.id。强制覆盖SDK生成的user.id ,会对影响UV的计算。
ArmsRum.init({
pid: "your app id",
endpoint: "your endpoint",
user: {
name: getYourUserName(),
tags: getYourTags(),
}
});
reportConfig 配置
参数 | 类型 | 描述 | 是否必填 | 默认值 |
参数 | 类型 | 描述 | 是否必填 | 默认值 |
flushTime | Number | 上报时间间隔 取值范围:[0, 10000] | 否 | 3000 |
maxEventCount | Number | 一次上报最大数量 取值范围:[1, 100] | 否 | 20 |
示例
使用业务自有账号体系强制覆盖SDK生成的user.id,会对影响UV的计算。
ArmsRum.init({
pid: "your app id",
endpoint: "your endpint",
reportConfig: {
flushTime: 0, // 立即上报
maxEventCount: 50 // 一次最多上报数量
}
});
sessionConfig 配置
参数 | 类型 | 描述 | 是否必填 | 默认值 |
参数 | 类型 | 描述 | 是否必填 | 默认值 |
sampleRate | Number | Session采样率:[0, 1] 0.5即50%采样率。 | 否 | 1 |
maxDuration | Number | Session最大持续时间,默认24小时。单位:毫秒。 | 否 | 86400000 |
overtime | Number | Session超时时间,默认半小时。单位:毫秒。 | 否 | 1800000 |
小程序本地缓存中存储了user.id和session信息 :
_arms_uid:唯一标识用户ID,对应user.id。
_arms_session:具备语义化的Session信息。
sessionId:Session唯一标识。
sampled:是否命中采样。
startTime:Session的开始时间戳。
lastTime:Session最后一次活跃时间戳。
`${sessionId}-${sampled}-${startTime}-${lastTime}`
示例
ArmsRum.init({
pid: "your app id",
endpoint: "your endpint",
sessionConfig: {
sampleRate: 0.5, // 采样率50%
maxDuration: 86400000,
overtime: 3600000,
},
});
Collectors配置
Collector是RUM SDK用于收集页面监控数据的最小单元。目前RUM SDK内置了api、static Resource等丰富的采集器。
参数 | 类型 | 描述 | 是否必填 | 默认值 |
参数 | 类型 | 描述 | 是否必填 | 默认值 |
api | Boolean | Object | 监听API请求。 | 否 | true |
jsError | Boolean | Object | 监听JS错误。 | 否 | true |
consoleError | Boolean | Object | 监听console.error抛出的错误。 | 否 | true |
action | Boolean | Object | 监听用户行为。 | 否 | true |
示例
关闭监听用户Click行为。
ArmsRum.init({
pid: "your app id",
endpoint: "your endpoint",
collectors: {
action: false,
}
});
evaluateApi配置
evaluateApi提供对API(request或httpRequest)事件的自定义解析。以下为SDK传入的三个参数:
参数 | 类型 | 描述 |
参数 | 类型 | 描述 |
options | Object | 请求参数,包括url、headers、data等,根据具体请求方式有差异。 |
response | Object | 请求响应体。 |
error | Error | 可选参数,只有在请求失败才会传入。 |
该函数支持异步函数,返回Promise<IApiBaseAttr>,IApiBaseAttr的定义如下:
参数 | 类型 | 描述 | 是否必填 |
参数 | 类型 | 描述 | 是否必填 |
name | String | API名称,一般是对URL的收敛,最大1000字符。 例如URL为 该字段的优先级高于parseResourceName返回的内容。 | 否 |
message | String | API信息,一个简短的描述API概况字符串,最大1000字符。 | 否 |
success | Number | 请求成功状态:
| 否 |
duration | Number | API总耗时。 | 否 |
status_code | Number | String | API状态码。 | 否 |
snapshots | String | API快照。 可用于存储reqHeaders、params、resHeaders等,具体字段组成方式可自行决定。该字段主要用于排查接口异常的原因,没有索引,不能根据该字段进行筛选或聚合,只接受字符串类型,最大5000字符。 | 否 |
示例
ArmsRum.init({
pid: "your app id",
endpoint: "your endpint",
evaluateApi: async (options, response, error) => {
const respText = JSON.stringify(response);
// 返回的字段会覆盖默认内容,不返回的字段会依然使用SDK自定生成内容
return {
name: 'my-custom-api',
success: error ? 0 : 1,
snapshots: JSON.stringify({
params: 'page=1&size=10', // 请求入参
response: respText.substring(0, 2000), // 返回值
reqHeaders: '', // 请求头
resHeaders: '' // 响应头
})
}
}
});
filters 配置
filters 用于过滤无需上报的事件,目前支持 resource 和 exception 两种事件。
参数 | 类型 | 描述 | 是否必填 |
参数 | 类型 | 描述 | 是否必填 |
resource | MatchOption | MatchOption[] | 对采集到的资源事件进行过滤,包括静态资源和API(XMLHttpRequest/fetch)。 | 否 |
exception | MatchOption | MatchOption[] | 对采集到的异常事件进行过滤。 | 否 |
MatchOption
type MatchOption = string | RegExp | ((value: string) => boolean);
string:匹配任何以该值开头的URL,如
https://api.aliyun.com
可以匹配https://api.aliyun.com/v1/resource
。RegExp:使用提供的RegExp和URL执行test。
function:以URL作为参数进行计算,返回true表示匹配。
当传入为 MatchOption[] 时,条件顺序执行,有一项满足就会被过滤。
示例
ArmsRum.init({
pid: "your app id",
endpoint: "your endpoint",
filters: {
// 过滤异常
exception: [
'Test error', // 以'Test error'开头的error.message
/^Script error\.?$/, // 正则表达式匹配 error.message
(msg) => {
return msg.includes('example-error');
},
],
// 过滤资源或API
resource: [
'https://example.com/', // 以'https://example.com/'开头的resource
/localhost/i,
(url) => {
return url.includes('example-resource');
},
],
},
});
properties 配置
Properties是RUM提供的自定义属性,可为任何上报事件配置该属性。
参数 | 类型 | 描述 | 是否必填 |
参数 | 类型 | 描述 | 是否必填 |
[key: string] | String | Number |
| 否 |
使用evaluateApi、sendCustom、sendException、sendResource等可以单独为某个事件增加properties,仅对单个事件生效。
全局properties和事件properties在存储时会进行合并。事件properties优先级高于全局properties,合并时相同key的事件properties会覆盖全局properties。合并后properties键值对数量不可超过20对,超出会基于key进行排序后移除。
示例
全局配置properties时,所有上报的事件都会拥有。
ArmsRum.init({
pid: "your app id",
endpoint: "your endpoint",
properties: {
prop_string: 'xx',
prop_number: 2,
// key 和 value 超出范围会被截断
more_than_50_key_limit_012345678901234567890123456789: 'yy',
more_than_2000_value_limit: new Array(2003).join('1'),
// 以下不符合要求的键值对会被移除
prop_null: null,
prop_undefined: undefined,
prop_bool: true,
},
});
其他配置
RUM SDK支持配置基于IP和UserAgent等解析所得到的公共属性,主动配置字段优先级高于自动解析。
参数 | 类型 | 描述 | 是否必填 |
参数 | 类型 | 描述 | 是否必填 |
device | Object | 设备信息 | 否 |
os | Object | 系统、容器信息 | 否 |
geo | Object | 行政地理信息 | 否 |
isp | Object | 运营商信息 | 否 |
net | Object | 网络信息 | 否 |
以上字段具体可配置项请参考日志数据说明中公共属性部分。
示例
ArmsRum.init({
pid: "your app id",
endpoint: "your endpoint",
geo: {
country: 'your custom cuntry info',
city: 'your custom city info',
},
});
SDK API
RUM SDK开放API,用于修改上报自定义数据,动态修改SDK配置等。
getConfig
获取SDK配置。
setConfig
修改SDK配置。
// 指定 key 设置
ArmsRum.setConfig('env', 'pre');
// 覆盖设置
const config = ArmsRum.getConfig();
ArmsRum.setConfig({
...config,
version: '1.0.0',
env: 'pre',
});
sendCustom
上报自定义数据,必须包含type和name两个属性,否则无法上报。属性的具体业务意义可参考下表,实际使用需要自行定义业务语义。
参数 | 类型 | 描述 | 是否必填 | 默认值 |
参数 | 类型 | 描述 | 是否必填 | 默认值 |
type | String | 类型 | 是 | - |
name | String | 名称 | 是 | - |
group | String | 分组 | 否 | - |
value | Number | 值 | 否 | - |
ArmsRum.sendCustom({
type: 'CustomEvnetType1',
name: 'customEventName2',
group: 'customEventGroup3',
value: 111.11
});
sendException
上报自定义异常数据,必须包含name和message两个属性,否则无法上报。
参数 | 类型 | 描述 | 是否必填 | 默认值 |
参数 | 类型 | 描述 | 是否必填 | 默认值 |
name | String | 异常名称 | 是 | - |
message | String | 异常信息 | 是 | - |
file | String | 异常发生文件 | 否 | - |
stack | String | 异常堆栈信息 | 否 | - |
line | Number | 异常发生的行数 | 否 | - |
column | Number | 异常发生的列数 | 否 | - |
ArmsRUM.sendException({
// 必选
name: 'customErrorName',
message: 'custom error message',
// 可选
file: 'custom exception filename',
stack: 'custom exception error.stack',
line: 1,
column: 2
});
sendResource
上报自定义资源,必须包含name、type和duration三个属性,否则无法上报。
参数 | 类型 | 描述 | 是否必填 | 默认值 |
参数 | 类型 | 描述 | 是否必填 | 默认值 |
name | String | 资源名。 | 是 | - |
type | String | 资源类型,例如:script、api、image、other。 | 是 | - |
duration | String | 请求耗时。 | 是 | - |
success | Number | 请求成功状态:
| 否 | - |
method | String | 请求方法。 | 否 | - |
status_code | Number | String | 请求状态码。 | 否 | - |
message | String | 请求消息。 | 否 | - |
url | String | 请求地址。 | 否 | - |
trace_id | String | 链路追踪ID。 | 否 | - |
ArmsRum.sendResource({
// 必选
name: 'getListByPage',
message: 'success',
duration: 800,
// 可选
url: 'https://www.aliyun.com/data/getListByPage',
});
- 本页导读 (1)
- SDK 配置
- user 配置
- 示例
- reportConfig 配置
- 示例
- sessionConfig 配置
- 示例
- Collectors配置
- 示例
- evaluateApi配置
- 示例
- filters 配置
- MatchOption
- 示例
- properties 配置
- 示例
- 其他配置
- 示例
- SDK API
- getConfig
- setConfig
- sendCustom
- sendException
- sendResource