트러블슈팅¶
컴파일 트러블슈팅¶
컴파일 중 오류가 발생하면 먼저 컴파일 환경을 확인해야 합니다.
실행 가능한 컴파일 환경¶
✅ 실행 가능 환경¶
- AGP
com.android.tools.build:gradle버전3.5.0이상 - gradle 버전
5.4.0이상 - java 버전
8.0이상 - Android minSdkVersion 21
참고: Android Studio 버전 업데이트에 따라 해당 버전 호환성도 변경될 수 있습니다. 컴파일 환경이 위 조건을 충족하지만 여전히 컴파일 오류가 발생하는 경우 당사 개발자에게 문의하시기 바랍니다.
⚠️ 호환 가능 실행 환경¶
- AGP
com.android.tools.build:gradle버전3.0.1이상 - Gradle 버전
4.8.1이상 - Java 버전
8.0이상 - Android minSdkVersion 21
이 환경에서는
ft-plugin을 사용할 수 없으며, 데이터 자동 캡처 부분을 수동으로 연동해야 합니다. 수동 연동에 대한 자세한 내용은 수동 연동을 참조하시기 바랍니다.
SDK 가져오기 오류¶
위와 같은 오류는 maven 저장소가 올바르게 설정되지 않았기 때문에 발생합니다. 설정을 참조하시기 바랍니다.
컴파일 오류¶
Desugaring 오류¶
>Task :app:transformClassesWithStackFramesFixerForDebug
Exception in thread "main" java.lang.IllegalStateException: Expected a load for Ljava/lang/String; to set up parameter 0 for com/ft/sdk/FTRUMGlobalManager$$Lambda$11 but got 95
at com.google.common.base.Preconditions.checkState (Preconditions.java:756)
at com.google.devtools.build. android.desugar.LambdaDesugaring$InvokedynamicRewriter .attemptAllocationBeforeArgumentLoadsLambdaDesugaring.java:535)
at com.google.devtools.build.android.desugar.LambdaDesugaring$InvokedynamicRewriter.visitInvokeDynamicInsn
(LambdaDesugaring.java: 420)
at org.objectweb.asm.ClassReader.a(Unknown Source)
at org.objectweb.asm.ClassReader.b(Unknown Source)
at org.objectweb.asm.ClassReader.accept(Unknown Source)
at org.objectweb.asm.ClassReader.accept(Unknown Source)
at com.google.devtools.build. android.desugar. Desugar.desugarClassesInInput (Desugar.java:401) at com.google.devtools.build.android.desugar.Desugar.desugar0neInput(Desugar.java:326) at com.google.devtools.build.android.desugar. Desugar.desugar (Desugar.java:280) at com.google.devtools.build.android.desugar. Desugar.main (Desugar.java:584)
3.0.0 호환성 문제로 인한 것입니다. 이슈에서 이 문제를 설명하고 있으며, AGP 3.1.0 이상 버전으로 업그레이드하거나 최신 버전 SDK를 사용하고 app/build.gradle에서 버전을 업그레이드하면 해결할 수 있습니다.
dependencies {
implementation('com.cloudcare.ft.mobile.sdk.tracker.agent:ft-sdk:1.3.10.beta01')//1.3.10 이상 가능
}
API 'android.registerTransform' is obsolete¶
AGP 7.0에서는 Transform이 Deprecated로 표시되었으며, AGP 8.0에서는 더 이상 사용되지 않습니다. ft-plugin:1.2.0에서 이미 이에 대한 적응이 완료되었으므로, 해당 버전으로 업그레이드하여 오류를 수정하시기 바랍니다. 자세한 내용은 통합 설정을 참조하시기 바랍니다.
AndroidComponentsExtension ClassNotFoundException¶
AndroidComponentsExtension은 AGP 7.4.2에서 지원되는 메서드로, 이보다 낮은 버전의 컴파일 환경에서는 이 오류가 발생합니다. ft-plugin-legacy 버전을 사용하여 이 오류를 수정할 수 있습니다. 자세한 내용은 통합 설정을 참조하시기 바랍니다.
java.lang.IllegalArgumentException:¶
- Invalid opcode 169
ft_plugin_legacy를 사용할 때 이 오류가 발생하는 경우, 이는 asm-commons:7.0 버전의 버그입니다. 원본 이슈는 여기에 있으며, 플러그인 구성에서 org.ow2.asm:asm-commons:7.2 이상 버전에 의존하도록 하여 이 문제를 해결할 수 있습니다. ./gradlew buildEnvironment를 통해 실제 사용 중인 asm-commons 버전을 확인할 수 있습니다.
buildscript {
dependencies {
classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[version]'
// 의존성 추가
classpath 'org.ow2.asm:asm-commons:7.2'
}
}
- org.ow2.asm:asm 버전이 7.0 미만
현재 플러그인 버전은 org.ow2.asm:asm7.x 이상 버전을 사용하는 빌드 환경만 지원합니다. ./gradlew buildEnvironment를 통해 빌드 환경을 조회하여 확인할 수 있습니다. 7.x 이상 버전을 강제로 의존하도록 하여 수정할 수 있으며, 7.2 이상 버전을 사용하는 것을 권장합니다.
buildscript {
dependencies {
classpath 'com.cloudcare.ft.mobile.sdk.tracker.plugin:ft-plugin-legacy:[version]'
// 의존성 추가
classpath 'org.ow2.asm:asm:7.2'
classpath 'org.ow2.asm:asm-commons:7.2'
}
}
SDK 초기화 예외 검증¶
Logcat에서 로그 Level이 Error이고 Tag가 [FT-SDK] 접두사인 로그가 있는지 확인합니다.
Debug 디버깅 활성화¶
ft-sdk Debug 모드¶
다음 구성을 통해 SDK의 debug 기능을 활성화할 수 있습니다. 활성화하면 콘솔 Logcat에 SDK 디버그 로그가 출력되며, [FT-SDK] 문자열을 필터링하여 Guance SDK 로그를 찾을 수 있습니다.
로그 예시¶
데이터 동기화¶
// 업로드 주소가 올바른지 확인하여 SDK 구성에 진입
[FT-SDK]FTHttpConfigManager com.demo D serverUrl ==>
Datakit Url:http://10.0.0.1:9529
// 다음은 연결 오류 로그입니다.
[FT-SDK]SyncTaskManager com.demo E Network not available Stop poll
[FT-SDK]SyncTaskManager com.demo E ↵
1:Sync Fail-[code:10003,response:failed to connect to 10.0.0.1 (port 9529) from ↵
10.0.2.16 (port 47968) after 10000ms,로컬 네트워크 연결이 정상인지 확인하세요]
// 다음은 정상 동기화 로그입니다.
[FT-SDK]SyncTaskManager com.demo D Sync Success-[code:200,response:]
릴리스 버전을 배포할 때는 이 구성을 비활성화하는 것을 권장합니다.
ft-plugin Debug 모드¶
다음 구성을 통해 Plugin의 debug 로그를 활성화할 수 있습니다. 활성화하면 Build 출력 로그에서 [FT-Plugin]의 출력 로그를 찾을 수 있습니다. 이를 통해 Plugin ASM 기록 상황을 확인할 수 있습니다.
릴리스 버전을 배포할 때는 이 구성을 비활성화하는 것을 권장합니다.
SDK 내부 로그를 캐시 파일로 변환¶
// >= 1.4.6
// 기본 경로: /data/data/{package_name}/files/LogInner.log
LogUtils.registerInnerLogCacheToFile()
// >= 1.4.5+
val cacheFile = File(filesDir, "LogCache.log")
LogUtils.registerInnerLogCacheToFile(cacheFile)
내부 로그의 완전성을 위해 SDK 초기화 전에 이 구성을 설정해야 합니다.
Session Replay Compose 리플레이에서 순수 컨테이너 배경색 누락¶
Jetpack Compose Session Replay를 사용할 때, 페이지에 레이아웃 및 배경 그리기만을 위한 Row, Column, Box 등의 컨테이너가 존재하는 경우(예: Modifier.background(...)만 설정되고 텍스트, 클릭, 시맨틱 또는 기타 접근성 정보가 없는 경우), 해당 컨테이너는 Compose 시맨틱 노드 트리에 나타나지 않을 수 있습니다. Session Replay는 현재 시맨틱 노드를 기반으로 매핑되므로, 리플레이에서 배경색이 누락되거나 Toolbar, 블록 배경이 기본 흰색으로 표시될 수 있습니다.
해당 배경이 리플레이 표시에 중요한 경우, 컨테이너에 빈 시맨틱 태그를 추가하여 시맨틱 노드 트리에 포함시킬 수 있습니다.
Row(
modifier = Modifier
.fillMaxWidth()
.height(56.dp)
.semantics { }
.background(Color(0xFFFF6600))
)
이 방식은 화면 표시 효과를 변경하지 않으며, Session Replay가 해당 Compose 컨테이너 노드를 캡처하도록 돕기 위한 것입니다. 추후 SDK는 무시맨틱 컨테이너 배경의 자동 수집 기능을 지속적으로 강화할 예정입니다.
SDK가 정상적으로 실행되지만 데이터가 없는 경우¶
-
Datakit가 정상적으로 실행 중인지 확인하십시오.
-
SDK 업로드 주소
datakitUrl또는datawayUrl이 올바르게 구성되었고, 올바르게 초기화되었는지 확인하십시오. debug 모드에서 로그를 확인하여 업로드 문제를 판단하십시오. -
Datakit이 해당 워크스페이스로 데이터를 업로드하고 있는지, 오프라인 상태인지 확인하십시오. 이는 Guance에 로그인하여 「인프라스트럭처」를 확인함으로써 확인할 수 있습니다.
OkHttp 3.12.+ 호환성 문제¶
ft-sdk < 1.6.13 버전에서 데이터 압축 FTSDKConfig.setCompressIntakeRequests(true)을 활성화하면 SDK 데이터 수집은 정상이지만, 데이터 동기화 단계에서 오류 메시지가 생성되지 않고 HTTP 상태 코드 로그도 출력되지 않습니다.
해결 방법: ft-sdk >= 1.6.13 버전을 사용하거나 OkHttp 4.5.0 이상 버전을 사용하면 이 문제를 해결할 수 있습니다.
데이터 손실¶
일부 데이터 손실¶
- RUM의 특정 Session 데이터, Log, Trace의 몇 가지 데이터가 손실된 경우, 먼저 FTRUMConfig, FTLoggerConfig, FTTraceConfig에서
sampleRate < 1을 설정했는지 확인하여 제외해야 합니다. - 데이터를 업로드하는 장치의 네트워크와 Datakit이 설치된 장치의 네트워크 및 부하 문제를 확인하십시오.
FTSdk.shutDown이 올바르게 호출되었는지 확인하십시오. 이 메서드는 SDK 데이터 처리 객체를 해제하며, 캐시된 데이터도 포함됩니다.
Resource 데이터 손실¶
자동 수집, ft-plugin이 올바르게 연동되지 않은 경우¶
Resource 자동 수집은 Plugin ASM 바이트코드 쓰기를 통해 OkHttpClient의 Interceptor와 EventListener를 자동으로 설정하고, FTTraceInterceptor, FTResourceInterceptor, FTResourceEventListener.FTFactory를 주입해야 합니다. Plugin을 사용하지 않는 경우 여기를 참조하시기 바랍니다.
커스텀 WebView 자동 수집이 적용되지 않는 경우¶
네이티브 WebView 페이지 수집은 정상이지만, 커스텀 WebView 페이지에서 예상한 자동 수집이 트리거되지 않는 경우, Plugin 로그를 통해 WebView 인식 문제인지 우선 확인하는 것이 좋습니다.
확인 방법:
- 먼저 통합 구성을 참조하여
FTExt에서 로그를 활성화합니다.
- 다시 컴파일한 후,
Build로그에서[FT-Plugin]및WEBVIEW관련 출력을 검색하고, 다음과 유사한 로그가 나타나는지 확인합니다.
[FT-Plugin]:TARGET_CUSTOM_WEBVIEW_METHOD-> owner:com/example/CustomWebView, class:com/example/WebViewActivity$2, super:java/lang/Object, method:loadUrl(Ljava/lang/String;)V | onItemSelected(Landroid/widget/AdapterView;Landroid/view/View;IJ)V
이러한 TARGET_CUSTOM_WEBVIEW_METHOD 로그가 나타나면 Plugin이 현재 owner를 커스텀 WebView로 인식하고 해당 호출을 처리한 것입니다.
이러한 로그가 전혀 나타나지 않지만 실제로 호출되는 것이 비즈니스 커스텀 WebView인 경우, 일반적으로 해당 클래스가 knownWebViewClasses에 추가되었는지 확인해야 합니다. 이는 자동 수집 인식에만 영향을 미치는 것이 아니라, Plugin이 커스텀 WebView 내부 메서드를 일반 메서드로 간주하고 계속 ASM 쓰기를 수행할지 여부도 결정합니다. 올바르게 인식되지 않으면 실행 시 loadUrl 등의 메서드가 순환 호출되어 최종적으로 WebView가 흰 화면으로 표시될 수 있습니다. 문제 해결 시 다음과 유사한 로그도 함께 확인할 수 있습니다.
이는 일반적으로 현재 클래스가 아직 Plugin에 의해 WebView로 인식되지 않았음을 의미합니다.
해결 방법:
FTExt에 knownWebViewClasses를 추가하여 실제 사용 중인 커스텀 WebView 클래스를 구성에 포함시킵니다. 비즈니스의 WebView 기본 클래스를 우선 추가하는 것이 좋습니다. 상속 계층이 깊은 경우 기본 클래스와 현재 사용 중인 클래스를 모두 추가할 수 있습니다. 이렇게 하면 Plugin이 WebView 호출을 올바르게 인식할 수 있을 뿐만 아니라 커스텀 WebView 내부 메서드가 중복 ASM 쓰기되는 것을 방지할 수 있습니다.
FTExt {
showLog = true
verboseLog = true
knownWebViewClasses = [
'com.example.web.BaseWebView',
'com.example.web.CustomWebView'
]
}
knownWebViewClasses는 비즈니스 커스텀 WebView를 Plugin의 알려진 WebView 목록에 미리 추가하는 역할을 합니다. 이를 통해 커스텀 WebView의 인식 문제를 해결하는 동시에 Plugin이 WebView 내부 메서드의 중복 쓰기를 건너뛰어 런타임 순환 호출 및 흰 화면을 방지할 수 있습니다.
OkHttpClient.build() 설정 문제¶
Plugin ASM은 애플리케이션이 OkHttpClient.Builder().build()를 호출할 때 네트워크 수집 기능을 자동으로 주입합니다. 다음 두 가지 상황에서 네트워크 수집이 실패할 수 있습니다.
- 시퀀스 문제 - SDK 초기화 미완료. SDK 초기화가 완료되기 전에
OkHttpClient.Builder().build()가 호출되면 빈 구성을 로드하여 Resource 관련 데이터가 손실될 수 있습니다. 디버그 로그를 확인하여 초기화 순서가 올바른지 확인하십시오. - 생성 방식 문제. 표준
OkHttpClient.Builder().build()메서드를 사용하지 않고 OkHttpClient 객체를 생성한 경우(예: OkHttpClient를 직접 인스턴스화하거나 다른 빌드 방식 사용).
//SDK 초기화 로그
[FT-SDK]FTSdk com.ft D initFTConfig complete
[FT-SDK]FTSdk com.ft D initLogWithConfig complete
[FT-SDK]FTSdk com.ft D initRUMWithConfig complete
[FT-SDK]FTSdk com.ft D initTraceWithConfig complete
//SDK OkHttpClient.Builder.build() 호출 시 출력되는 로그
//(SDK 초기화 후에 호출되어야 함)
[FT-SDK]AutoTrack com.ft D trackOkHttpBuilder
초기화 호출 순서를 조정할 수 없는 경우 수동 방식을 선택하여 연동할 수 있습니다.
Interceptor 또는 EventListener를 사용하여 데이터를 2차 처리한 경우¶
Plugin ASM이 삽입된 후, 원본 프로젝트 코드를 기반으로 OkHttpClient.Builder()에 addInterceptor가 추가되어 FTTraceInterceptor와 FTResourceInterceptor가 각각 추가됩니다. 여기서 HTTP 요청의 body contentLength를 사용하여 고유 ID를 계산하고, Resource 데이터의 각 단계 데이터는 이 ID를 통해 컨텍스트가 연결됩니다. 따라서 통합 측에서 OkHttp를 사용할 때 addInterceptor도 추가하고 데이터를 2차 처리하여 크기가 변경되면, ID의 각 단계 계산이 일치하지 않아 데이터 손실이 발생할 수 있습니다.
해결 방법:
ft-sdk < 1.4.1
커스텀 addInterceptor 위치 순서를 통해 SDK 메서드가 가장 먼저 ID를 계산하도록 하여 이 문제를 해결할 수 있습니다. 중복 설정을 방지하기 위해 커스텀 방식에서는 FTRUMConfig의 enableTraceUserResource와 FTTraceConfig의 enableAutoTrace 구성을 비활성화해야 합니다.
ft-sdk >= 1.4.1
SDK가 수동 설정이 아닌 시나리오에서는 자체적으로 이 문제를 호환 처리합니다. 이미 수동 설정을 한 경우 Interceptor가 앞쪽 위치에 있는지 확인해야 합니다.
OkHttp 3.12.+ 호환성 문제¶
ft-sdk < 1.6.13 에서 사용하는 Interceptor가 response body 내용을 read하여 처리하는 경우, 현재 Resource 데이터를 수집하지 못할 수 있습니다.
해결 방법:
ft-sdk < 1.6.13
-
OkHttp 버전을 변경하지 않고 수동 설정으로 이 문제를 해결합니다.
OkHttpClient.Builder builder = new OkHttpClient.Builder() .addInterceptor(new CustomReadReponseInterceptor())//응답 body 읽기 .addInterceptor(new FTTraceInterceptor()) .addInterceptor(new FTResourceInterceptor()) .addInterceptor(new CustomRequestBodyFixInterceptor())//body 암호화 또는 수정 .eventListenerFactory(new FTResourceEventListener.FTFactory()); OkHttpClient client = builder.build(); -
OkHttp를 4.5.0 이상 버전으로 업그레이드해도 이 문제를 해결할 수 있습니다.
ft-sdk >= 1.6.13
SDK가 수동 설정이 아닌 시나리오에서는 자체적으로 이 문제를 호환 처리합니다.
Error 데이터 손실 - Crash 유형 데이터¶
- Crash를 캡처하는 기능이 있는 다른 타사 SDK를 함께 사용하고 있는지 확인하십시오. 그렇다면 SDK 초기화 메서드를 다른 SDK 뒤에 배치해야 합니다.
데이터에서 특정 필드 정보 누락¶
사용자 데이터 필드¶
-
사용자 데이터 바인딩 메서드가 올바르게 호출되었는지 확인하십시오. debug 모드에서는 로그를 통해 이 문제를 추적할 수 있습니다.
커스텀 매개변수 누락 또는 값 오류¶
- 올바른 시나리오에서 호출되었는지 확인하십시오.
FTRUMConfig.addGlobalContext,FTLoggerConfig.addGlobalContext는 애플리케이션 채널, 애플리케이션의 다른 Flavor 속성 등 애플리케이션 주기 내에서 변경되지 않는 시나리오에 적합합니다. 동적 시나리오에 따라 실시간으로 응답해야 하는 경우, RUM 및 Log 인터페이스를 수동으로 호출해야 합니다. - debug 모드에서
[FT-SDK]SyncTaskManager로그를 확인하면 커스텀 필드 매개변수의 정확성을 검증할 수 있습니다.
로그 활성화 시 enableConsoleLog 로 인한 끊김 문제¶
끊김 현상이 발생하는 경우, 로그 데이터 수집량이 너무 많기 때문일 수 있습니다. FTLoggerConfig.enableConsoleLog의 원리는 컴파일된 android.util.Log, Java 및 Kotlin println을 캡처하는 것입니다. 필요에 따라 FTLoggerConfig 구성의 sampleRate, logPrefix, logLevelFilters 매개변수를 조정하여 이 문제를 완화하거나 해결하는 것을 권장합니다.
OkHttp EventListener가 SDK 통합 후 작동하지 않는 경우¶
Plugin AOP ASM이 삽입된 후, 원본 프로젝트 코드를 기반으로 OkHttpClient.Builder()에 eventListenerFactory가 추가되며, 이는 기존의 eventListener 또는 eventListenerFactory를 덮어씁니다.
해결 방법:
ft-sdk < 1.4.1
Plugin AOP 자동 설정을 비활성화하고(FTRUMConfig setEnableTraceUserResource(false)), 동시에 FTResourceEventListener.FTFactory를 상속받는 CustomEventListenerFactory를 커스텀하여 커스텀 방식으로 연동합니다.
ft-sdk >= 1.4.1
FTResourceEventListener.FTFactory를 상속받는 CustomEventListenerFactory를 커스텀하고, FTRUMConfig.setOkHttpEventListenerHandler를 설정하여 ASM이 작성한 eventListenerFactory를 커스텀합니다.
ft-sdk >= 1.6.7
SDK가 수동 설정이 아닌 시나리오에서는 자체적으로 이 문제를 호환 처리합니다.
TraceID 누락 또는 Trace Propagation Header와 불일치¶
완전한 요청 데이터 수집을 수행하려면 일반적으로 Interceptor와 EventListener에서 각각 정보를 가져와야 합니다. 이 두 부분의 데이터를 효과적으로 연결하기 위해 SDK는 동일한 네트워크 요청을 연결하는 고유 ID가 필요합니다. 그러나 1.6.10 버전 이전에는 이 ID가 동일한 요청에서 동일했기 때문에, 고부하 시나리오에서 데이터 오류나 손실이 발생할 수 있었습니다. 1.6.10 버전부터는 FTSDKConfig.setEnableOkhttpRequestTag(true)를 호출하거나 Request에 명시적으로 ResourceID를 추가하여 각 요청에 고유 식별자를 부여함으로써 동일한 요청 간의 간섭 문제를 방지할 수 있습니다. 설정 방법은 여기를 참조하시기 바랍니다.