コンテンツにスキップ

データ収集のカスタムルール

View

UIKit View の自動収集ルールをカスタマイズする場合は、設定 FTRumConfig.enableTraceUserView = YES を有効にする必要があります。

rumConfig.viewTrackingHandler = [CustomViewTracker new];

#import "FTDefaultUIKitViewTrackingHandler.h"

// プロトコル実装例
@interface CustomViewTracker : NSObject <FTUIKitViewTrackingHandler>
// SDK デフォルトの View 収集ルールが必要な場合のみ追加
@property (nonatomic, strong) FTDefaultUIKitViewTrackingHandler defaultHandler;
@end

@implementation CustomViewTracker

// SDK デフォルトの View 収集ルールが必要な場合のみ追加
-(FTDefaultUIKitViewTrackingHandler *)defaultHandler{
    if (!_defaultHandler) {
        _defaultHandler = [FTDefaultUIKitViewTrackingHandler new];
    }
    return _defaultHandler;
}

- (FTRUMView *)rumViewForViewController:(UIViewController *)viewController {
    // クラス名による完全一致
    if ([viewController isKindOfClass:[HomeViewController class]]) {
        return [[FTRUMView alloc] initWithViewName:@"main_home" property:@{@"page_type": @"home"}];
    }
    // プレフィックスによるフィルタリング
    else if ([NSStringFromClass([viewController class]) hasPrefix:@"FT"]) {
        return [[FTRUMView alloc] initWithViewName:[NSString stringWithFormat:@"ft_%@", NSStringFromClass([viewController class])] property:nil];
    }
    // accessibilityLabel による設定
    else if (viewController.view.accessibilityLabel) {
        return [[FTRUMView alloc] initWithViewName:viewController.view.accessibilityLabel property:nil];
    }
    // 一部のページをカスタマイズした後、残りのページは SDK デフォルトの収集ルールを使用します(デフォルトハンドラーの処理結果を返します)
    return [self.defaultHandler rumViewForViewController:viewController];

    // 追跡をスキップする場合は nil を直接返します
    return nil;
}
@end
rumConfig.viewTrackingHandler = CustomViewTracker()

class CustomViewTracker: NSObject, FTUIKitViewTrackingHandler {

    // SDK デフォルトの View 収集ルールが必要な場合のみ、このプロパティを保持します
    lazy var defaultHandler: FTDefaultUIKitViewTrackingHandler = {
        FTDefaultUIKitViewTrackingHandler() 
    }()

    func rumView(for viewController: UIViewController) -> FTRUMView? {
        // クラス名による完全一致
        if viewController is HomeViewController {
            let properties: [String: Any] = ["page_type": "home"]
            return FTRUMView(viewName: "main_home", property: properties)
        }

        // クラス名のプレフィックスによるフィルタリング
        let vcClassName = String(describing: type(of: viewController))
        if vcClassName.hasPrefix("FT") {
            let viewName = "ft_\(vcClassName)"
            return FTRUMView(viewName: viewName, property: nil)
        }

        // accessibilityLabel による設定
        if let accessibilityLabel = viewController.view.accessibilityLabel, !accessibilityLabel.isEmpty {
            return FTRUMView(viewName: accessibilityLabel, property: nil)
        }

        // 一部のページをカスタマイズした後、残りのページは SDK デフォルトの収集ルールを使用します(デフォルトハンドラーの処理結果を返します)
        return defaultHandler.rumView(for: viewController)

        // 追跡をスキップする場合は nil を直接返します
        return nil
    }
}

ページ読み込み時間の収集制御

SDK 1.6.9 以降でサポートされています。

RUM の起動前に FTRumConfig を設定すると、View の自動追跡を維持したまま、ページの loading_time の自動収集だけを無効にできます。enableTraceUserViewLoadingTime のデフォルトは YES で、enableTraceUserView = YES の場合に有効になります。NO に設定すると、自動の読み込み時間収集をグローバルに無効にできますが、手動で読み込み時間を送信する動作には影響しません。

rumConfig.enableTraceUserView = YES;
rumConfig.enableTraceUserViewLoadingTime = NO;
[[FTMobileAgent sharedInstance] startRumWithConfigOptions:rumConfig];
rumConfig.enableTraceUserView = true
rumConfig.enableTraceUserViewLoadingTime = false
FTMobileAgent.sharedInstance().startRum(withConfigOptions: rumConfig)

