데이터 수집 사용자 정의 규칙¶
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로 설정하면 자동 로딩 소요 시간 수집을 전역적으로 끄며, 수동으로 로딩 소요 시간을 보고하는 기능에는 영향을 주지 않습니다.
특정 컨트롤러만 제외하려면 전역 스위치를 켠 상태로 두고 viewLoadingTimeClassNameExcludes를 설정하세요. 예를 들어 프로젝트의 HomeViewController를 제외하려면 다음과 같습니다.
클래스 이름 배열의 기본값은 비어 있습니다. 일치 여부는 대소문자를 구분하는 전체 런타임 클래스 이름으로 판단하며, 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를 설정해야 합니다.
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 시작 시간에서 동일 세션의 바로 이전 View 내 가장 최근 적격 Action 시작 시간을 뺀 값입니다. 기본적으로 click만 일치하며, 간격은 [0,3초] 이내여야 합니다. |
network_settled_time(TNS) |
나노초 | 초기 네트워크 요청 중 가장 늦은 유효 종료 시간에서 현재 View 시작 시간을 뺀 값입니다. 기본적으로 초기 요청은 View 시작 후 [0,100ms] 내에 시작됩니다. |
여기서 시작점은 RUM View 시작이며 loading_time의 로딩 시작점이 아닙니다. TNS의 100ms는 요청 시작을 선별하는 범위이며, "네트워크가 100ms 동안 유휴 상태가 되기를 기다리는 것"이 아닙니다. 초기 요청 중 완료된 배치가 먼저 결과를 생성할 수 있으며, 이후 적격 배치가 완료되면 동일 View의 값이 업데이트될 수 있습니다.
적격 Action이 없거나 유효한 초기 요청 구간이 없거나 데이터가 필터링된 경우 해당 지표는 나타나지 않으며, 누락을 0으로 간주해서는 안 됩니다. 유효한 0 소요 시간은 보고할 수 있습니다. 세션을 넘는 경우 INV를 연결하지 않으며, 폴백 View(예: 합성된 시작 또는 백그라운드 View)는 이 두 지표를 생성하지 않습니다. TNS 계산 구간이 백그라운드로 넘어가거나 사용 가능한 상태 이력이 없으면 값을 생성하지 않습니다.
RUM 초기화 전에 기본 규칙의 시간 임계값을 조정할 수 있으며, 생성자 매개변수의 단위는 모두 나노초입니다.
두 속성의 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
// RUM 초기화 전에 설정합니다.
CheckoutTimingRules *rules = [[CheckoutTimingRules alloc] init];
rumConfig.nextViewActionPredicate = rules;
rumConfig.networkSettledResourcePredicate = rules;
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)을 자동으로 수집합니다. 동일 프로세스에서는 초기 시작을 한 번만 보고하며, 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 기준 오프셋과 단계 소요 시간을 나타냅니다. 최초 활성화보다 늦게 수집을 시작한 경우 최초 활성화를 종료 시점으로 하며 마지막 세 단계는 출력하지 않습니다.
시작 프리웜 식별 및 소요 시간 보정¶
SDK 1.6.9부터 지원하며 iOS에만 적용됩니다.
iOS는 사용자가 앱을 열기 전에 프로세스를 생성하고 일부 시작 준비를 미리 완료할 수 있으며, 이러한 메커니즘을 프리웜(Prewarm)이라고 합니다. 프리웜 이후 실제 시작까지의 대기 시간 때문에 측정된 시작 소요 시간이 더 크게 집계될 수 있습니다.
SDK는 시스템 프리웜을 식별하고 시작 소요 시간을 보정합니다. 또한 RUM 시작 전에 rumConfig.launchPrewarmInterval = 1500을 설정해 사용자 정의 소요 시간 추론을 활성화할 수 있습니다. 단위는 밀리초이며 기본값은 0(사용자 정의 추론 비활성화)입니다. 처리 규칙은 다음과 같습니다.
- 시스템 프리웜: 자동으로 식별하며 pre-runtime, runtime 두 단계를 무시하고 constructor부터 계산하며, 위 구성의 제어를 받지 않습니다.
- 수동 감지 구간이 임계값 초과: 앞의 세 단계를 무시하고 SDK 초기화부터 계산합니다.
- pre-runtime이 임계값 초과: 수동 규칙에 해당하지 않을 때 pre-runtime만 무시하고 SDK
+load부터 계산합니다.
사용자 정의 판단은 임계값보다 엄격히 큰 조건을 사용합니다. 보정 후 Action의 time, 전체 duration 및 단계 start는 새 시작점을 사용합니다. 유효한 시작점을 얻을 수 없으면 원래 소요 시간을 유지합니다. 프리웜 시작은 launch_warm으로 보고되며, 구성값이 양수이면 prewarm_type이 system / custom을 구분합니다.
수동 감지를 보완하려면 네이티브 생명주기에 다음을 추가하세요.
main진입점에서[FTSDKAgent prewarmCheckStart]를 호출합니다.application:willFinishLaunchingWithOptions:메서드 시작 부분에서[FTSDKAgent prewarmCheckEnd]를 호출합니다.
Swift의 대응 호출은 FTSDKAgent.prewarmCheckStart(), FTSDKAgent.prewarmCheckEnd()입니다. 두 호출은 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 기준 수집 필터링¶
사용자 정의 속성 추가¶
속성 제공자 클로저를 설정하면 RUM Resource에 추가할 다른 속성을 반환할 수 있습니다.
예를 들어 RUM Resource에 HTTP 요청 body를 추가할 수 있습니다.
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};
}
네트워크 오류 필터링¶
네트워크 요청에서 오류가 발생하면 RUM에 network_error 유형의 Error 데이터가 생성됩니다. 일부 URLSession 로컬 오류(예: task.cancel)는 사용자 프로그램의 정상 로직이며 오류 데이터가 아닙니다. 이 경우 sessionTaskErrorFilter 콜백으로 가로채 필터링할 수 있습니다. 가로채려면 YES, 가로채지 않으려면 NO를 반환하며, 가로챈 후에는 RUM-Error가 해당 오류를 수집하지 않습니다.
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마다 동기적으로 한 번 호출됩니다. 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는 메인 스레드가 아닌 곳에서 동시에 또는 재진입하여 실행될 수 있습니다. 콜백은 다음 요구 사항을 충족해야 합니다.
- 스레드 안전성을 보장하고, 미리 준비된 불변 데이터 또는 메모리 스냅샷을 우선 읽으세요.
- 10ms 이내에 반환하는 것이 좋습니다.
- UI를 조작하지 말고 네트워크 또는 디스크 I/O를 수행하지 마세요.
- 스레드 전환, 동기 디스패치, 장시간 잠금 대기 등 차단 작업을 수행하지 마세요.
실행 시간이 50ms를 초과하면 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
}