Android应用SDK常用配置方法详解-云监控-阿里云

用户体验监控提供了一系列SDK配置项，让您能够通过设置参数来满足额外需求。本文介绍Android应用常用的SDK配置。

启动配置

重要

启动配置类的接口，需通过链式调用方式随AlibabaCloudRum.withServiceId(serviceId).withWorkspace(workspace).withEndpoint(endpoint).start(getApplicationContext());一同配置。
启动配置类的接口需要在调用start方法之前、withServiceId方法之后进行相关配置。
可同时配置多项，在start方法之后配置无效。

设置Endpoint地址

每个应用都需要关联对应的Endpoint地址。

AlibabaCloudRum withEndpoint(String endpoint)

参数	说明	参数限制	失败结果
endpoint	Endpoint 地址	字符串长度大于0且小于2083	接口调用失败，SDK停止

设置 Workspace 地址

每个应用都需要关联对应的Workspace。

AlibabaCloudRum withWorkspace(String workspace)

参数	说明	参数限制	失败结果
workspace	工作空间	字符串长度大于0且小于2083	接口调用失败，SDK停止

设置自定义设备ID

可以通过此方法设置自定义设备ID，设置成功后，SDK将不再使用默认获取的设备ID。

AlibabaCloudRum withDeviceID(String deviceID)

参数	说明	参数限制	失败结果
deviceID	自定义的设备ID	字符串长度大于0且小于256，且不包含特殊字符，仅支持字母、数字、下划线（_）和英文半角连接号（-）。	接口调用失败，当次设置无效。

设置自定义App版本号

通过此方法设置了自定义App版本号，那么SDK将会上报此版本号，不再使用默认获取的版本号。

AlibabaCloudRum withAppVersion(String appVersion)

参数	说明	参数限制	失败结果
appVersion	自定义的App版本号	字符串长度大于0且小于64。	接口调用失败，当次设置无效。

设置用户渠道ID

区分应用发布的渠道。

AlibabaCloudRum withChannelID(String channelID)

参数	说明	参数限制	失败结果
channelID	自定义的渠道号	字符串长度大于0且小于256。	接口调用失败，当次设置无效。

设置应用环境

区分应用的环境。通过此方法可以指定应用的环境，如LOCAL、DAILY、PROD等。

AlibabaCloudRum withEnvironment(Env env)

参数

说明

参数限制

失败结果

env

应用环境的枚举值。需要在withAppID方法之后调用。

Env枚举：

LOCAL：本地
DAILY：日常
PRE：预发
GRAY：灰度
PROD（默认）：线上
NONE：无

接口调用失败，当次设置无效。

自定义信息

自定义用户名称

SDK支持设置与用户相关的信息，从而完成数据分析与实际用户相关联的需求场景。

void setUserName(String userName)

参数

说明

参数限制

失败结果

userName

用户名称标识

字符串可为null或空串。

字符串小于等于256，且不包含特殊字符，只允许数字、字母、英文半角冒号（:）、空格、正斜线（/）、下划线（_）、英文半角连接号（-）、英文半角句号（.）和@。

接口调用失败，当次设置无效。

自定义用户扩展信息

SDK支持设置与用户相关的信息，从而完成数据分析与实际用户相关联的需求场景。

void setUserExtraInfo(Map<String, Object> extraInfo)

参数

说明

参数限制

失败结果

extraInfo

用户扩展信息

Map可为空或空集。

转JSON后长度在7000字符以内，否则接口调用失败。

接口调用失败，当次设置无效。

自定义全局属性

自定义全局属性设置后，新产生的数据会自动携带该业务属性信息，用于分析与业务属性相关联的需求。

void setExtraInfo(Map<String, Object> extraInfo)

void addExtraInfo(Map<String, Object> extraInfo)

参数	说明	参数限制	失败结果
extraInfo	属性信息	Map可为空或空集。转JSON后长度在7000字符以内，否则接口调用失败。	接口调用失败，当次设置无效。

说明

调用 setExtraInfo 方法时会清空历史设置的属性信息。如您需要追加新的属性信息，建议您通过 addExtraInfo 方法。

自定义异常

调用自定义异常接口，并传入相应的参数，可完成自定义异常数据的统计功能。

void setCustomException(Throwable exception) // 推荐使用，直接将Exception或Throwable对象传入即可

参数	说明	参数限制	失败结果
exception	异常对象	系统抛出或自行构造的异常对象，非null。	接口调用失败，当次设置无效。

void setCustomException(String type, String causeBy, String errorDump)