特定のコントローラーだけを除外する場合は、グローバルスイッチを有効にしたまま、viewLoadingTimeClassNameExcludes を設定してください。たとえば、プロジェクト内の HomeViewController を除外する場合は次のように設定します:

rumConfig.enableTraceUserView = YES;
rumConfig.viewLoadingTimeClassNameExcludes = @[@"HomeViewController"];
[[FTMobileAgent sharedInstance] startRumWithConfigOptions:rumConfig];
rumConfig.enableTraceUserView = true
rumConfig.viewLoadingTimeClassNameExcludes = [NSStringFromClass(HomeViewController.self)]
FTMobileAgent.sharedInstance().startRum(withConfigOptions: rumConfig)

クラス名配列のデフォルトは空です。マッチングには大文字小文字を区別する完全なランタイムクラス名を使用し、Swift クラスでは NSStringFromClass(HomeViewController.self) を使用して正確な名前を取得し、モジュール名のプレフィックスの欠落を避けてください。部分文字列、正規表現、サブクラスには一致せず、viewTrackingHandler が返すカスタム View Name も使用しません。除外されたコントローラーでも RUM View は収集されます。ライフサイクルメソッドをオーバーライドする場合は、対応する super メソッドを呼び出してください。

SwiftUI View の自動収集(実験的)

SwiftUI View の自動収集では、まず SDK がページ名を抽出し、その後 FTRumConfig.swiftUIViewTrackingHandler によって RUM View を生成するかどうかを決定します。デフォルトハンドラーを使用して直接有効にするか、FTSwiftUIViewTrackingHandler を実装して、抽出された SwiftUI View Name をフィルタリングし、送信する View Name と属性をカスタマイズできます。

特定の SwiftUI View でページ名とライフサイクルを明示的に制御する場合は、SwiftUI View 手動収集を参照してください。

注意:SwiftUI View の自動収集は現在実験的機能であり、関連 API と収集動作は今後のバージョンで変更される可能性があります。

使用前に FTRumConfig.enableTraceUserView を有効にし、FTRumConfig.swiftUIViewTrackingHandler を設定する必要があります。

rumConfig.enableTraceUserView = YES;
rumConfig.swiftUIViewTrackingHandler = [FTDefaultSwiftUIViewTrackingHandler new];
rumConfig.enableTraceUserView = true
rumConfig.swiftUIViewTrackingHandler = FTDefaultSwiftUIViewTrackingHandler()

SwiftUI View の収集ルールをカスタマイズする場合は、FTSwiftUIViewTrackingHandler を実装できます。FTRUMView を返すとその SwiftUI View を収集し、nil を返すとスキップします。

rumConfig.swiftUIViewTrackingHandler = [CustomSwiftUIViewTracker new];

@interface CustomSwiftUIViewTracker : NSObject <FTSwiftUIViewTrackingHandler>
@end

@implementation CustomSwiftUIViewTracker
- (nullable FTRUMView *)rumViewForExtractedViewName:(NSString *)extractedViewName {
    if ([extractedViewName isEqualToString:@"HomeView"]) {
        return [[FTRUMView alloc] initWithViewName:@"main_home" property:@{@"page_type": @"home"}];
    }
    return nil;
}
@end
rumConfig.swiftUIViewTrackingHandler = CustomSwiftUIViewTracker()

class CustomSwiftUIViewTracker: NSObject, FTSwiftUIViewTrackingHandler {
    func rumView(forExtractedViewName extractedViewName: String) -> FTRUMView? {
        if extractedViewName == "HomeView" {
            return FTRUMView(
                viewName: "main_home",
                property: ["page_type": "home"]
            )
        }
        return nil
    }
}

View 時間メトリクス

SDK 1.6.8 以降でサポートされています

既存の View と関連する Action / Resource の収集データがある場合、SDK は次のオプションメトリクスを自動計算します。個別の有効化スイッチは不要です。手動収集では、実際のイベント境界で対応する開始/終了 API を呼び出してください。

