データ収集のカスタムルール¶
View¶
Activity¶
- まず
FTRUMConfig.setEnableTraceUserView(true)で有効にする必要があります
FTSdk.initRUMWithConfig(new FTRUMConfig()
.setViewActivityTrackingHandler(new FTViewActivityTrackingHandler() {
@Override
public HandlerView resolveHandlerView(Activity activity) {
String activityName = activity.getClass().getSimpleName();
// Activity 名に基づいて View 名をカスタマイズ
if (activityName.startsWith("Main")) {
return new HandlerView("自定义主页面");
} else if (activityName.startsWith("Detail")) {
HashMap<String, Object> properties = new HashMap<>();
properties.put("extra_key", "extra_value");
return new HandlerView("自定义详情页面", properties);
}
// null を返して追跡をスキップ
return null;
}
})
);
FTSdk.initRUMWithConfig(
FTRUMConfig()
.setViewActivityTrackingHandler(object : FTViewActivityTrackingHandler {
override fun resolveHandlerView(activity: Activity): HandlerView? {
val activityName = activity.javaClass.simpleName
return when {
activityName.startsWith("Main") ->
HandlerView("自定义主页面")
activityName.startsWith("Detail") -> {
val properties = hashMapOf<String, Any>("extra_key" to "extra_value")
HandlerView("自定义详情页面", properties)
}
else -> null // 追跡をスキップ
}
}
})
)
Fragment¶
FTRUMConfig.setEnableTraceUserView(true)とFTRUMConfig.setEnableTraceUserViewInFragment(true)を同時に有効にする必要があります
FTSdk.initRUMWithConfig(new FTRUMConfig()
.setViewFragmentTrackingHandler(new FTViewFragmentTrackingHandler() {
@Override
public HandlerView resolveHandlerView(FragmentWrapper fragment) {
String fragmentName = fragment.getSimpleClassName();
// Fragment 名に基づいて View 名をカスタマイズ
if (fragmentName.equals("HomeFragment")) {
return new HandlerView("自定义首页片段");
} else if (fragmentName.startsWith("Detail")) {
HashMap<String, Object> properties = new HashMap<>();
properties.put("extra_key", "extra_value");
return new HandlerView("自定义详情片段", properties);
}
// null を返して追跡をスキップ
return null;
}
})
);
FTSdk.initRUMWithConfig(
FTRUMConfig()
.setViewFragmentTrackingHandler(object : FTViewFragmentTrackingHandler {
override fun resolveHandlerView(fragment: FragmentWrapper): HandlerView? {
val fragmentName = fragment.simpleClassName
return when {
fragmentName == "HomeFragment" ->
HandlerView("自定义首页片段")
fragmentName.startsWith("Detail") -> {
val properties = hashMapOf<String, Any>("extra_key" to "extra_value")
HandlerView("自定义详情片段", properties)
}
else -> null // 追跡をスキップ
}
}
})
)
View 所要時間メトリクスのカスタムルール¶
FTRUMConfig.setInitialResourceIdentifier と setLastInteractionIdentifier を使用して、ネイティブ View の network_settled_time と interaction_to_next_view_time の判定ルールをカスタマイズします。メトリクスの意味、単位、デフォルトルールについては、View 所要時間メトリクスを参照してください。
時間ウィンドウの調整¶
FTSdk.initRUMWithConfig に渡す設定でポリシーを設定します。次の例では、初期 Resource ウィンドウを 500 ms に、interaction_to_next_view_time の上限を 5000 ms に調整します。コンストラクタ引数の単位はミリ秒で、0 より大きい必要があり、ウィンドウの上限は含まれません。
FTSdk.initRUMWithConfig(
new FTRUMConfig()
.setRumAppId(RUM_APP_ID)
.setEnableTraceUserView(true)
.setEnableTraceUserAction(true)
.setEnableTraceUserResource(true)
.setInitialResourceIdentifier(new FTTimeBasedInitialResourceIdentifier(500))
.setLastInteractionIdentifier(new FTTimeBasedInteractionIdentifier(5000))
);
FTSdk.initRUMWithConfig(
FTRUMConfig()
.setRumAppId(RUM_APP_ID)
.setEnableTraceUserView(true)
.setEnableTraceUserAction(true)
.setEnableTraceUserResource(true)
.setInitialResourceIdentifier(FTTimeBasedInitialResourceIdentifier(500))
.setLastInteractionIdentifier(FTTimeBasedInteractionIdentifier(5000))
)
ポリシーを設定しても、View、Action、Resource の収集は自動的に有効になりません。自動収集には引き続き対応する設定を有効にし、既存の導入要件を満たす必要があります。RUM 手動インスツルメンテーション API と組み合わせて使用することもできます。
判定ルールのカスタマイズ¶
2 つのポリシーインターフェースはいずれも validate(context) メソッドを提供します。true を返すとカスタムフィルタを通過し、false を返すと対応するメトリクスの計算に参加しません。フィルタを通過してもメトリクスが生成されるとは限りません。後述のメトリクス生成制限も満たす必要があります。判定条件には、コンテキストが提供する情報または業務側が管理する外部状態を使用できます。
カスタムルールは対応するデフォルトの時間判定を置き換え、100 ms または 3000 ms の制限は追加適用されません。interaction_to_next_view_time の時間差が 0 より大きい必要があるという基本要件は引き続き有効です。
RUM の初期化前に、設定済みの config にルールを指定します。次の例では、業務の初期ロード段階で登録された Resource のみをネットワークメトリクスに含め、間隔が 5 秒未満の最後の click インタラクションのみを受け入れます。
import java.util.concurrent.atomic.AtomicBoolean;
// 業務側で管理する。初期ロード段階の終了時に initialLoading.set(false) を呼び出す。
AtomicBoolean initialLoading = new AtomicBoolean(true);
FTLastInteractionIdentifier navigationWindow = new FTTimeBasedInteractionIdentifier(5000);
config.setInitialResourceIdentifier(context -> initialLoading.get())
.setLastInteractionIdentifier(context ->
"click".equals(context.getActionType()) && navigationWindow.validate(context));
import java.util.concurrent.atomic.AtomicBoolean
// 業務側で管理する。初期ロード段階の終了時に initialLoading.set(false) を呼び出す。
val initialLoading = AtomicBoolean(true)
val navigationWindow = FTTimeBasedInteractionIdentifier(5000)
config.setInitialResourceIdentifier { context -> initialLoading.get() }
.setLastInteractionIdentifier { context ->
context.actionType == "click" && navigationWindow.validate(context)
}
Java では、Lambda を使用せずに匿名内部クラスで FTInitialResourceIdentifier または FTLastInteractionIdentifier を実装することもできます。
2 つのコールバックのコンテキストはどちらも不変オブジェクトであり、以下のメソッドを公開しています。時間値は System.nanoTime() と同じプロセス内単調クロックを使用し、単位はナノ秒です。Unix タイムスタンプではないため、System.currentTimeMillis() と直接比較することはできません。
| コンテキスト | メソッド | 意味 |
|---|---|---|
FTNetworkSettledResourceContext |
getResourceId() |
この SDK 登録で使用される Resource ID |
FTNetworkSettledResourceContext |
getResourceStartTimeNanos() |
SDK が記録した元の Resource 計測開始時点 |
FTNetworkSettledResourceContext |
getViewStartTimeNanos() |
所属する View の開始時間 |
FTPreviousViewLastInteractionContext |
getActionType() |
前の View における最後の候補インタラクションのタイプ |
FTPreviousViewLastInteractionContext |
getInteractionTimeNanos() |
SDK が記録したインタラクション開始時間。明示的に停止された待機型 Action は停止時間を使用 |
FTPreviousViewLastInteractionContext |
getNextViewStartTimeNanos() |
次の View の開始時間 |
ネットワークコンテキストには URL、リクエストメソッド、リクエストヘッダー、ステータスコード、カスタム属性は含まれないため、コンテキストから直接エンドポイントアドレスを読み取ってフィルタリングすることはできません。interaction_to_next_view_time コンテキストには Action 名や業務属性は含まれません。
コールバック使用時の注意事項¶
- 初期化前にルールを設定します。 初期化後に
FTRUMConfigのポリシーを変更しても有効になりません。コールバックは引き続き業務側が管理する外部状態を読み取ることができます。 - 迅速に返し、スレッドセーフティに注意します。 コールバック内でネットワークリクエストやファイル I/O などのブロッキング操作を実行しないでください。ネットワークルールはメインスレッドまたは複数の収集スレッドから呼び出される可能性があります。
interaction_to_next_view_timeルールは SDK イベントキュー内で呼び出されます。 - 業務状態はコールバック実行時の値に基づきます。 ネットワークルールは SDK が Resource を登録する時点で同期的に呼び出され、各登録につき 1 回だけ判定されます。登録はリクエスト開始時刻より遅れる可能性があります。時間でフィルタリングする場合は、コンテキスト内の元の開始時間を使用してください。例の
initialLoadingはコールバック実行時の値を使用し、その後状態を変更しても該当リクエストの再判定は行われません。 - メトリクスから除外してもイベント収集には影響しません。
falseを返すか通常の例外をスローしても、今回のリクエストまたはインタラクションのメトリクスへの寄与が除外されるだけで、元の Resource または Action イベントが破棄されることはありません。
メトリクス生成の制限¶
network_settled_time:
- 選択されたすべてのリクエストの処理が完了した後にのみ、SDK はそのうち正常に記録されたリクエストに基づいて所要時間を計算できます。有効なリクエストがない場合はフィールドは生成されません。フィールドの欠落は所要時間が 0 であることを意味しません。
- View の終了時に結果が確定します。この時点で選択されたリクエストがまだ終了していない場合、またはそのローカルキャッシュへの書き込みが完了していない場合、フィールドは欠落したままになります。その後リクエストが完了しても再計算されません。
interaction_to_next_view_time:
clickタイプの Action のみを受け入れます。自動収集される戻るキー操作もclickタイプを使用し、名前はbackです。カスタムルールによって他の Action タイプを計算に参加させることはできません。- 前の View で最後に正常記録された候補インタラクションのみを判定します。ルールがそのインタラクションを拒否した場合、今回の結果は生成されず、さらに古いインタラクションを検索することもありません。
データ書き込みとコールバックタイミングの詳細ルール
- リクエストが有効かどうか: 選択されたリクエストの Resource または対応する Network Error が少なくとも 1 件ローカルキャッシュに正常書き込みされた場合にのみ、
network_settled_timeに計上されます。関連レコードがすべてフィルタリング、破棄、または書き込み失敗した場合、SDK は該当リクエストの待機を停止しますが、その所要時間は計上しません。有効な 0 ナノ秒の結果は保持されます。 - インタラクションの前後順序: 「最後」は SDK が Action の正常書き込み結果を受信した順序で決定され、インタラクションのタイムスタンプによる再ソートは行われません。
- インタラクションルールが呼び出されるタイミング: 前の View の候補インタラクションと次の View の両方が確定した後、SDK は
interaction_to_next_view_timeルールを呼び出します。同じ組み合わせは 1 回だけ判定されます。新しい候補インタラクションを受信すると再判定されます。通常の View 更新、リトライ、アップロード、キャッシュ復元では、これら 2 つのルールは再度呼び出されません。 - インタラクション結果が更新されるタイミング: SDK が前の View と次の View の関連情報をまだ保持している場合、遅延して到着した前ページの Action 書き込み結果によって、次の View の
interaction_to_next_view_timeを更新できます。計算済みの結果は、前の View の履歴レコードが削除されてもクリアされません。
メトリクスを無効化¶
setInitialResourceIdentifier は null を受け付けません。上記の設定はすべて FTSdk.initRUMWithConfig(config) より前に設定する必要があり、既存の View、Action、Resource イベント収集は無効化されません。
Action¶
FTRUMConfig.setEnableTraceUserAction(true)で有効化されている必要があります- 用途:Action 名や属性をカスタマイズする、または特定の View に基づいて Action 収集をフィルタリングする
FTSdk.initRUMWithConfig(new FTRUMConfig()
.setActionTrackingHandler(new FTActionTrackingHandler() {
@Override
public HandlerAction resolveHandlerAction(ActionEventWrapper actionEventWrapper) {
// 操作タイプを取得
ActionSourceType actionType = actionEventWrapper.getSourceType();
Object source = actionEventWrapper.getSource();
// 指定 View の Action をフィルタリング
if (source instanceof View) {
View view = (View) source;
if (view.getId() == R.id.ignore_action_view) {
return null;
}
}
// 操作タイプに基づいて追跡をカスタマイズ
if (actionType == ActionSourceType.CLICK_VIEW) {
HashMap<String, Object> properties = new HashMap<>();
properties.put("extra_key", "extra_value");
return new HandlerAction("自定义按钮点击", properties);
} else if (actionType == ActionSourceType.CLICK_LIST_ITEM) {
return new HandlerAction("自定义列表项点击");
}
// null を返して追跡をスキップ
return null;
}
})
);
FTSdk.initRUMWithConfig(
FTRUMConfig()
.setActionTrackingHandler(object : FTActionTrackingHandler {
override fun resolveHandlerAction(actionEventWrapper: ActionEventWrapper): HandlerAction? {
val source = actionEventWrapper.source
// 指定 View の Action をフィルタリング
if (source is View && source.id == R.id.ignore_action_view) {
return null
}
return when (actionEventWrapper.sourceType) {
ActionSourceType.CLICK_VIEW -> {
val properties = hashMapOf<String, Any>("extra_key" to "extra_value")
HandlerAction("自定义按钮点击", properties)
}
ActionSourceType.CLICK_LIST_ITEM ->
HandlerAction("自定义列表项点击")
else -> null // 追跡をスキップ
}
}
})
)
注意
ActionEventWrapper.getSource() を使用して、現在の操作のソースオブジェクトを取得できます。通常のクリック、リスト項目のクリック、タブのクリックなど、View によってトリガーされる Action では、source は通常対応する View です。setActionTrackingHandler を設定すると、SDK はこのハンドラーの返り値を Action 収集の判断基準とします。null を返した Action はスキップされます。引き続き収集する必要がある Action は HandlerAction を返す必要があります。
Resource¶
FTRUMConfig.setEnableTraceUserResource(true)で有効化されている必要があります
URL に基づく収集フィルタリング¶
カスタム属性を追加¶
FTRUMConfig.setOkHttpResourceContentHandler(FTResourceInterceptor.ContentHandlerHelperEx) を使用できます。
new FTResourceInterceptor.ContentHandlerHelperEx() {
@Override
public void onRequest(Request request, HashMap<String, Object> extraData) {
extraData.put("df_custom_key","custom_value");
}
@Override
public void onResponse(Response response, HashMap<String, Object> extraData) throws IOException {
extraData.put("df_custom_key","custom_value");
}
@Override
public boolean onExceptionWithFilter(Exception e, HashMap<String, Object> extraData) {
extraData.put("df_custom_key","custom_value");
return false;
}
}
object : FTResourceInterceptor.ContentHandlerHelperEx() {
override fun onRequest(
request: Request,
extraData: HashMap<String, Any>
) {
extraData["df_custom_key"] = "custom_value"
}
override fun onResponse(
response: Response,
extraData: HashMap<String, Any>
) {
extraData["df_custom_key"] = "custom_value"
}
override fun onExceptionWithFilter(
e: Exception,
extraData: HashMap<String, Any>
): Boolean {
extraData["df_custom_key"] = "custom_value"
return false
}
}
ネットワークエラーをフィルタリング¶
ローカルネットワークの IOException エラーを対象にフィルタリングできます。FTRUMConfig.setOkHttpResourceContentHandler(FTResourceInterceptor.ContentHandlerHelperEx) で設定するか、Resource のカスタマイズを参照してください。
new FTResourceInterceptor.ContentHandlerHelperEx() {
//...
/**
* ネットワーク接続プロセス中の例外を返します
*
* @param e リクエストで発生した IOException データ
* @param extraData 追加データ
* @return ローカルネットワークの network_error タイプのエラーをフィルタリングするかどうか。true の場合はフィルタリングして収集しないことを示します
*/
@Override
public boolean onExceptionWithFilter(Exception e, HashMap<String, Object> extraData) {
if (e instanceof SocketTimeoutException) { //ネットワークタイムアウト
return true;
}
return super.onExceptionWithFilter(e, extraData);
}
}
object : FTResourceInterceptor.ContentHandlerHelperEx() {
//...
/**
* ネットワーク接続プロセス中の例外を返します
*
* @param e リクエストで発生した IOException データ
* @param extraData 追加データ
* @return ローカルネットワークの network_error タイプのエラーをフィルタリングするかどうか。true の場合はフィルタリングして収集しないことを示します
*/
override fun onExceptionWithFilter(e: Exception, extraData: HashMap<String, Any>): Boolean {
return if (e is SocketTimeoutException) {
true
} else {
super.onExceptionWithFilter(e, extraData)
}
}
}
Error¶
Crash/ANR カスタムフィールド¶
ft-sdk >= 1.7.5 では、FTRUMConfig.setIssueDataProvider(FTIssueDataProvider) を使用して、自動収集される Crash および ANR RUM Error にカスタムフィールドを追加できます。
FTRUMConfig config = new FTRUMConfig()
.setEnableTrackAppCrash(true)
.setEnableTrackAppANR(true)
.setIssueDataProvider(issue -> {
Map<String, Object> fields = new HashMap<>();
fields.put("business_scene", sceneStore.current());
fields.put("historical_issue", issue.isHistorical());
return fields;
});
FTIssueDataProvider.provideAdditionalFields(FTIssueInfo) は Error の構築時に同期的に呼び出され、並行実行される可能性があります。実装はスレッドセーフであること、I/O を避けること、10 ms 以内に返すことを保証する必要があります。Provider を設定しても Crash または ANR 収集は自動的に有効にならず、対応する収集項目を有効にする必要があります。
- 自動収集された Java/Native Crash、および watchdog、native、
ApplicationExitInfoANR のみが Provider をトリガーします。手動 Error、Network Error、WebView Error はトリガーしません。 - Native dump または
ApplicationExitInfoから復元されたデータでは、FTIssueInfo.isHistorical()はtrueを返します。 - 返り値は文字列、ブール値、有限数値をサポートし、最大 50 項目までチェックされます。Key は最大 100 UTF-8 バイト、文字列値は最大 4096 UTF-8 バイト、すべてのフィールドの合計は 25 KiB 以下である必要があります。
- 無効な値、上限超過、SDK 予約フィールド、および
error.またはerror_で始まる Key は無視されます。業務側は、フィールド内容がプライバシーとコンプライアンスの要件を満たすことを自ら保証する必要があります。
カスタム TraceHeader¶
FTTraceConfig.setOkHttpTraceHeaderHandler(FTTraceInterceptor.HeaderHandler) で設定するか、Trace のカスタマイズを参照してください。以下は w3c-traceContext を例にしています。
new FTTraceInterceptor.HeaderHandler() {
private String[] splits;
@Override
public HashMap<String, String> getTraceHeader(Request request) {
HashMap<String, String> map = new HashMap<>();
//ヘッダーからカスタム trace_id を取得
String replaceTrace = request.header(CUSTOM_TRACE_HEADER);
String headerString = FTTraceManager.get().
getTraceHeader(request.url().toString())
// ヘッダーから propagation header を取得
.get(FTTraceHandler.W3C_TRACEPARENT_KEY);
splits = headerString.split("-");
String originTraceId = splits[1];
splits[1] = replaceTrace;
map.put(FTTraceHandler.W3C_TRACEPARENT_KEY, headerString.replace(originTraceId, replaceTrace));
return map;
}
@Override
public String getSpanID() {
if (splits != null) {
return splits[2];
}
return null;
}
@Override
public String getTraceID() {
if (splits != null) {
return splits[1];
}
return null;
}
};
object : FTTraceInterceptor.HeaderHandler() {
private var splits: List<String>? = null
override fun getTraceHeader(request: Request): HashMap<String, String> {
val map = HashMap<String, String>()
// ヘッダーからカスタム trace_id を取得
val replaceTrace = request.header(CUSTOM_TRACE_HEADER)
val headerString = FTTraceManager.get()
.getTraceHeader(request.url().toString())
.get(FTTraceHandler.W3C_TRACEPARENT_KEY)
splits = headerString?.split("-")
val originTraceId = splits?.getOrNull(1)
if (headerString != null && originTraceId != null && replaceTrace != null) {
map[FTTraceHandler.W3C_TRACEPARENT_KEY] =
headerString.replace(originTraceId, replaceTrace)
}
return map
}
override fun getSpanID(): String? {
return splits?.getOrNull(2)
}
override fun getTraceID(): String? {
return splits?.getOrNull(1)
}
}
カスタム trace_id を使用して RUM Resource を関連付ける¶
アプリ側にすでにカスタム trace_id がある場合(例:リクエストヘッダーのキーが custom_trace_id)、SDK が生成した traceparent を基に trace_id を更新し、TraceContext.Simple を介して RUM Resource の関連付けに使用する trace_id を指定できます。
new FTTraceInterceptor.HeaderHandler() {
@Override
public TraceContext getTraceContext(Request request) {
HashMap<String, String> headers = FTTraceManager.get()
.getTraceHeader(request.url().toString());
// リクエストヘッダーからカスタム trace_id を取得する(例:custom_trace_id)
String customTraceId = request.header(CUSTOM_TRACE_HEADER);
TraceContext.Simple sdkContext = TraceContext.Simple.fromTraceType(headers);
if (customTraceId == null
|| customTraceId.length() == 0
|| sdkContext == null
|| sdkContext.getTraceId() == null) {
return sdkContext;
}
String traceparent = headers.get(FTTraceHandler.W3C_TRACEPARENT_KEY);
if (traceparent == null) {
return sdkContext;
}
String newTraceparent = traceparent.replace(
sdkContext.getTraceId(),
customTraceId
);
// リクエストに注入される W3C trace ヘッダーを更新
headers.put(FTTraceHandler.W3C_TRACEPARENT_KEY, newTraceparent);
// 任意:カスタム業務ヘッダーを保持
headers.put(CUSTOM_TRACE_HEADER, customTraceId);
// RUM Resource の関連付けには customTraceId を使用し、spanId は引き続き SDK が生成した spanId を使用
return new TraceContext.Simple(headers, customTraceId, sdkContext.getSpanId());
}
};
object : FTTraceInterceptor.HeaderHandler() {
override fun getTraceContext(request: Request): TraceContext? {
val headers = FTTraceManager.get()
.getTraceHeader(request.url().toString())
// リクエストヘッダーからカスタム trace_id を取得
val customTraceId = request.header(CUSTOM_TRACE_HEADER)
val sdkContext = TraceContext.Simple.fromTraceType(headers)
val sdkTraceId = sdkContext?.traceId
val sdkSpanId = sdkContext?.spanId
if (customTraceId.isNullOrEmpty() || sdkTraceId.isNullOrEmpty()) {
return sdkContext
}
val traceparent = headers[FTTraceHandler.W3C_TRACEPARENT_KEY] ?: return sdkContext
val newTraceparent = traceparent.replace(sdkTraceId, customTraceId)
// リクエストに注入される W3C trace ヘッダーを更新
headers[FTTraceHandler.W3C_TRACEPARENT_KEY] = newTraceparent
// 任意:カスタム業務ヘッダーを保持
headers[CUSTOM_TRACE_HEADER] = customTraceId
// RUM Resource の関連付けには customTraceId を使用し、spanId は引き続き SDK が生成した spanId を使用
return TraceContext.Simple(headers, customTraceId, sdkSpanId)
}
}
注意:W3C trace_id は 32 桁の 16 進数文字列である必要があり、すべてが 0 であってはなりません。