参数	说明	参数限制	失败结果
type	异常类型（必要）	字符串长度大于0且小于等于256。	接口调用失败，当次设置无效。
causeBy	异常原因	字符串可为null或空串。字符串小于等于512，超长会截取。	不涉及
errorDump	异常信息	字符串可为null或空串。字符串小于等于10000，超长会截取。	不涉及

自定义事件

SDK支持上报自定义事件。调用相应的接口，并传入相应的参数，可完成自定义事件数据的统计功能。

void setCustomEvent(String eventName)

参数	说明	参数限制	失败结果
eventName	事件名称（必要）	字符串小于等于512，超长会截取。	接口调用失败，当次设置无效。

void setCustomEvent(String eventName, String group)

参数

说明

参数限制

失败结果

eventName

事件名称（必要）

字符串小于等于512，超长会截取。

接口调用失败，当次设置无效。

group

事件分组

字符串可为null或空串。

字符串小于等于256，超长会截取。

不涉及

void setCustomEvent(String eventName, String group, String snapshots)

参数	说明	参数限制	失败结果
eventName	事件名称（必要）	字符串小于等于512，超长会截取。	接口调用失败，当次设置无效。
group	事件分组	字符串可为null或空串。字符串小于等于256，超长会截取。	不涉及
snapshots	事件快照	字符串可为null或空串。字符串小于等于7000，超长会截取。	不涉及

void setCustomEvent(String eventName, String group, double value)

参数	说明	参数限制	失败结果
eventName	事件名称（必要）	字符串小于等于512，超长会截取。	接口调用失败，当次设置无效。
group	事件分组	字符串可为null或空串。字符串小于等于256，超长会截取。	不涉及
value	事件值	Double类型	不涉及

void setCustomEvent(String eventName, String group, Map<String, Object> attributes)

参数	说明	参数限制	失败结果
eventName	事件名称（必要）	字符串小于等于512，超长会截取。	接口调用失败，当次设置无效。
group	事件分组	字符串可为null或空串。字符串小于等于256，超长会截取。	不涉及
attributes	KV存储信息	转JSON后长度在7000字符以内。	不涉及

void setCustomEvent(String eventName, String group, String snapshots, double value)

参数	说明	参数限制	失败结果
eventName	事件名称（必要）	字符串小于等于512，超长会截取。	接口调用失败，当次设置无效。
group	事件分组	字符串可为null或空串。字符串小于等于256，超长会截取。	不涉及
snapshots	事件快照	字符串可为null或空串。字符串小于等于7000，超长截取。	不涉及
value	事件值	Double类型	不涉及

void setCustomEvent(String eventName, String group, String snapshots, Map<String, Object> attributes)

参数	说明	参数限制	失败结果
eventName	事件名称（必要）	字符串小于等于512，超长会截取。	接口调用失败，当次设置无效。
group	事件分组	字符串可为null或空串。字符串小于等于256，超长会截取。	不涉及
snapshots	事件快照	字符串可为null或空串。字符串小于等于7000，超长截取。	不涉及
attributes	KV存储信息	转JSON后长度在7000字符以内。	不涉及

void setCustomEvent(String eventName, String group, double value, Map<String, Object> attributes)

参数	说明	参数限制	失败结果
eventName	事件名称（必要）	字符串小于等于512，超长会截取。	接口调用失败，当次设置无效
group	事件分组	字符串可为null或空串。字符串小于等于256，超长会截取。	不涉及
value	事件值	Double类型	不涉及
attributes	KV存储信息	转JSON后长度在7000字符以内。	不涉及

void setCustomEvent(String eventName, String group, String snapshots, double value, Map<String, Object> attributes)

参数	说明	参数限制	失败结果
eventName	事件名称（必要）	字符串小于等于512，超长会截取。	接口调用失败，当次设置无效。
group	事件分组	字符串可为null或空串。字符串小于等于256，超长会截取。	不涉及
snapshots	事件快照	字符串可为null或空串。字符串小于等于7000，超长截取。	不涉及
value	事件值	Double类型	不涉及
attributes	KV存储信息	转JSON后长度在7000字符以内。	不涉及

自定义日志

SDK支持上报自定义日志信息。调用相应的接口，并传入相应的参数，可完成自定义日志数据的统计功能。

void setCustomLog(String content)

参数	说明	参数限制	失败结果
content	日志信息（必要）	字符串长度大于0且小于等于10000，超长会被截取。	接口调用失败，当次设置无效。