メトリクス 単位 定義とデフォルトルール
interaction_to_next_view_time(INV) ナノ秒 現在の View の開始時刻から、同一 Session 内で直前の View 内にある直近の条件を満たす Action の開始時刻を減算した値。デフォルトでは click のみに一致し、間隔は [0,3秒] である必要があります
network_settled_time(TNS) ナノ秒 初回ネットワークリクエストのうち最も遅い有効な終了時刻から、現在の View の開始時刻を減算した値。デフォルトでは、初回リクエストは View 開始後 [0,100ms] 以内に開始されたものとします

ここでの起点は RUM View の開始 であり、loading_time の読み込み開始点ではありません。TNS の 100ms はリクエスト開始のフィルタリング範囲であり、「ネットワークが 100ms アイドルになるのを待つ」ものではありません。初回リクエストの完了済みバッチが先に結果を生成でき、後続の条件を満たすバッチが完了すると同じ View の値が更新される可能性があります。

条件を満たす Action がない場合、有効な初回リクエスト区間がない場合、データがフィルタリングされた場合などには、対応するメトリクスは表示されません。欠落を 0 と見なさないでください。有効なゼロ所要時間は送信できます。Session をまたぐ場合、INV は関連付けられません。フォールバック View(合成された起動 View やバックグラウンド View など)では、これら 2 つのメトリクスは生成されません。TNS の計算区間がバックグラウンドに跨る場合、または利用可能な状態履歴がない場合、値は生成されません。

RUM の初期化前にデフォルトルールの時間しきい値を調整できます。コンストラクタ引数の単位はすべてナノ秒です:

rumConfig.nextViewActionPredicate = [[FTRUMTimeBasedNextViewActionPredicate alloc]
    initWithMaxTimeNs:5000000000LL]; // click、最大 5 秒
rumConfig.networkSettledResourcePredicate = [[FTRUMTimeBasedNetworkSettledPredicate alloc]
    initWithThresholdNs:200000000LL]; // View 開始後 200ms 以内に開始されたリクエスト
rumConfig.nextViewActionPredicate = FTRUMTimeBasedNextViewActionPredicate(maxTimeNs: 5_000_000_000)
rumConfig.networkSettledResourcePredicate = FTRUMTimeBasedNetworkSettledPredicate(thresholdNs: 200_000_000)

2 つのプロパティの nil の動作は異なります:nextViewActionPredicate = nil は INV を無効にします。networkSettledResourcePredicate = nil はデフォルトの 100ms ルールに戻します。INV 設定 API は App Extension をサポートしていません。

Action 名、次のページ、リクエスト URL でフィルタリングする場合は、公開プロトコルを実装できます。次の例では、Checkout へ遷移する open_checkout click のみに一致し、指定した API リクエストのみを初回リクエストとして扱います:

@interface CheckoutTimingRules : NSObject <FTRUMNextViewActionPredicate, FTRUMNetworkSettledResourcePredicate>
@end

@implementation CheckoutTimingRules
- (BOOL)isLastAction:(FTRUMNextViewActionParams *)params {
    return [params.actionType isEqualToString:@"click"] &&
        [params.actionName isEqualToString:@"open_checkout"] &&
        [params.nextViewName isEqualToString:@"Checkout"] &&
        params.timeToNextViewNs >= 0 && params.timeToNextViewNs <= 3000000000LL;
}
- (BOOL)isInitialResource:(FTRUMNetworkSettledResourceParams *)params {
    return [params.resourceURL hasPrefix:@"https://api.example.com/"] &&
        params.timeSinceViewStartNs >= 0 && params.timeSinceViewStartNs <= 100000000LL;
}
@end
final class CheckoutTimingRules: NSObject, FTRUMNextViewActionPredicate, FTRUMNetworkSettledResourcePredicate {
    func isLastAction(_ params: FTRUMNextViewActionParams) -> Bool {
        params.actionType == "click" && params.actionName == "open_checkout" &&
            params.nextViewName == "Checkout" &&
            params.timeToNextViewNs >= 0 && params.timeToNextViewNs <= 3_000_000_000
    }

    func isInitialResource(_ params: FTRUMNetworkSettledResourceParams) -> Bool {
        (params.resourceURL?.hasPrefix("https://api.example.com/") ?? false) &&
            params.timeSinceViewStartNs >= 0 && params.timeSinceViewStartNs <= 100_000_000
    }
}

// RUM の初期化前に設定します。
let rules = CheckoutTimingRules()
rumConfig.nextViewActionPredicate = rules
rumConfig.networkSettledResourcePredicate = rules

