RUM Configuration¶
RUM Initialization Configuration¶
| Field | Type | Required | Description |
|---|---|---|---|
| androidAppId | String | Yes | Android platform app_id, applied for in the RUM console |
| iOSAppId | String | Yes | iOS platform app_id, applied for in the RUM console |
| sampleRate | double | No | Sampling rate, range [0,1], 0 means no collection, 1 means full collection, default is 1. Scope is all View, Action, LongTask, Error data under the same session_id |
| sessionOnErrorSampleRate | double | No | Error collection rate. When a session is not sampled by sampleRate, if an error occurs during the session, data from the 1 minute before the error can be collected, range [0,1], default is 0 |
| enableUserResource | bool | No | Whether to enable automatic Flutter http Resource capture, default false. Implemented by modifying HttpOverrides.global. If the project has customization needs, inherit FTHttpOverrides |
| enableNativeUserAction | bool | No | Whether to perform Native Action tracking, default false |
| enableNativeUserView | bool | No | Whether to perform Native View automatic tracking. For pure Flutter applications, it is recommended to turn off, default false |
| enableNativeSwiftUIUserView | bool | No | iOS: Whether to enable native SwiftUI View automatic tracking. Requires enableNativeUserView to also be enabled |
| enableNativeUserViewInFragment | bool | No | Whether to automatically track Native Fragment type page data, default false, only supports Android |
| enableNativeUserResource | bool | No | Whether to perform Native Resource automatic tracking. For pure Flutter applications, it is recommended to turn off, default false |
| enableAppUIBlock | bool | No | Whether to perform Native Freeze automatic tracking, default false |
| nativeUiBlockDurationMS | int | No | Set the time range for Native Freeze, range [100, ), unit milliseconds. iOS default 250ms, Android default 1000ms |
| enableLongTask | bool | No | Whether to enable Flutter Dart main Isolate long task automatic detection, default false |
| dartLongTaskThreshold | double | No | Flutter Dart long task detection threshold, unit seconds, default 0.1 |
| enableTrackNativeAppANR | bool | No | Whether to enable Native ANR monitoring, default false |
| enableTrackNativeCrash | bool | No | Whether to enable Android Java Crash and OC/C/C++ crash monitoring, default false |
| errorMonitorType | enum ErrorMonitorType | No | Set auxiliary monitoring information, add additional monitoring data to RUM Error data. Default is off |
| deviceMetricsMonitorType | enum DeviceMetricsMonitorType | No | Add performance monitoring data within the View cycle, default is off |
| detectFrequency | enum DetectFrequency | No | View performance monitoring sampling frequency, default DetectFrequency.normal |
| globalContext | Map | No | Custom global parameters. For addition rules, refer to Conflict Field Description |
| rumCacheDiscard | enum | No | Discard policy: FTRUMCacheDiscard.discard discard new data (default), FTRUMCacheDiscard.discardOldest discard old data |
| rumCacheLimitCount | number | No | Local cache maximum RUM entry count limit [10_000, ), default 100_000 |
| isInTakeUrl | callBack | No | Set Resource filtering conditions, usage refer to Data Collection Custom Rules |
| enableTraceWebView | bool | No | Whether to enable WebView data collection via Android SDK, only supports Android |
| allowWebViewHost | List |
No | Configure the list of Hosts allowed for WebView data collection, must be used with enableTraceWebView, only supports Android |
| enableResourceHostIP | bool | No | Whether to collect Host IP information for Resource requests |
| iosCrashMonitoringType | enum IOSCrashMonitoringType | No | iOS crash monitoring type configuration |
RUM User Data Tracking¶
Action¶
Usage¶
/// Add action
/// [actionName] action name
/// [actionType] action type
/// [property] additional property parameters (optional)
Future<void> startAction(String actionName, String actionType,
{Map<String, Object?>? property})
/// High-frequency action addition, not associated with current Resource, LongTask, Error events
Future<void> addAction(String actionName, String actionType,
{Map<String, Object?>? property})
Code Example¶
FTRUMManager().startAction("action name", "action type");
FTRUMManager().addAction("action name", "action type");
View¶
Automatic Collection¶
After adding FTRouteObserver to MaterialApp.navigatorObservers, the SDK can automatically collect Flutter page switches. The page name (view_name) can be configured in the following ways.
Method 1: Collection via routes¶
Set the pages to navigate to in MaterialApp.routes. The key in routes is the page name (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");
Method 2: Collection via FTMaterialPageRoute¶
Use the custom FTMaterialPageRoute to parse the page name from the widget's runtimeType, where the widget class name is the page name (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()),
);
For examples, refer to here.
Method 3: Collection via RouteSettings.name¶
Customize RouteSettings.name in Route type pages. FTRouteObserver will prioritize obtaining this value. This method also applies to Dialog type pages, such as showDialog(), showTimePicker(), etc.
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"),
),
);
The above three methods can be mixed within one project.
Sleep and Wake Event Collection¶
For versions below 0.5.1-pre.1, if you need to collect application sleep and wake behaviors, add the following code:
class _HomeState extends State<HomeRoute> {
@override
void initState() {
FTLifeRecycleHandler().initObserver();
}
@override
void dispose() {
FTLifeRecycleHandler().removeObserver();
}
}
For automatic collection filtering rules, refer to Data Collection Custom Rules.
Custom View¶
Usage¶
/// View creation, this method needs to be called before [starView]
/// [viewName] interface name
/// [duration] page load duration
Future<void> createView(String viewName, int duration)
/// View start
/// [viewName] interface name
/// [viewReferer] previous interface name
/// [property] additional property parameters (optional)
Future<void> starView(String viewName, {Map<String, String>? property})
/// View end
/// [property] additional property parameters (optional)
Future<void> stopView({Map<String, String>? property})
Code Example¶
FTRUMManager().createView("Current Page Name", 100000000);
FTRUMManager().starView("Current Page Name");
FTRUMManager().stopView();
For automatic page collection, route filtering, sleep/wake listening rules, etc., refer to Data Collection Custom Rules.
Error¶
Automatic Collection¶
void main() async {
runZonedGuarded(() async {
WidgetsFlutterBinding.ensureInitialized();
await FTMobileFlutter.sdkConfig(
datakitUrl: serverUrl,
debug: true,
);
await FTRUMManager().setConfig(
androidAppId: appAndroidId,
iOSAppId: appIOSId,
);
// Flutter exception capture
FlutterError.onError = FTRUMManager().addFlutterError;
runApp(MyApp());
}, (Object error, StackTrace stack) {
// Add Error data
FTRUMManager().addError(error, stack);
});
}
Custom Error¶
Usage¶
/// Add custom error
/// [stack] stack log
/// [message] error message
/// [appState] application state
/// [errorType] custom errorType
/// [property] additional property parameters (optional)
Future<void> addCustomError(String stack, String message,
{Map<String, String>? property, String? errorType})
Code Example¶
LongTask¶
Automatic Collection¶
After enabling enableLongTask via FTRUMManager().setConfig, the SDK will detect if the Flutter Dart main Isolate has blocking tasks exceeding the threshold and generate LongTask data. The default threshold is 0.1 seconds, adjustable via dartLongTaskThreshold.
await FTRUMManager().setConfig(
androidAppId: appAndroidId,
iOSAppId: appIOSId,
enableLongTask: true,
dartLongTaskThreshold: 0.1,
);
Custom LongTask¶
Usage¶
/// Report LongTask, duration unit is nanoseconds
Future<void> addLongTask(String stack, int duration,
{Map<String, String>? property})
Code Example¶
FTRUMManager().addLongTask(
"flutter_manual_long_task",
250000000,
property: {"long_task_source": "manual_report"},
);
Automatically detected LongTasks are used to identify Dart main Isolate event loop delays. The collected duration is the blocking time, and does not necessarily mean the business code stack causing the blockage can be obtained.
Resource¶
Automatic Collection¶
Enabled via FTRUMManager().setConfig by turning on enableUserResource.
Custom Resource¶
Usage¶
/// Start resource request
/// [key] unique id
/// [property] additional property parameters (optional)
Future<void> startResource(String key, {Map<String, String>? property})
/// End resource request
/// [key] unique id
/// [property] additional property parameters (optional)
Future<void> stopResource(String key, {Map<String, String>? property})
/// Send resource data metrics
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,
})
| Field | Type | Description |
|---|---|---|
| resourceSize | int | Response body size, unit byte |
| resourceType | String | Resource type, e.g., native, image, media, font, css, js |
| metrics.requestSize | num | Request size, including request headers and body, unit byte |
| metrics.resourceHttpProtocol | String | HTTP protocol used by Resource, e.g., http/1.1 |
| metrics.reusedConnection | bool | Whether the connection is reused |
When
enableUserResourceautomatic collection is enabled, the SDK will automatically supplement fields likeresourceType,requestSize,resourceHttpProtocol,reusedConnectionbased on request method, response headers, and connection status.
Code Example¶
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,
);
}
}
For using
httplibrary anddiolibrary, refer to example.