RUM 設定¶
RUM 初期設定¶
| フィールド | 型 | 必須 | 説明 |
|---|---|---|---|
| androidAppId | String | Android 必須 | Android プラットフォームの app_id。RUM コンソールで申請します。Android ランタイムでのみ読み取られます |
| iOSAppId | String | iOS 必須 | iOS プラットフォームの app_id。RUM コンソールで申請します。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¶
startAction と addAction の使い分け
startActionは内部で Action の所要時間を自動計算します。計算中は、近くで発生したResource、LongTask、Errorデータとの関連付けを試み、100 ms の頻繁なトリガーを防ぐ保護機能も備えています。ユーザー操作タイプのデータに使用することを推奨します。- 頻繁に呼び出す必要がある場合は、
addActionを使用してください。addActionで報告された Action はstartActionと競合せず、現在のResource、LongTask、Errorデータとも関連付けられません。
使用方法¶
/// 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 はこの値を優先的に取得します。この方法は、showDialog()、showTimePicker() などの Dialog タイプのページにも適用できます。
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"),
),
);
上記 3 つの方法は、1 つのプロジェクト内で併用できます。
スリープとウェイクアップイベントの収集¶
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 を参照してください。