コールバックは RUM のバックグラウンドキューで実行されるため、高速かつスレッドセーフで、同じ入力に対して一貫した結果を返す必要があります。UI へのアクセス、ネットワークリクエストの発行、ブロッキング待機は行えません。resourceURL は空になる可能性があります。ルールは実際に収集されフィルタリングを通過したデータのみを選択でき、新しい Action や Resource を追加収集することはありません。

Action

設定 FTRumConfig.enableTraceUserAction = YES を有効にする必要があります。

SDK の初期化タイミング

基本 SDK はメインスレッドで初期化してから RUM を起動することを推奨します。UIKit では application:didFinishLaunchingWithOptions: メソッドの先頭、SwiftUI では App.init() 内に配置します。完全な例はクイックスタートを参照してください。

起動所要時間のフェーズ

enableTraceUserAction を有効にすると、SDK は初回起動(launch_cold / launch_warm)とホット起動(launch_hot)を自動収集します。同じプロセスで初回起動は 1 回だけ送信されます。shutdown 後に再初期化しても、ホット起動の収集は継続されます。

フェーズ 区間
Pre Runtime Init app_pre_runtime_init_time:プロセス作成からランタイム初期化(SDK の +load)まで。
Runtime Init to Pre Main Initializers app_runtime_init_time:ランタイム初期化から main 前初期化(SDK の constructor)まで。
UIKit Init app_uikit_init_time:main 前初期化から基本 SDK の起動まで。
Application Init app_application_init_time:基本 SDK の起動から UIApplicationDidFinishLaunchingNotification 通知の受信まで。
Initial Frame Render app_first_frame_init_time:起動完了通知から最初の CADisplayLink コールバックに対応するフレーム時刻まで。

フェーズフィールドの start、duration はどちらもナノ秒で、それぞれ起動 Action の time に対するオフセットとフェーズの所要時間を表します。初回アクティブ化より後に収集を開始した場合、初回アクティブ化を終点とし、最後の 3 フェーズは出力されません。

起動プリウォームの識別と所要時間のキャリブレーション

SDK 1.6.9 以降でサポートされています。iOS のみに適用されます。

iOS では、ユーザーがアプリを開く前にプロセスを作成し、起動準備の一部を事前に完了する場合があります。この仕組みはプリウォーム(Prewarm)と呼ばれます。プリウォーム後から実際の起動までの待機により、計測される起動所要時間が過大になる可能性があります。

SDK はシステムのプリウォームを識別し、起動所要時間をキャリブレーションします。また、RUM の起動前に rumConfig.launchPrewarmInterval = 1500 を設定すると、カスタム所要時間推定を有効にできます。単位はミリ秒で、デフォルトは 0(カスタム推定は無効)です。処理ルールは次のとおりです:

  • システムのプリウォーム:自動識別し、pre-runtime と runtime の 2 フェーズを無視して constructor から計算します。上記の設定には影響されません。
  • 手動検出区間がしきい値を超過:最初の 3 フェーズを無視し、SDK の初期化から計算します。
  • pre-runtime がしきい値を超過:手動ルールに該当しない場合、pre-runtime のみを無視し、SDK の +load から計算します。

カスタム判定では、しきい値より厳密に大きいという条件を使用します。キャリブレーション後、Action の time、合計 duration、フェーズ start は新しい起点を使用します。有効な起点を取得できない場合は元の所要時間を保持します。プリウォーム起動は launch_warm として送信されます。正の値を設定した場合、prewarm_type で system / custom を区別します。

手動検出を補足する場合は、ネイティブライフサイクルに次を追加します:

  1. main のエントリで [FTSDKAgent prewarmCheckStart] を呼び出します。
  2. application:willFinishLaunchingWithOptions: メソッドの先頭で [FTSDKAgent prewarmCheckEnd] を呼び出します。

Swift ではそれぞれ FTSDKAgent.prewarmCheckStart()、FTSDKAgent.prewarmCheckEnd() を呼び出します。2 つの呼び出しは SDK の初期化前に完了する必要があります。

アプリが main のエントリから application:willFinishLaunchingWithOptions: コールバックまでの間に独自のビジネスロジックを追加している場合は、上記の手動検出インターフェースを使用しないでください。ビジネス実行時間をプリウォーム待機と誤判定し、起動所要時間を誤って切り詰める可能性があります。

