RUM 配置¶
RUM 初始化配置¶
| 字段 | 类型 | 必须 | 说明 |
|---|---|---|---|
| androidAppId | String | Android 必填 | Android 平台的 app_id,在应用访问监测控制台申请;仅 Android 运行时读取 |
| iOSAppId | String | iOS 必填 | iOS 平台的 app_id,在应用访问监测控制台申请;仅 iOS 运行时读取 |
| sampleRate | double | 否 | 采样率,取值范围 [0,1],0 表示不采集,1 表示全采集,默认值为 1。作用域为同一 session_id 下所有 View、Action、LongTask、Error 数据 |
| sessionOnErrorSampleRate | double | 否 | 错误采集率。当会话未被 sampleRate 采样时,若会话期间发生错误,可以采集到错误前 1 分钟范围的数据,取值范围 [0,1],默认值为 0 |
| enableUserResource | bool | 否 | 是否开启 Flutter http Resource 自动抓取,默认 false。通过修改 HttpOverrides.global 实现,如果项目有定制需求需要继承 FTHttpOverrides |
| enableNativeUserAction | bool | 否 | 是否自动追踪原生侧 Action,包括 Android/iOS 原生控件点击和应用启动事件,默认 false。Android 端需配置 ft-plugin,采集启动事件还需自定义 Application |
| enableNativeUserView | bool | 否 | 是否自动采集原生页面,Android 采集 Activity,iOS 采集 UIViewController,默认 false |
| enableNativeSwiftUIUserView | bool | 否 | iOS:是否开启原生 SwiftUI View 自动追踪。需同时开启 enableNativeUserView |
| enableNativeUserViewInFragment | bool | 否 | 是否自动采集 Android Fragment 页面,需配置 ft-plugin,默认 false,仅支持 Android |
| enableNativeUserResource | bool | 否 | 是否开启原生网络 Resource 自动采集,Android 自动采集 OkHttp 请求,iOS 自动采集原生网络请求,默认 false。该参数与采集 Flutter HttpClient 请求的 enableUserResource 是两套独立能力 |
| enableNativeAppUIBlock | bool | 否 | 是否开启原生主线程卡顿(UI Block/Freeze)自动检测,默认 false |
| nativeUiBlockDurationMS | int | 否 | 原生主线程卡顿检测阈值,单位毫秒,仅在开启 enableNativeAppUIBlock 时生效,取值范围 [100, )。iOS 默认 250ms,Android 默认 1000ms |
| enableLongTask | bool | 否 | 是否开启 Flutter Dart 主 Isolate 长任务自动检测,默认 false |
| dartLongTaskThreshold | double | 否 | Flutter Dart 长任务检测阈值,单位秒,默认 0.1 |
| enableTrackNativeAppANR | bool | 否 | 是否开启原生 ANR 监测,默认 false。ANR 用于检测应用持续无响应,不同于 enableNativeAppUIBlock 采集的单次主线程卡顿;iOS 通过主线程 RunLoop 检测无响应 |
| enableTrackNativeCrash | bool | 否 | 是否开启原生崩溃监测,默认 false。Android 采集 Java Crash 和 Native C/C++ Crash;iOS 采集 Crash,并可通过 iosCrashMonitoringType 配置监控类型 |
| errorMonitorType | int | 否 | 设置附加到 RUM Error 数据的辅助监控信息,支持 ErrorMonitorType.battery、memory、cpu、all,调用时传入对应的 .value,例如 ErrorMonitorType.all.value,默认不开启 |
| deviceMetricsMonitorType | int | 否 | 设置附加到 RUM View 数据的性能监控信息,支持 DeviceMetricsMonitorType.battery、memory、cpu、fps、all,调用时传入对应的 .value,例如 DeviceMetricsMonitorType.all.value,默认不开启 |
| detectFrequency | enum DetectFrequency | 否 | View 性能监控采样周期:DetectFrequency.normal 为 500ms、frequent 为 100ms、rare 为 1000ms,默认 normal;仅配置 deviceMetricsMonitorType 时有意义 |
| globalContext | Map | 否 | 自定义全局参数。添加规则请查阅 冲突字段说明 |
| rumCacheDiscard | enum | 否 | 丢弃策略:FTRUMCacheDiscard.discard 丢弃新数据(默认)、FTRUMCacheDiscard.discardOldest 丢弃旧数据 |
| rumCacheLimitCount | int | 否 | 本地缓存最大 RUM 条目数量限制 [10_000, ),默认 100_000 |
| isInTakeUrl | bool Function(String url) | 否 | Flutter http Resource URL 过滤回调。返回 true 表示过滤、不采集,返回 false 表示采集。使用方式请查阅 数据采集自定义规则 |
| enableTraceWebView | bool | 否 | 是否开启通过原生 SDK 采集 WebView 数据,支持 Android/iOS,默认 true |
| allowWebViewHost | List |
否 | 配置允许进行 WebView 数据采集的 Host 列表,需与 enableTraceWebView 配合使用,支持 Android/iOS;不设置或为 null 时允许采集全部 Host |
| enableResourceHostIP | bool | 否 | 是否采集原生 Resource 请求的 Host IP,默认 false。仅影响 enableNativeUserResource 的原生网络自动采集,不作用于 enableUserResource 采集的 Flutter HttpClient Resource;iOS 要求 13 及以上 |
| iosCrashMonitoringType | enum IOSCrashMonitoringType | 否 | iOS 崩溃监控类型,仅 iOS 生效,需开启 enableTrackNativeCrash。可选 machException、signal、cppException、nsException、system、applicationState、all、highCompatibility,默认 IOSCrashMonitoringType.highCompatibility |
RUM 用户数据追踪¶
Action¶
使用方法¶
/// 添加 action
/// [actionName] action 名称
/// [actionType] action 类型
/// [property] 附加属性参数(可选)
Future<void> startAction(String actionName, String actionType,
{Map<String, Object?>? property})
/// 高频添加 action,不与当前 Resource、LongTask、Error 事件做关联
Future<void> addAction(String actionName, String actionType,
{Map<String, Object?>? property})
代码示例¶
FTRUMManager().startAction("action name", "action type");
FTRUMManager().addAction("action name", "action type");
View¶
自动采集¶
在 MaterialApp.navigatorObservers 添加 FTRouteObserver 后,SDK 可以自动采集 Flutter 页面切换。页面名称(view_name)可通过以下方式配置。
方法 1:通过 routes 采集¶
设置 MaterialApp.routes 需要跳转的页面,routes 中的 key 即为页面名称(view_name)。
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
home: HomeRoute(),
navigatorObservers: [
FTRouteObserver(),
],
routes: <String, WidgetBuilder>{
'logging': (BuildContext context) => Logging(),
'rum': (BuildContext context) => RUM(),
'tracing_custom': (BuildContext context) => CustomTracing(),
'tracing_auto': (BuildContext context) => AutoTracing(),
},
);
}
}
Navigator.pushNamed(context, "logging");
方法 2:通过 FTMaterialPageRoute 采集¶
通过自定义 FTMaterialPageRoute 从控件的 runtimeType 中解析页面名称,其中 widget 类名即为页面名称(view_name)。
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
home: HomeRoute(),
navigatorObservers: [
FTRouteObserver(),
],
);
}
}
Navigator.of(context).push(
FTMaterialPageRoute(builder: (context) => new NoRouteNamePage()),
);
示例请参考 这里。
方法 3:通过 RouteSettings.name 采集¶
在 Route 类型页面中自定义 RouteSettings.name,FTRouteObserver 会优先获取该值。这个方法同样适用于 Dialog 类型页面,例如 showDialog()、showTimePicker() 等。
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
return MaterialApp(
home: HomeRoute(),
navigatorObservers: [
FTRouteObserver(),
],
);
}
}
Navigator.of(context).push(
MaterialPageRoute(
builder: (context) => new NoRouteNamePage(),
settings: RouteSettings(name: "RouteSettingName"),
),
);
以上三种方法可以在一个项目中混合使用。
休眠和唤醒事件采集¶
低于 0.5.1-pre.1 版本,如果需要采集应用休眠和唤醒行为,需要添加如下代码:
class _HomeState extends State<HomeRoute> {
@override
void initState() {
FTLifeRecycleHandler().initObserver();
}
@override
void dispose() {
FTLifeRecycleHandler().removeObserver();
}
}
自动采集过滤规则请查阅 数据采集自定义规则。
自定义 View¶
使用方法¶
/// view 创建,这个方法需要在 [starView] 之前被调用
/// [viewName] 界面名称
/// [duration] 页面加载时长
Future<void> createView(String viewName, int duration)
/// view 开始
/// [viewName] 界面名称
/// [viewReferer] 前一个界面名称
/// [property] 附加属性参数(可选)
Future<void> starView(String viewName, {Map<String, String>? property})
/// view 结束
/// [property] 附加属性参数(可选)
Future<void> stopView({Map<String, String>? property})
代码示例¶
FTRUMManager().createView("Current Page Name", 100000000);
FTRUMManager().starView("Current Page Name");
FTRUMManager().stopView();
自动页面采集、路由过滤、休眠唤醒监听等规则请查阅 数据采集自定义规则。
Error¶
自动采集¶
void main() async {
runZonedGuarded(() async {
WidgetsFlutterBinding.ensureInitialized();
await FTMobileFlutter.sdkConfig(
datakitUrl: serverUrl,
debug: true,
);
await FTRUMManager().setConfig(
androidAppId: appAndroidId,
iOSAppId: appIOSId,
);
// Flutter 异常捕获
FlutterError.onError = FTRUMManager().addFlutterError;
runApp(MyApp());
}, (Object error, StackTrace stack) {
// 添加 Error 数据
FTRUMManager().addError(error, stack);
});
}
自定义 Error¶
使用方法¶
/// 添加自定义错误
/// [stack] 堆栈日志
/// [message] 错误信息
/// [appState] 应用状态
/// [errorType] 自定义 errorType
/// [property] 附加属性参数(可选)
Future<void> addCustomError(String stack, String message,
{Map<String, String>? property, String? errorType})
代码示例¶
LongTask¶
自动采集¶
通过 FTRUMManager().setConfig 开启 enableLongTask 后,SDK 会检测 Flutter Dart 主 Isolate 是否出现超过阈值的阻塞任务,并生成 LongTask 数据。默认阈值为 0.1 秒,可通过 dartLongTaskThreshold 调整。
await FTRUMManager().setConfig(
androidAppId: appAndroidId,
iOSAppId: appIOSId,
enableLongTask: true,
dartLongTaskThreshold: 0.1,
);
自定义 LongTask¶
使用方法¶
/// 上报 LongTask,duration 单位为纳秒
Future<void> addLongTask(String stack, int duration,
{Map<String, String>? property})
代码示例¶
FTRUMManager().addLongTask(
"flutter_manual_long_task",
250000000,
property: {"long_task_source": "manual_report"},
);
自动检测的 LongTask 用于识别 Dart 主 Isolate 事件循环延迟,采集到的是阻塞时长,不表示一定能获取到造成阻塞的业务代码堆栈。
Resource¶
自动采集¶
通过 FTRUMManager().setConfig 开启 enableUserResource 来实现。
自定义 Resource¶
使用方法¶
/// 开始资源请求
/// [key] 唯一 id
/// [property] 附加属性参数(可选)
Future<void> startResource(String key, {Map<String, String>? property})
/// 结束资源请求
/// [key] 唯一 id
/// [property] 附加属性参数(可选)
Future<void> stopResource(String key, {Map<String, String>? property})
/// 发送资源数据指标
Future<void> addResource({
required String key,
required String url,
required String httpMethod,
required Map<String, dynamic> requestHeader,
Map<String, dynamic>? responseHeader,
String? responseBody = "",
int? resourceStatus,
int? resourceSize,
String? resourceType,
FTRUMResourceMetrics? metrics,
})
| 字段 | 类型 | 说明 |
|---|---|---|
| resourceSize | int | 响应体大小,单位 byte |
| resourceType | String | 资源类型,例如 native、image、media、font、css、js |
| metrics.requestSize | num | 请求大小,包含请求头和请求体,单位 byte |
| metrics.resourceHttpProtocol | String | Resource 使用的 HTTP 协议,例如 http/1.1 |
| metrics.reusedConnection | bool | 是否复用连接 |
开启
enableUserResource自动采集时,SDK 会根据请求方法、响应头和连接状态自动补充resourceType、requestSize、resourceHttpProtocol、reusedConnection等字段。
代码示例¶
void httpClientGetHttp(String url) async {
var httpClient = HttpClient();
String key = Uuid().v4();
HttpClientResponse? response;
HttpClientRequest? request;
try {
request = await httpClient
.getUrl(Uri.parse(url))
.timeout(Duration(seconds: 10));
FTRUMManager().startResource(key);
response = await request.close();
} finally {
Map<String, dynamic> requestHeader = {};
Map<String, dynamic> responseHeader = {};
request!.headers.forEach((name, values) {
requestHeader[name] = values;
});
var responseBody = "";
if (response != null) {
response.headers.forEach((name, values) {
responseHeader[name] = values;
});
responseBody = await response.transform(Utf8Decoder()).join();
}
FTRUMManager().stopResource(key);
FTRUMManager().addResource(
key: key,
url: request.uri.toString(),
requestHeader: requestHeader,
httpMethod: request.method,
responseHeader: responseHeader,
resourceStatus: response?.statusCode,
responseBody: responseBody,
);
}
}
使用
http库与dio库,可参考 example。