void setCustomLog(String content, String name)

参数	说明	参数限制	失败结果
content	日志信息（必要）	字符串长度大于0且小于等于10000，超长会被截取。	接口调用失败，当次设置无效。
name	日志名称	字符串长度大于0且小于等于256。	不涉及

void setCustomLog(String content, String name, String snapshots)

参数	说明	参数限制	失败结果
content	日志信息（必要）	字符串长度大于0且小于等于10000，超长会被截取。	接口调用失败，当次设置无效。
name	日志名称	字符串长度大于0且小于等于256。	不涉及
snapshots	日志快照	字符串可为null或空串。字符串小于等于7000，超长会截取。	不涉及

void setCustomLog(String content, String name, String snapshots, String level, Map<String, Object> attributes)

参数	说明	参数限制	失败结果
content	日志信息（必要）	字符串长度大于0且小于等于10000，超长会被截取。	接口调用失败，当次设置无效。
name	日志名称	字符串长度大于0且小于等于256。	不涉及
snapshots	日志快照	字符串可为null或空串。字符串小于等于7000，超长会截取。	不涉及
level	日志等级	字符串长度大于0且小于等于256，默认为INFO。	不涉及
info	日志附加信息	Map可为空或空集。转JSON后，字符串长度与content共享，否则接口调用失败。	不涉及

自定义资源

SDK支持上报自定义网络资源请求数据，可以记录 HTTP/HTTPS 等类型请求的详细信息，包括请求状态、性能指标和链路追踪信息。

void reportCustomResource(String type, String url, String method, int statusCode, String errorMessage, boolean success, String provider, TraceContext traceContext, Measuring measuring)

参数	类型	说明	参数限制	失败结果
type	String	资源类型，例如：`"js"`、`"media"`、`"api"` 等	字符串长度大于0	接口调用失败，当次设置无效
url	String	请求的完整 URL 地址	字符串长度大于0
method	String	HTTP 请求方法	字符串长度大于0且小于等于24，超长截取。
statusCode	int	HTTP 响应状态码	HTTP 状态码，如：200、404、500等。
errorMessage	String	请求失败报错信息	可为`null`
success	boolean	请求是否成功	true、false
provider	String	服务提供商标识，如：`"CDN"`	字符串长度大于0且小于等于128，超长截取。可为 `null` 。
traceContext	TraceContext	链路打通信息	TraceContext类型，可为 `null` 。
measuring	Measuring	资源请求性能信息	Measuring类型，可为 `null` 。

TraceContext 类

用户可设置trace数据

参数	类型	说明
traceId	String	自定义traceId，可以使用 TraceIdGenerator.generateTraceId(TraceProtocol traceProtocol) 方法生成
spanId	String	自定义spanId，可以使用 TraceIdGenerator.generateSpanId(TraceProtocol traceProtocol) 方法生成
traceProtocol	TraceProtocol	协议，TraceProtocol.W3C 或 TraceProtocol.SKYWALKING

Measuring 类

指标数据

参数	类型	说明
duration	long	资源加载的全部耗时，单位ms
size	long	资源大小，单位Byte
connectDuration	long	与服务器建连耗时，单位ms
sslDuration	long	TLS握手耗时，单位ms
dnsDuration	long	DNS解析耗时，单位ms
redirectDuration	long	重定向耗时，单位ms
firstByteDuration	long	首包耗时，单位ms
downloadDuration	long	下载响应耗时，单位ms

使用示例：

// (可选) SDK 当前支持 W3C 和 SkyWalking trace协议的自定义，以下为生成 W3C trace 协议信息的示例：
String traceId = TraceIdGenerator.generateTraceId(TraceProtocol.W3C);
String spanId = TraceIdGenerator.generateSpanId(TraceProtocol.W3C);

// (可选) 您需要手动把 traceId 和 spanId 存入到 TraceContext 中，便于后续处理。
TraceContext traceContext = new TraceContext(traceId, spanId, TraceProtocol.W3C);

// (可选) 支持将生成的trace信息写入请求头，支持 OkHttp、HttpURLConnection，以OkHttp为例：
TraceHeaderWriter.setTraceHeaders(okhttp3.Request.Builder requestBuilder , TraceContext traceContext);

// (可选) 记录指标数据
Measuring measuring = new Measuring(200, 100, 30, 10, 10, 0, 145, 2);

// 上报自定义资源
AlibabaCloudRum.reportCustomResource("api", "https://example.com/xx", "GET", 200, "", true, "cdn", traceContext, measuring);