所要時間推定は、実際の低速起動をプリウォームと誤判定する可能性があります。有効化前後のデータを比較することを推奨します。キャリブレーション結果は、ユーザーが体感する起動所要時間とは同一ではありません。

Action のカスタム収集

rumConfig.actionTrackingHandler = [CustomActionTracker new];

#import "FTDefaultActionTrackingHandler.h"

// プロトコル実装例
// iOS 環境では `FTUIPressRUMActionsHandler` プロトコルに準拠する必要があります
// tvOS 環境では `FTUITouchRUMActionsHandler` プロトコルに準拠する必要があります。
@interface CustomActionTracker : NSObject <FTUIPressRUMActionsHandler,FTUITouchRUMActionsHandler>
// SDK デフォルトの Action 収集ルールが必要な場合のみ追加
@property (nonatomic, strong) FTDefaultActionTrackingHandler defaultHandler;
@end
@implementation CustomActionTracker

// SDK デフォルトの Action 収集ルールが必要な場合のみ追加
-(FTDefaultActionTrackingHandler *)defaultHandler{
    if (!_defaultHandler) {
        _defaultHandler = [FTDefaultActionTrackingHandler new];
    }
    return _defaultHandler;
}

// iOS と tvOS の両方で実装が必要なプロトコルメソッド
- (nullable FTRUMAction *)rumLaunchActionWithLaunchType:(FTLaunchType)type {
    if(type == FTLaunchCold){
      return [[FTRUMAction alloc]initWithActionName:@"cold"];
    }
    // nil を返すと追跡をスキップ
    return nil;
}

// iOS 環境で実装が必要なプロトコルメソッド
-(nullable FTRUMAction *)rumActionWithTargetView:(UIView *)targetView{
    if (view.accessibilityIdentifier){
       return [[FTRUMAction alloc] initWithActionName:view.accessibilityIdentifier];
    }

     // 一部の Action をカスタマイズした後、残りは SDK デフォルトの収集ルールを使用します(デフォルトハンドラーの処理結果を返します)
    return [self.defaultHandler rumActionWithTargetView:targetView];

    // nil を返すと追跡をスキップ
    return nil;
}
// tvOS 環境で実装が必要なプロトコルメソッド
- (nullable FTRUMAction *)rumActionWithPressType:(UIPressType)type targetView:(UIView *)targetView{
    if (type == UIPressTypeSelect && view.accessibilityIdentifier){
       return [[FTRUMAction alloc] initWithActionName:view.accessibilityIdentifier];
    }

    // 一部の Action をカスタマイズした後、残りは SDK デフォルトの収集ルールを使用します(デフォルトハンドラーの処理結果を返します)
    return [self.defaultHandler rumActionWithPressType:type targetView:targetView];

        // nil を返すと追跡をスキップ
    return nil;
}
@end
rumConfig.actionTrackingHandler = CustomActionTracker()

// プロトコル実装例
// iOS 環境では `FTUIPressRUMActionsHandler` プロトコルに準拠する必要があります
// tvOS 環境では `FTUITouchRUMActionsHandler` プロトコルに準拠する必要があります。
class CustomActionTracker: NSObject, FTUIPressRUMActionsHandler, FTUITouchRUMActionsHandler {

    // SDK デフォルトの Action 収集ルールが必要な場合のみ追加
    lazy var defaultHandler: FTDefaultActionTrackingHandler = {
        FTDefaultActionTrackingHandler()
    }()

    // iOS と tvOS の両方で実装が必要なプロトコルメソッド
    func rumLaunchAction(with type: FTLaunchType) -> FTRUMAction? {
        if type == .cold {
            return FTRUMAction(actionName: "cold")
        }
        // nil を返すと追跡をスキップ
        return nil
    }

    // iOS 環境で実装が必要なプロトコルメソッド
    func rumAction(withTargetView targetView: UIView) -> FTRUMAction? {
        if let identifier = targetView.accessibilityIdentifier {
            return FTRUMAction(actionName: identifier)
        }

        // 一部の Action をカスタマイズした後、残りは SDK デフォルトの収集ルールを使用します(デフォルトハンドラーの処理結果を返します)
        return defaultHandler.rumAction(withTargetView: targetView)

        // nil を返すと追跡をスキップ
        return nil 
    }

