콘텐츠로 이동

문제 해결

SDK 초기화 예외 검증

디버그 환경에서 Guance SDK를 구성하고 애플리케이션을 처음 실행한 후 Xcode의 디버거 콘솔을 확인하세요. SDK는 assertion을 사용하여 여러 구성 항목의 올바른지를 검사하며, 구성이 잘못된 경우 크래시가 발생하고 관련 경고를 출력합니다.

예: SDK를 구성할 때 datakit metrics 쓰기 주소를 설정하지 않으면 프로그램이 크래시되고 콘솔에 경고⚠️가 출력됩니다.

*** Assertion failure in +[FTMobileAgent startWithConfigOptions:], FTMobileAgent.m:53
*** Terminating app due to uncaught exception 'NSInternalInconsistencyException', reason: '请设置 datakit metrics 写入地址'

Debug 디버그 활성화

디버그 환경에서는 FTMobileConfig의 설정 항목 enableSDKDebugLog = YES를 활성화하고, 릴리스 환경에서는 비활성화할 것을 권장합니다. SDK 디버그 로그는 [FTLog] 접두사로 표시되며, [FTLog]로 필터링할 수 있습니다.

참고: scheme에 OS_ACTIVITY_MODE=disable이 설정된 경우 SDK 디버그 로그가 정상적으로 출력되지 않으므로, 디버그 시에는 이 설정을 끌 것을 권장합니다.

릴리스 버전 배포 시에는 Debug 디버그를 끌 것을 권장합니다

로그 예시

데이터 동기화

//다음은 정상 동기화 로그입니다
[FTLog][INFO] -[FTTrackDataManger flushWithEvents:type:] [line 143] ↵
                                                开始上报事件(本次上报事件数:2)
[FTLog][INFO] -[FTRequestLineBody getRequestBodyWithEventArray:] [line 149]
Upload Datas Type:RUM
Line RequestDatas:
...... datas ......
[FTLog][INFO] -[FTTrackDataManger flushWithEvents:type:]_block_invoke [line 157] ↵
                                                Upload Response statusCode : 200

1.3.10 버전 이전에는 Upload Response statusCode : 200이 출력되지 않습니다. 콘솔에 오류 로그가 있는지 확인할 수 있으며, 오류 로그가 없으면 업로드가 성공한 것입니다.

오류 로그: Network failure: ...... 또는 服务器异常 稍后再试 ......

1.5.16 버전 이후부터는 로그에서 [NETWORK]를 검색하여 데이터 동기화 관련 모든 로그를 확인할 수 있습니다.

SDK 내부 로그를 캐시 파일로 변환

// 기본 경로: 1.4.11-1.4.12 /Library/Caches/FTLogs/FTLog xxxx-xx-xx--xx/xx/xx/xxx.log
//         >= 1.4.13 /Documents/FTLogs/FTLog.log

// >= 1.4.11
 [[FTLog sharedInstance] registerInnerLogCacheToLogsDirectory:nil fileNamePrefix:nil];

// >= 1.4.13
//  방법 1: 기본 경로
 [[FTLog sharedInstance] registerInnerLogCacheToDefaultPath]
//  방법 2: 지정 경로
 NSString *filePath = [NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES).firstObject 
stringByAppendingPathComponent:@"ExampleName.log"];
 [[FTLog sharedInstance] registerInnerLogCacheToLogsFilePath:filePath];

내부 로그의 완전성을 위해 SDK 초기화 전에 이 구성을 설정해야 합니다

SDK가 정상적으로 실행되지만 데이터가 없는 경우

  • Datakit가 정상적으로 실행되는지 확인

  • SDK 업로드 주소 datakitUrl 또는 datawayUrl이 올바르게 설정되었는지 확인하고 올바르게 초기화합니다. 디버그 모드에서 로그를 확인하여 업로드 문제를 판단합니다.

  • datakit이 해당 워크스페이스에 데이터를 업로드하는지, 오프라인 상태인지 확인합니다. Guance에 로그인하여 「인프라」에서 확인할 수 있습니다.

데이터 수집 성공 확인

Logger

