Real User Monitoring (RUM) provides a range of software development kit (SDK) configuration items that you can set to meet your specific needs. This topic describes common SDK configurations for Android applications.
Startup configuration
You can configure startup class interfaces using chained calls with
AlibabaCloudRum.withServiceId(serviceId).withWorkspace(workspace).withEndpoint(endpoint).start(getApplicationContext());.You must configure the startup configuration class interface after calling the
withServiceIdmethod and before calling thestartmethod.You can configure multiple items at the same time. Configurations made after the
startmethod is called are not applied.
Set the Endpoint address
Each application must be associated with a corresponding Endpoint address.
AlibabaCloudRum withEndpoint(String endpoint)Parameter | Description | Parameter limits | Failure result |
endpoint | Endpoint address | The string length must be greater than 0 and less than 2083. | The API call fails and the SDK stops. |
Set the Workspace address
Each application must be associated with a corresponding Workspace.
AlibabaCloudRum withWorkspace(String workspace)Parameter | Description | Parameter limits | Failure result |
workspace | Workspace | The string length must be greater than 0 and less than 2083. | The API call fails and the SDK stops. |
Set a custom device ID
You can use this method to set a custom device ID. After a custom device ID is set, the SDK no longer uses the default device ID.
AlibabaCloudRum withDeviceID(String deviceID)Parameter | Description | Parameter limits | Failure result |
deviceID | Custom device ID | The string length must be greater than 0 and less than 256. The string cannot contain special characters. Only letters, digits, underscores (_), and hyphens (-) are supported. | The API call fails. The current setting is not applied. |
Set a custom app version number
If you use this method to set a custom app version number, the SDK reports this version number instead of the default one.
AlibabaCloudRum withAppVersion(String appVersion)Parameter | Description | Parameter limits | Failure result |
appVersion | Custom app version number | The string length must be greater than 0 and less than 64. | The API call fails. The current setting is not applied. |
Set the user channel ID
You can differentiate between application publishing channels.
AlibabaCloudRum withChannelID(String channelID)Parameter | Description | Parameter limits | Failure result |
channelID | Custom channel ID | The string length must be greater than 0 and less than 256. | The API call fails. The current setting is not applied. |
Set the application environment
Use this method to distinguish and specify the application environment, such as LOCAL, DAILY, or PROD.
AlibabaCloudRum withEnvironment(Env env) Parameter | Description | Parameter limits | Failure result |
env | The enumeration value of the application environment. This must be called after the | Env enumeration:
| The API call fails. The current setting is not applied. |
Custom information
Set a custom username
The SDK lets you set user-related information. This helps you associate data analytics with actual users.
void setUserName(String userName)Parameter | Description | Parameter limits | Failure result |
userName | Username identifier | The string can be null or empty. The string must be 256 characters or less. It cannot contain special characters. Only digits, letters, colons (:), spaces, forward slashes (/), underscores (_), hyphens (-), periods (.), and at signs (@) are allowed. | The API call fails. The current setting is not applied. |
Set custom user extended information
The SDK lets you set user-related information. This helps you associate data analytics with actual users.
void setUserExtraInfo(Map<String, Object> extraInfo)Parameter | Description | Parameter limits | Failure result |
extraInfo | User extended information | The Map can be null or empty. After conversion to JSON, the length must be within 7000 characters. Otherwise, the API call fails. | The API call fails. The current setting is not applied. |
Set custom global properties
After you set custom global properties, new data automatically includes these properties. This is useful for analysis related to business attributes.
void setExtraInfo(Map<String, Object> extraInfo)
void addExtraInfo(Map<String, Object> extraInfo)Parameter | Description | Parameter limits | Failure result |
extraInfo | Property information | The Map can be null or empty. After conversion to JSON, the length must be within 7000 characters. Otherwise, the API call fails. | The API call fails. The current setting is not applied. |
Calling the setExtraInfo method clears all previously set properties. To append new properties, use the addExtraInfo method.
Custom exceptions
You can call the custom exception interface and pass the corresponding parameters to collect statistics on custom exception data.
void setCustomException(Throwable exception) // Recommended. Pass the Exception or Throwable object directly.Parameter | Description | Parameter limits | Failure result |
exception | Exception object | A system-thrown or self-constructed exception object. Cannot be null. | The API call fails. The current setting is not applied. |
void setCustomException(String type, String causeBy, String errorDump)Parameter | Description | Parameter limits | Failure result |
type | Exception type (required) | The string length must be greater than 0 and less than or equal to 256. | The API call fails. The current setting is not applied. |
causeBy | Exception cause | The string can be null or empty. The string must be 512 characters or less. Longer strings are truncated. | Not applicable |
errorDump | Exception information | The string can be null or empty. The string must be 10,000 characters or less. Longer strings are truncated. | Not applicable |
Custom events
The SDK supports reporting custom events. You can call the corresponding interfaces and pass the parameters to collect statistics on custom event data.
void setCustomEvent(String eventName)Parameter | Description | Parameter limits | Failure result |
eventName | Event name (required) | The string must be 512 characters or less. Longer strings are truncated. | The API call fails. The current setting is not applied. |
void setCustomEvent(String eventName, String group)Parameter | Description | Parameter limits | Failure result |
eventName | Event name (required) | The string must be 512 characters or less. Longer strings are truncated. | The API call fails. The current setting is not applied. |
group | Event group | The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated. | Not applicable |
void setCustomEvent(String eventName, String group, String snapshots)Parameter | Description | Parameter limits | Failure result |
eventName | Event name (required) | The string must be 512 characters or less. Longer strings are truncated. | The API call fails. The current setting is not applied. |
group | Event group | The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated. | Not applicable |
snapshots | Event snapshot | The string can be null or empty. The string must be 7000 characters or less. Longer strings are truncated. | Not applicable |
void setCustomEvent(String eventName, String group, double value) Parameter | Description | Parameter limits | Failure result |
eventName | Event name (required) | The string must be 512 characters or less. Longer strings are truncated. | The API call fails. The current setting is not applied. |
group | Event group | The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated. | Not applicable |
value | Event value | Double type | Not applicable |
void setCustomEvent(String eventName, String group, Map<String, Object> attributes) Parameter | Description | Parameter limits | Failure result |
eventName | Event name (required) | The string must be 512 characters or less. Longer strings are truncated. | The API call fails. The current setting is not applied. |
group | Event group | The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated. | Not applicable |
attributes | Key-value storage information | After conversion to JSON, the length must be within 7000 characters. | Not applicable |
void setCustomEvent(String eventName, String group, String snapshots, double value)Parameter | Description | Parameter limits | Failure result |
eventName | Event name (required) | The string must be 512 characters or less. Longer strings are truncated. | The API call fails. The current setting is not applied. |
group | Event group | The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated. | Not applicable |
snapshots | Event snapshot | The string can be null or empty. The string must be 7000 characters or less. Longer strings are truncated. | Not applicable |
value | Event value | Double type | Not applicable |
void setCustomEvent(String eventName, String group, String snapshots, Map<String, Object> attributes)Parameter | Description | Parameter limits | Failure result |
eventName | Event name (required) | The string must be 512 characters or less. Longer strings are truncated. | The API call fails. The current setting is not applied. |
group | Event group | The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated. | Not applicable |
snapshots | Event snapshot | The string can be null or empty. The string must be 7000 characters or less. Longer strings are truncated. | Not applicable |
attributes | Key-value storage information | After conversion to JSON, the length must be within 7000 characters. | Not applicable |
void setCustomEvent(String eventName, String group, double value, Map<String, Object> attributes)Parameter | Description | Parameter limits | Failure result |
eventName | Event name (required) | The string must be 512 characters or less. Longer strings are truncated. | The API call fails. The current setting is not applied. |
group | Event group | The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated. | Not applicable |
value | Event value | Double type | Not applicable |
attributes | Key-value storage information | After conversion to JSON, the length must be within 7000 characters. | Not applicable |
void setCustomEvent(String eventName, String group, String snapshots, double value, Map<String, Object> attributes) Parameter | Description | Parameter limits | Failure result |
eventName | Event name (required) | The string must be 512 characters or less. Longer strings are truncated. | The API call fails. The current setting is not applied. |
group | Event group | The string can be null or empty. The string must be 256 characters or less. Longer strings are truncated. | Not applicable |
snapshots | Event snapshot | The string can be null or empty. The string must be 7000 characters or less. Longer strings are truncated. | Not applicable |
value | Event value | Double type | Not applicable |
attributes | Key-value storage information | After conversion to JSON, the length must be within 7000 characters. | Not applicable |
Custom logs
The SDK supports reporting custom log information. You can call the corresponding interfaces and pass the parameters to collect statistics on custom log data.
void setCustomLog(String content)Parameter | Description | Parameter limits | Failure result |
content | Log information (required) | The string length must be greater than 0 and less than or equal to 10,000. Longer strings are truncated. | The API call fails. The current setting is not applied. |
void setCustomLog(String content, String name) Parameter | Description | Parameter limits | Failure result |
content | Log information (required) | The string length must be greater than 0 and less than or equal to 10,000. Longer strings are truncated. | The API call fails. The current setting is not applied. |
name | Log name | The string length must be greater than 0 and less than or equal to 256. | Not applicable |
void setCustomLog(String content, String name, String snapshots)Parameter | Description | Parameter limits | Failure result |
content | Log information (required) | The string length must be greater than 0 and less than or equal to 10,000. Longer strings are truncated. | The API call fails. The current setting is not applied. |
name | Log name | The string length must be greater than 0 and less than or equal to 256. | Not applicable |
snapshots | Log snapshot | The string can be null or empty. The string must be 7000 characters or less. Longer strings are truncated. | Not applicable |
void setCustomLog(String content, String name, String snapshots, String level, Map<String, Object> attributes) Parameter | Description | Parameter limits | Failure result |
content | Log information (required) | The string length must be greater than 0 and less than or equal to 10,000. Longer strings are truncated. | The API call fails. The current setting is not applied. |
name | Log name | The string length must be greater than 0 and less than or equal to 256. | Not applicable |
snapshots | Log snapshot | The string can be null or empty. The string must be 7000 characters or less. Longer strings are truncated. | Not applicable |
level | Log level | The string length must be greater than 0 and less than or equal to 256. The default value is INFO. | Not applicable |
attributes | Additional log information | The Map can be null or empty. After conversion to JSON, the string length is shared with content. Otherwise, the API call fails. | Not applicable |
Custom resources
The SDK supports reporting data for custom network resources. You can record details for requests, such as HTTP and HTTPS requests. These details include the request status, performance metrics, and tracing information.
void reportCustomResource(String type, String url, String method, int statusCode, String errorMessage, boolean success, String provider, TraceContext traceContext, Measuring measuring)Parameter | Type | Description | Parameter limits | Failure result |
type | String | Resource type, such as | The string length must be greater than 0. | The API call fails. The current setting is not applied. |
url | String | The complete URL of the request | The string length must be greater than 0. | |
method | String | HTTP request method | The string must be 24 characters or less. Longer strings are truncated. | |
statusCode | int | HTTP response status code | HTTP status code, such as 200, 404, or 500. | |
errorMessage | String | Error message for a failed request | Can be | |
success | boolean | Whether the request was successful | true, false | |
provider | String | Service provider (SP) identifier, such as | The string must be 128 characters or less. Longer strings are truncated. Can be | |
traceContext | TraceContext | Link Connectivity | TraceContext type. Can be | |
measuring | Measuring | Resource request performance information | Measuring type. Can be |
TraceContext class
Sets trace data.
Parameter | Type | Description |
traceId | String | Custom traceId. Use the TraceIdGenerator.generateTraceId(TraceProtocol traceProtocol) method to generate it. |
spanId | String | Custom spanId. Use the TraceIdGenerator.generateSpanId(TraceProtocol traceProtocol) method to generate it. |
traceProtocol | TraceProtocol | Protocol. `TraceProtocol.W3C` or `TraceProtocol.SKYWALKING`. |
Measuring class
Contains metric data.
Parameter | Type | Description |
duration | long | Total time to load the resource, in ms |
size | long | Resource size, in bytes |
connectDuration | long | Time to establish a connection with the server, in ms |
sslDuration | long | TLS handshake duration, in ms |
dnsDuration | long | DNS parsing duration, in ms |
redirectDuration | long | Redirection duration, in ms |
firstByteDuration | long | Time to first byte (TTFB), in ms |
downloadDuration | long | Response download duration, in ms |
Example:
// (Optional) The SDK supports custom W3C and SkyWalking trace protocols. The following example shows how to generate W3C trace protocol information:
String traceId = TraceIdGenerator.generateTraceId(TraceProtocol.W3C);
String spanId = TraceIdGenerator.generateSpanId(TraceProtocol.W3C);
// (Optional) Manually save the traceId and spanId to the TraceContext for subsequent processing.
TraceContext traceContext = new TraceContext(traceId, spanId, TraceProtocol.W3C);
// (Optional) You can write the generated trace information to the request header. OkHttp and HttpURLConnection are supported. The following example uses OkHttp:
TraceHeaderWriter.setTraceHeaders(okhttp3.Request.Builder requestBuilder , TraceContext traceContext);
// (Optional) Record metric data
Measuring measuring = new Measuring(200, 100, 30, 10, 10, 0, 145, 2);
// Report the custom resource
AlibabaCloudRum.reportCustomResource("api", "https://example.com/xx", "GET", 200, "", true, "cdn", traceContext, measuring);