    // tvOS 環境で実装が必要なプロトコルメソッド
    func rumAction(with pressType: UIPress.PressType, targetView: UIView) -> FTRUMAction? {
        if pressType == .select, let identifier = targetView.accessibilityIdentifier {
            return FTRUMAction(actionName: identifier)
        }

        // 一部の Action をカスタマイズした後、残りは SDK デフォルトの収集ルールを使用します(デフォルトハンドラーの処理結果を返します)        
        return defaultHandler.rumAction(with: pressType, targetView: targetView)

        // nil を返すと追跡をスキップ
        return nil
    }
}

Resource

設定 FTRUMConfig.enableTraceUserResource = YES を有効にするか、URLSession Delegate の転送による Network のカスタム収集が必要です。

URL による収集フィルタリング

rumConfig.resourceUrlHandler = ^(NSURL *url){
        // YES を返すと収集しない;NO を返すと収集する
        if ([url.host isEqualToString:@"example.com"]) {
            return YES;
        }
        return NO;
};
rumConfig.resourceUrlHandler = { url in 
     // true を返すと収集しない;false を返すと収集する
     return url.host == "example.com"
}

カスタム属性の追加

プロパティプロバイダーのクロージャを設定すると、RUM Resource に付加する追加属性を返せます。

たとえば、HTTP リクエスト body を RUM Resource に追加したい場合があります:

rumConfig.resourcePropertyProvider = ^NSDictionary *_Nullable(NSURLRequest *request, NSURLResponse *response,NSData *data, NSError *error) {
     NSString *body = @"";
     if (request.HTTPBody) {
        body = [[NSString alloc] initWithData:httpBody encoding:NSUTF8StringEncoding] ?: @"";
     }
     return @{@"request_body": body};
 }
rumConfig.resourcePropertyProvider = { request, response, data, error in
   let body = request.httpBody.flatMap { String(data: $0, encoding: .utf8) } ?? ""
   return ["request_body": body]
  }

ネットワークエラーのフィルタリング

ネットワークリクエストでエラーが発生すると、RUM にタイプ network_error の Error データが生成されます。task.cancel など一部の URLSession ローカルエラーはユーザープログラムにおける正常なロジックであり、エラーデータではありません。このような場合は sessionTaskErrorFilter コールバックでインターセプトしてフィルタリングできます。インターセプトする場合は YES、しない場合は NO を返します。インターセプトすると、RUM Error はそのエラーを収集しません。

rumConfig.sessionTaskErrorFilter = ^BOOL(NSError * _Nonnull error){
    return error.code == NSURLErrorCancelled;
}; 
rumConfig.sessionTaskErrorFilter = { error in
   return (error as? URLError)?.code == .cancelled
}

Error

FTRumConfig.issueDataProvider を使用すると、SDK が Crash または ANR を自動収集する際に、今回の例外情報に基づいて対応する RUM Error にビジネスフィールド(ビジネスシーン、機能モジュール、実験グループなど)を追加できます。この機能は SDK 1.6.7 以降でサポートされています。

issueDataProvider は自動収集された Crash と ANR にのみフィールドを追加し、Crash または ANR モニタリングを有効化するものではありません。使用前に、収集対象に応じて enableTrackAppCrash または enableTrackAppANR を有効にする必要があります。

設定

RUM の起動前に issueDataProvider を設定してください。RUM 起動後に元の FTRumConfig を変更しても、現在実行中の Provider は変更されません。

FTRumConfig *rumConfig = [[FTRumConfig alloc] initWithAppid:appid];
rumConfig.enableTrackAppCrash = YES;
rumConfig.enableTrackAppANR = YES;

// RUM の起動前に読み取り専用のビジネススナップショットを準備し、コールバック内で時間のかかる処理を実行しないようにします。
NSDictionary<NSString *, id> *businessContext = @{
    @"business_scene": @"checkout",
    @"release_channel": @"app_store"
};

rumConfig.issueDataProvider = ^NSDictionary<NSString *, id> * _Nullable(FTIssueInfo *issue) {
    NSMutableDictionary<NSString *, id> *fields = [businessContext mutableCopy];
    fields[@"issue_category"] =
        issue.category == FTIssueCategoryCrash ? @"crash" : @"anr";
    fields[@"historical_issue"] = @(issue.isHistorical);

    if (issue.threadName.length > 0) {
        fields[@"issue_thread_name"] = issue.threadName;
    }
    return fields;
};