FTLoggerConfig의 설정 항목 enableCustomLog = YES를 지정하여 커스텀 로그 수집 및 보고를 활성화합니다.

SDK가 로그를 수집하면 Xcode 디버거 콘솔에서 SDK 디버그 로그를 확인할 수 있습니다.

[FTLog][INFO] -[FTRecordModel initWithSource:op:tags:fields:tm:] [line 36] write data = {
    op = Logging;
    opdata =     {
        fields =         {
            message = "xxxxx采集到的日志内容XXXXX";
        };
        source = "df_rum_ios_log";
        tags =         {
             ...... 
        }
   }
}

op = Logging; 이 표시되면 Logger 기능이 정상적으로 활성화되어 데이터가 성공적으로 수집된 것입니다.

RUM

SDK 버전이 1.4.14 미만인 경우, Resource 데이터와 Action 데이터(launch action 제외)는 View에 바인딩되므로 View가 수집된 상태에서만 정상적으로 수집할 수 있습니다.

View 수집: FTRumConfig의 설정 항목 enableTraceUserView = YES를 지정하여 자동 수집을 활성화하거나 -startViewWithName으로 수동 수집합니다.

Xcode 디버거 콘솔에서 SDK 디버그 로그를 확인합니다.

[FTLog][INFO] -[FTRecordModel initWithSource:op:tags:fields:tm:] [line 36] write data = {
    op = RUM;
    opdata =     {
        fields =       {
            .......
        };
        source = action;
        tags =         {
            ........
        }       
   }
}

op = RUM; 이 표시되면 RUM 기능이 정상적으로 활성화되어 데이터가 성공적으로 수집된 것입니다.

Trace

enableLinkRumData = YES로 설정하면 RUM Resourse 데이터에서 확인할 수 있습니다. Xcode 디버거 콘솔에서 SDK 디버그 로그를 확인합니다.

