Android RUM SDK 数据收集

概述

FlashCat Android RUM SDK 默认收集所有 RUM 事件的多个指标和属性。您还可以添加自定义属性以扩展默认收集的数据集。

应用启动

FlashCat 从应用启动收集以下指标:

指标	描述
cold_start_duration	冷启动持续时间:从应用进程创建到首个 Activity 渲染完成的时间。
warm_start_duration	温启动持续时间:应用进程已存在,从 Activity 开始到渲染完成的时间。
hot_start_duration	热启动持续时间:应用和 Activity 都在内存中,从 Activity 恢复到渲染完成的时间。
activity_start_duration	Activity 启动持续时间:从 `onCreate` 到首帧绘制完成的时间。
is_pre_warmed	布尔值,指示应用是否通过预热启动(Android 11+)。

启动类型说明:

冷启动:应用首次启动或进程被终止后启动。需要加载所有资源并初始化应用状态。

温启动:应用进程在内存中,但 Activity 需要重新创建。

热启动:应用和 Activity 都在内存中,只需将 Activity 带回前台。

Views 监控与应用生命周期

View 代表用户在应用中看到的唯一屏幕。每个 View 开始时会创建一个新的 RUM 事件,并在 View 的整个生命周期内更新该事件。View 会收集其生命周期内发生的所有资源、操作、错误和长任务的相关信息。

在 Android 中,Activities 和 Fragments 被视为 View。默认情况下,SDK 使用以下策略自动追踪 View:

ActivityViewTrackingStrategy:基于 Activity 生命周期追踪每个 Activity 为一个 View。

FragmentViewTrackingStrategy:基于 Fragment 生命周期追踪每个 Fragment 为一个 View。

MixedViewTrackingStrategy:同时追踪 Activity 和 Fragment。

NavigationViewTrackingStrategy:适用于 Jetpack Navigation 组件的追踪策略。

您也可以通过手动调用 RumMonitor.startView() 和 RumMonitor.stopView() 来自定义 View 追踪。

默认属性

FlashCat RUM SDK 为所有事件附加以下默认属性。这些属性可帮助您了解用户设备、网络状态和应用上下文。

通用核心属性

属性名	类型	描述
`application.id`	string	FlashCat 应用 ID。
`application.name`	string	应用包名(例如 `com.example.app`)。
`application.version`	string	应用版本名称。
`application.build`	string	应用构建版本号。
`session.id`	string	唯一会话 ID,用于将用户旅程中的事件分组。
`session.type`	string	会话类型:`user`。
`view.id`	string	为每个 View 生成的唯一 ID。
`view.url`	string	View 的规范化 URL(Activity 或 Fragment 的类名)。
`view.name`	string	可自定义的 View 名称。
`env`	string	应用的环境名称(例如 `prod`、`dev`)。
`service`	string	服务名称,用于区分应用的不同模块或微服务。
`version`	string	应用版本。
`sdk_version`	string	FlashCat SDK 版本。
`date`	number	事件发生的时间戳(epoch 毫秒)。
`type`	string	事件类型(例如 `view`、`resource`、`action`、`error`、`long_task`)。

设备属性

以下属性与设备相关,在所有 RUM 事件中自动收集:

属性名	类型	描述
`device.type`	string	设备类型,如 `mobile`、`tablet`、`tv` 等。
`device.name`	string	设备商业名称(例如 `Samsung Galaxy S21`)。
`device.model`	string	设备型号(例如 `SM-G991B`)。
`device.brand`	string	设备品牌(例如 `Samsung`)。
`device.architecture`	string	设备架构(例如 `arm64-v8a`)。
`device.marketing_name`	string	设备的市场营销名称。

连接性属性

以下网络相关属性在所有 RUM 事件中自动收集:

属性名	类型	描述
`connectivity.status`	string	设备网络可达性状态(`connected`、`not_connected`、`maybe`)。
`connectivity.interfaces`	array	可用网络接口列表(例如 `wifi`、`cellular`、`ethernet`)。
`connectivity.cellular.technology`	string	蜂窝网络技术类型(例如 `LTE`、`5G`)。
`connectivity.cellular.carrier_name`	string	运营商名称(例如 `中国移动`)。

操作系统属性

以下操作系统相关属性在所有 RUM 事件中自动收集:

属性名	类型	描述
`os.name`	string	操作系统名称(例如 `Android`)。
`os.version`	string	操作系统版本(例如 `13`)。
`os.version_major`	string	操作系统主版本号(例如 `13`)。
`os.build`	string	系统构建号(例如 `TQ2A.230505.002`)。

地理位置属性

FlashCat RUM 可以从用户的 IP 地址推断出地理位置信息:

属性名	类型	描述
`geo.country`	string	国家名称。
`geo.country_iso`	string	国家的 ISO 代码。
`geo.city`	string	城市名称。

注意: 地理位置信息由 FlashCat 后端根据客户端 IP 地址推断,不会在客户端收集精确的 GPS 位置。

全局用户属性

您可以通过 setUser() API 设置用户信息,这些信息会被附加到所有 RUM 事件中:

属性名	类型	描述
`usr.id`	string	用户的唯一标识符。
`usr.name`	string	用户的友好名称。
`usr.email`	string	用户的电子邮件地址。

您还可以添加自定义用户属性,例如 usr.plan、usr.role 等。

事件特定属性

除了默认属性外,不同类型的 RUM 事件还会收集特定的指标和属性。

Session 属性

属性名	类型	描述
`session.id`	string	唯一会话 ID。
`session.type`	string	会话类型:`user`。
`session.has_replay`	bool	会话是否包含会话重放录制。
`session.is_active`	bool	会话是否处于活动状态。

View 属性

View 事件包含以下特定属性和性能指标:

属性名	类型	描述
`view.id`	string	每个 View 的唯一 ID。
`view.name`	string	View 的自定义名称。
`view.url`	string	View 的 URL(Activity 或 Fragment 类名)。
`view.time_spent`	number(ns)	用户在此 View 上花费的时间。
`view.loading_time`	number(ns)	View 加载完成所需的时间。
`view.loading_type`	string	View 加载类型:`initial_load`、`activity_display`、`fragment_display`。
`view.first_contentful_paint`	number(ns)	首次内容绘制时间(仅适用于 API 29+)。
`view.action.count`	number	View 中收集的所有操作的数量。
`view.resource.count`	number	View 中收集的所有资源的数量。
`view.error.count`	number	View 中收集的所有错误的数量。
`view.long_task.count`	number	View 中收集的所有长任务的数量。
`view.crash.count`	number	View 中收集的所有崩溃的数量。
`view.is_active`	bool	View 是否仍处于活动状态。

Resource 属性

Resource 事件表示应用中的网络请求。收集的属性包括:

属性名	类型	描述
`resource.id`	string	资源的唯一标识符。
`resource.type`	string	资源类型(例如 `xhr`、`fetch`、`image`、`css`、`js`、`font`、`media`、`other`)。
`resource.url`	string	资源的 URL。
`resource.method`	string	HTTP 方法(例如 `GET`、`POST`)。
`resource.status_code`	number	HTTP 响应状态码。
`resource.duration`	number(ns)	加载资源所花费的总时间。
`resource.size`	number	资源大小(字节)。
`resource.dns.duration`	number(ns)	DNS 解析时间(`domainLookupEnd - domainLookupStart`)。
`resource.connect.duration`	number(ns)	建立连接的时间(`connectEnd - connectStart`)。
`resource.ssl.duration`	number(ns)	TLS 握手时间(`connectEnd - secureConnectionStart`),仅适用于 HTTPS。
`resource.first_byte.duration`	number(ns)	等待首字节响应的时间(`responseStart - requestStart`)。
`resource.download.duration`	number(ns)	下载响应的时间(`responseEnd - responseStart`)。
`resource.redirect.duration`	number(ns)	后续 HTTP 重定向所花费的时间(`redirectEnd - redirectStart`)。
`resource.provider.name`	string	资源提供商名称,默认为 `unknown`。
`resource.provider.domain`	string	资源提供商域名。
`resource.provider.type`	string	资源提供商类型(例如 `first-party`、`cdn`、`ad`、`analytics`)。

Error 属性

前端错误通过 RUM 收集,错误消息和堆栈跟踪(如果可用)会被包含在内:

属性名	类型	描述
`error.source`	string	错误来源(例如 `webview`、`logger`、`network`、`source`、`console`)。
`error.type`	string	错误类型或错误代码。
`error.message`	string	简洁、人类可读的单行错误消息。
`error.stack`	string	堆栈跟踪或错误的补充信息。
`error.issue_id`	string	错误问题的唯一标识符。
`error.category`	string	错误的高级分类,可能的值:`ANR`(应用无响应)、`Exception`(异常)。
`error.file`	string	发生错误的文件名(用于错误追踪问题)。
`error.line`	number	发生错误的行号。
`error.is_crash`	bool	指示该错误是否导致应用崩溃。

网络错误

网络错误包含有关失败的 HTTP 请求的信息,并收集以下属性:

属性名	类型	描述
`error.resource.status_code`	number	HTTP 响应状态码。
`error.resource.method`	string	HTTP 方法(例如 `POST`、`GET`)。
`error.resource.url`	string	资源 URL。
`error.resource.provider.name`	string	资源提供商名称,默认为 `unknown`。
`error.resource.provider.domain`	string	资源提供商域名。
`error.resource.provider.type`	string	资源提供商类型(例如 `first-party`、`cdn`、`ad`、`analytics`)。

Action 计时属性

Action 代表用户与应用的交互(例如点击、滑动、滚动)。

属性名	类型	描述
`action.loading_time`	number(ns)	操作的加载时间。
`action.long_task.count`	number	此操作收集的所有长任务数量。
`action.resource.count`	number	此操作收集的所有资源数量。
`action.error.count`	number	此操作收集的所有错误数量。

Action 属性

属性名	类型	描述
`action.id`	string	用户操作的 UUID。
`action.type`	string	用户操作类型(例如 `tap`、`scroll`、`swipe`、`application_start`)。
`action.name`	string	用户操作的名称。
`action.target.name`	string	用户交互的元素,仅适用于自动收集的操作。

数据存储

在数据上传到 FlashCat 之前,会以明文形式存储在应用的缓存目录中。此缓存文件夹受 Android 应用沙箱保护,这意味着在大多数设备上,其他应用无法读取这些数据。但是,如果移动设备已 root 或有人篡改 Linux 内核,存储的数据可能会变得可读。

存储位置: /data/data/<package_name>/cache/com.flashcat.rum/

注意: 敏感数据不应包含在 RUM 事件中,或者应在发送前通过 beforeSend 回调进行混淆或过滤。

数据上传

FlashCat RUM Android SDK 在保证数据传输的同时,会考虑用户的带宽影响。SDK 以批次方式上传事件,具体流程如下:

批处理机制

事件收集时:
FlashCat SDK 将未压缩的事件追加到批次文件中(使用 TLV 编码格式,即 Tag-Length-Value)。

上传时(当批次被视为"关闭"时):

读取批次文件并提取事件

对 RUM 事件进行去重优化(删除冗余的 View 事件;其他追踪不进行优化)

构建特定于每个追踪的有效载荷

压缩有效载荷并发送

上传触发条件

批次在以下情况下会被上传:

批次文件大小达到阈值(例如 4MB)

批次中的事件数量达到阈值

应用切换到后台

定期上传(例如每 5 秒)

上传策略

网络可用时: 优先通过 WiFi 上传,移动网络也支持上传。

电量充足时: 确保不会过度消耗设备电量。

失败重试: 如果上传失败,批次会保留在本地,直到成功发送。

数据压缩

上传前,FlashCat SDK 会对批次数据进行 gzip 压缩,以减少网络流量和上传时间。

Direct Boot 模式支持

如果您的应用支持 Direct Boot 模式(在设备解锁前启动),请注意:在设备解锁前捕获的数据将不会被记录,因为此时凭据加密存储尚不可用。

FlashCat SDK 会在设备解锁后开始收集数据。如果您需要在 Direct Boot 模式下收集数据,请确保使用设备加密存储而非凭据加密存储。

数据收集

概述#

应用启动#

Views 监控与应用生命周期#

默认属性#

通用核心属性#

设备属性#

连接性属性#

操作系统属性#

地理位置属性#

全局用户属性#

事件特定属性#

Session 属性#

View 属性#

Resource 属性#

Error 属性#

网络错误#

Action 计时属性#

Action 属性#

数据存储#

数据上传#

批处理机制#

上传触发条件#

上传策略#

数据压缩#

Direct Boot 模式支持#

更多阅读#

概述