[[FTMobileAgent sharedInstance] startRumWithConfigOptions:rumConfig];
let rumConfig = FTRumConfig(appid: appid)
rumConfig.enableTrackAppCrash = true
rumConfig.enableTrackAppANR = true

// RUM の起動前に読み取り専用のビジネススナップショットを準備し、コールバック内で時間のかかる処理を実行しないようにします。
let businessContext: [String: Any] = [
    "business_scene": "checkout",
    "release_channel": "app_store"
]

rumConfig.issueDataProvider = { issue in
    var fields = businessContext
    fields["issue_category"] =
        issue.category == .crash ? "crash" : "anr"
    fields["historical_issue"] = issue.isHistorical

    if let threadName = issue.threadName, !threadName.isEmpty {
        fields["issue_thread_name"] = threadName
    }
    return fields
}

FTMobileAgent.sharedInstance().startRum(withConfigOptions: rumConfig)

Provider は条件を満たす自動収集 Error ごとに 1 回同期的に呼び出されます。nil または空の辞書を返すと、今回はカスタムフィールドを追加しないことを示します。

FTIssueInfo

コールバック引数 FTIssueInfo は読み取り専用オブジェクトで、現在処理中の Crash または ANR を表します。

属性 型 説明
category FTIssueCategory 例外カテゴリ:FTIssueCategoryCrash / Swift .crash は Crash、FTIssueCategoryANR / Swift .anr は ANR を表します
errorType NSString 対応する RUM Error のタイプ。Crash は ios_crash、ANR は anr_error
message NSString Error メッセージ。取得できない場合は nil
stack NSString 例外スタック
occurredAtNanoseconds long long 例外の発生日時。Unix タイムスタンプ、単位はナノ秒
appState NSString 対応する RUM Error で使用されるアプリ状態
threadName NSString 例外スレッド名。取得できない場合は nil
historical BOOL 永続化データから例外を復元したかどうか。Objective-C の getter は isHistorical、Swift では isHistorical を使用します

自動収集シナリオにおける category、errorType、historical の対応関係は次のとおりです:

シナリオ category errorType historical
Crash レポートがアプリの次回起動時に復元される Crash ios_crash YES
現在のプロセスで復旧した ANR ANR anr_error NO
前回のプロセスの Watchdog ANR がアプリの次回起動時に復元される ANR anr_error YES

historical が YES の場合、FTIssueInfo の例外時刻、スタック、アプリ状態は永続化済みの例外データに由来しますが、Provider はアプリが復旧してレポートを処理するときに初めて実行されます。そのため、Provider 実行時に直接読み取ったビジネス状態は現在のプロセスに属し、例外発生時の状態とは限りません。例外発生時のビジネス情報を関連付ける必要がある場合は、事前に永続化し、RUM の起動前にスレッドセーフなメモリスナップショットとして読み込んでください。Provider 内でディスク読み取りを行わないでください。

カスタムフィールドのルール

Provider が返すフィールドは、対応する RUM Error の fields に書き込まれ、tags には書き込まれません。フィールドは次のルールを満たす必要があります:

  • Key は空でない文字列である必要があり、UTF-8 エンコード長は 100 バイトを超えてはなりません。
  • Value は文字列、ブール値、整数、有限の浮動小数点数のみをサポートします。配列、辞書、NSNull、カスタムオブジェクトはサポートしません。
  • 文字列 Value の UTF-8 エンコード長は 4096 バイトを超えてはなりません。
  • SDK は返された辞書の先頭 50 項目までをスキャンします。無効なフィールドもスキャン数に含まれます。辞書の走査順序は固定ではないため、50 項目以内を返すことを推奨します。
  • 受け入れられたすべてのフィールドの推定合計サイズは 25 KiB を超えてはなりません。
  • error. または error_ で始まる Key は無視されます。
  • カスタムフィールドが SDK 既存の tag または field と名前が重複する場合、SDK のフィールドが優先されます。

ルールに適合しないフィールドは無視され、元の Crash または ANR Error の収集と送信を妨げることはありません。カスタムフィールドは RUM データとともにアップロードされるため、パスワードや Token などの機密情報を含めないでください。