[FTLog][INFO] -[FTRecordModel initWithSource:op:tags:fields:tm:] [line 36] write data = {
    op = RUM;
    opdata =     {
        fields =         {
            duration = 5873084;
            "request_header" = "Accept:*/*\nx-datadog-parent-id:12914452039873665275\nx-datadog-trace-id:6849912365449426814\nx-datadog-origin:rum\nAccept-Language:en-US,en;q=0.9\nAccept-Encoding:gzip, deflate\nx-datadog-sampling-priority:2";
            ......
        };
        source = resource;
        tags =         {
            ......
            "span_id" = 12914452039873665275;
            "trace_id" = 6849912365449426814;
            ......
        };
    };

op = RUM;, source = resource; 데이터를 찾아 tags에 span_id와 trace_id가 포함되어 있으면 Trace 기능이 정상적으로 활성화된 것입니다.

데이터 손실

일부 데이터 손실

  1. RUM의 특정 Session 데이터나 Log, Trace의 일부 데이터가 손실된 경우

먼저 RUM, Log, Trace의 샘플링 구성을 확인합니다. SDK 1.6.8+에서는 sessionSamplingRate, logSamplingRate, traceSamplingRate 사용을 권장하며, 단위는 0~100 퍼센트로 0이면 비활성화, 100이면 전체 샘플링입니다. 1보다 작은 양수는 여전히 유효한 소수 샘플링 비율입니다. 예를 들어 0.1은 0.1%를 의미합니다. 값이 "1 미만"이라는 이유만으로 기능이 비활성화된 것으로 판단해서는 안 됩니다. 세션 샘플링 미적중 또는 로그/Trace가 비율에 따라 선택되지 않은 경우에도 일부 데이터가 누락될 수 있습니다. 기존 속성 sampleRate / samplerate는 정수 퍼센트만 지원하며 더 이상 사용되지 않음(deprecated)으로 표시되었고 향후 버전에서 제거될 수 있습니다. 원격 레거시 필드의 비율 단위는 원격 구성 필드를 참조하세요.

  1. RUM에서 Resource 이벤트 또는 Action 이벤트(launch action 제외)가 손실된 경우

View 자동 수집이 활성화되어 있는지 또는 Open API로 수동 수집을 사용하고 있는지 확인해야 합니다. Resource 이벤트나 Action 이벤트는 View에 바인딩되므로 View가 수집된 상태에서만 정상적으로 수집할 수 있습니다.

  1. SDK 버전 <= 1.4.14에서 일부 데이터가 손실되고 Xcode 디버거 콘솔에서 다음과 같은 디버그 로그가 확인되는 경우
*********此条数据格式错误********
(null)*** 1717051153966272768
******************

SDK에 전달된 NSDictionary 유형 매개변수가 다음 요구 사항을 충족하는지 확인합니다.

  • 모든 딕셔너리 키는 NSString이어야 합니다.

  • 모든 객체는 NSString, NSNumber, NSArray, NSDictionary 또는 NSNull이어야 합니다.

  • NSNumber는 NaN 또는 무한대가 아니어야 합니다.

키와 값 모두 NSString 사용을 권장합니다.

  1. 데이터를 업로드하는 디바이스의 네트워크와 datakit이 설치된 디바이스의 네트워크 및 부하 문제를 점검합니다.

Error 데이터 손실: Crash 유형 데이터

  • Crash 수집 기능이 활성화되어 있는지 확인

  • SDK 초기화가 Crash 이전에 완료되었는지 확인

  • Crash를 캡처하는 기능이 있는 다른 타사 컴포넌트를 사용하는지 확인, 사용 중이라면 FTMobileSDK 초기화를 해당 컴포넌트 뒤에 배치

  • Xcode 디버그 단계인지 확인

SDK는 UNIX 신호와 Mach 예외를 사용하여 크래시를 캡처합니다. 두 캡처 방식 모두 Xcode에서 기본적으로 활성화된 Debug executable의 영향을 받습니다. Debug executable은 SDK가 이러한 예외를 캡처하기 전에 가로채므로, 디버그 단계에서도 크래시를 정상적으로 캡처하려면 Debug executable 기능을 수동으로 끄거나 Xcode 디버그 연결 없이 테스트를 수행해야 합니다.

참고: Debug executable을 끄면 브레이크포인트 디버깅 기능이 동작하지 않습니다.

troubleshooting_debug_executable

버전 호환 문제

RUM Resource 이벤트의 성능 지표 누락

영향 버전: SDK 버전 1.3.10 이하

SDK는 iOS 9 이상을 지원합니다. RUM Resource 이벤트의 성능 지표는 iOS 10 이상 시스템에서 지원하는 API를 사용해야 수집할 수 있으므로, 사용자 디바이스의 시스템이 iOS 10 미만인 경우 수집된 Resource 이벤트에서 성능 지표 부분이 누락됩니다.

RUM Error 데이터의 carrier 속성에 -- 표시

iOS 16.4 이상에서 CoreTelephony의 CTCarrier는 더 이상 사용되지 않으며(deprecated) 대체 API가 없습니다. 더 이상 사용되지 않는 메서드를 호출하면 정적 값 --가 반환됩니다.

WebView

[xxViewController retain]: message sent to deallocated instance xxx

영향 버전: SDK 버전 1.4.10 이하

원인: WebView를 사용할 때 WebView에 관찰자(observer)를 추가했지만, 관찰자가 해제되기 전에 WebView에서 해당 관찰자를 제거하지 않은 경우입니다. SDK 내부에서 WebView를 강한 참조(strong reference)로 유지하므로 WebView가 해제되지 않습니다. 이후 관찰 중인 KeyPath가 변경되면 이미 해제된 관찰자에게 알림이 전송되어 EXC_BAD_ACCESS 오류가 발생합니다.

수정 권장 사항:

  • SDK 버전 업그레이드

  • 또는 관찰자가 해제되기 전에 해당 관찰자를 제거합니다.

   - (void)createWebView{
     [self.webView.scrollView addObserver:self forKeyPath:@"contentSize" options:NSKeyValueObservingOptionNew context:nil];
   }
   -(void)dealloc{
     [self.webView.scrollView removeObserver:self forKeyPath:@"contentSize"]
   }

문서 평가

이 페이지가 도움이 되었나요?