コールバック実行要件

issueDataProvider はメインスレッド以外で並行または再入して実行される可能性があります。コールバックは次の要件を満たす必要があります:

  • スレッドセーフに実装し、準備済みの不変データまたはメモリスナップショットを優先して読み取ってください。
  • 10 ms 以内に返すことを推奨します。
  • UI を操作せず、ネットワークまたはディスク I/O を実行しないでください。
  • スレッド切り替え、同期ディスパッチ、長時間のロック待機などのブロッキング操作を行わないでください。

実行時間が 50 ms を超えると、SDK は遅いコールバックのデバッグログを出力する場合がありますが、元の RUM Error の処理は継続します。

適用範囲

issueDataProvider は SDK が自動収集する Crash、現在のプロセスで復旧した ANR、前回のプロセスの Watchdog ANR に適用されます。次のデータはこの Provider をトリガーしません:

  • addError などのインターフェースで手動追加した Error
  • Resource / Network Error
  • WebView Error
  • Long Task
  • データアップロードまたは再試行のプロセス

カスタム TraceHeader

FTTraceConfig.traceInterceptor でグローバルに設定するか、URLSession レベルのカスタム Trace を使用できます。以下では w3c-traceContext を例に説明します。

FTTraceConfig *traceConfig = [[FTTraceConfig alloc]init];
   traceConfig.traceInterceptor = ^FTTraceContext * _Nullable(NSURLRequest *request) {
    // 1. ビジネス側でカスタマイズした traceId を取得
    NSString *replaceTrace = [request.allHTTPHeaderFields valueForKey:CUSTOM_TRACE_HEADER];

    // 2. SDK 標準の W3C traceparent リクエストヘッダーを取得
    NSDictionary *traceHeaders = [[FTExternalDataManager sharedManager] getTraceHeaderWithUrl:request.URL];
    NSString *traceParentStr = traceHeaders[FT_NETWORK_TRACEPARENT_KEY];

    // 3. W3C traceparent 形式を解析し、インデックス 1 の traceId を置換
    NSArray *traceComponents = [traceParentStr componentsSeparatedByString:@"-"];
    if (traceComponents.count != 4) {
        return nil;
    }
    NSMutableArray *newComponents = [traceComponents mutableCopy];
    newComponents[1] = replaceTrace;
    NSString *newTraceParent = [newComponents componentsJoinedByString:@"-"];

    // 4. カスタムトレーシングコンテキストを組み立てて返す
    FTTraceContext *context = [FTTraceContext new];
    context.traceHeader = @{FT_NETWORK_TRACEPARENT_KEY:newTraceParent};
    context.traceId = replaceTrace;
    // SDK が生成した spanId を保持(インデックス 2 の固定位置)
    context.spanId = newComponents[2];
    return context;
};
let traceConfig = FTTraceConfig()
traceConfig.traceInterceptor = { (request: URLRequest) -> FTTraceContext? in
        // 1. ビジネス側でカスタマイズした traceId を取得
        guard let replaceTrace = request.allHTTPHeaderFields?[CUSTOM_TRACE_HEADER] else {
            return nil
        }

        // 2. SDK 標準の W3C traceparent リクエストヘッダーを取得
        guard let traceHeaders = FTExternalDataManager.shared().getTraceHeader(with: request.url!), let traceParentStr = traceHeaders[FT_NETWORK_TRACEPARENT_KEY] as? String else {
            return nil
        }

        // 3. W3C traceparent 形式を解析し、インデックス 1 の traceId を置換
        let traceComponents = traceParentStr.components(separatedBy: "-")
        guard traceComponents.count == 4 else {
            return nil
        }
        var newComponents = traceComponents
        newComponents[1] = replaceTrace
        let newTraceParent = newComponents.joined(separator: "-")

        // 4. カスタムトレーシングコンテキストを組み立てて返す
        let context = FTTraceContext()
        context.traceHeader = [FT_NETWORK_TRACEPARENT_KEY: newTraceParent]
        context.traceId = replaceTrace
        // SDK が生成した spanId を保持(インデックス 2 の固定位置)
        context.spanId = newComponents[2]
        return context
    }

フィードバック

このページは役に立ちましたか?