문제 해결¶
이 문서는 HarmonyOS SDK 초기화 및 보고 이상 발생 시 기본적인 문제 해결 진입점을 제공합니다.
초기화 및 로그 진단¶
초기화 실패¶
SDK 초기화에 실패한 경우 다음을 우선 확인하는 것이 좋습니다:
datakitUrl,datawayUrl,clientToken이 배포 방식에 맞게 올바르게 구성되었는지 확인합니다ft_sdk.har,ft_native.har가libs디렉터리에 올바르게 배치되었고,oh-package.json5에서 각각@guancecloud/ft_sdk,@guancecloud/ft_native로 선언한 후ohpm install을 실행했는지 확인합니다- 앱이 문서에 따라
oh-package.json5의존성 선언을 완료했는지 확인합니다 - SDK 초기화가 앱 시작 단계에서 발생했는지 확인합니다
SDK 초기화 오류 확인¶
hilog에서 Tag가 [FT-SDK] 접두사인 로그가 있는지 확인합니다. SDK 초기화, 구성 설치, 데이터 동기화 등 내부 로그가 이 접두사로 출력되며, 초기화 실패, 구성 미적용 또는 네트워크 동기화 이상 등의 문제를 파악하는 데 사용할 수 있습니다.
Debug 디버깅 활성화¶
다음 구성을 통해 SDK Debug 모드를 활성화할 수 있습니다. setDebug(true)는 SDK 내부 로그의 마스터 스위치입니다. 활성화하면 콘솔 hilog에 SDK 디버그 로그가 출력되며, [FT-SDK] 문자열을 필터링하여 SDK 내부 로그를 찾을 수 있습니다. setSdkLogLevel(...)은 출력 임계값을 제어합니다:
| 로그 레벨 | 출력 내용 |
|---|---|
SDKLogLevel.V, SDKLogLevel.D |
현재 모든 SDK 진단 로그 출력: D, I, W, E |
SDKLogLevel.I |
I, W, E 출력 |
SDKLogLevel.W |
W, E 출력 |
SDKLogLevel.E |
E만 출력 |
import { FTSDK, FTSDKConfig, SDKLogLevel } from '@guancecloud/ft_sdk/Index';
const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
.setDebug(true)
.setSdkLogLevel(SDKLogLevel.D);
FTSDK.install(sdkConfig, this.context);
Release 버전을 배포할 때는 이 구성을 비활성화하는 것이 좋습니다.
사용자 정의 로그를 HiLog에 출력¶
디버깅 시 FTLogger.logBackground(...) 내용을 함께 확인하려면 setPrintCustomLogToConsole(true)를 활성화할 수 있습니다. 이 기능은 Hvigor 플러그인이 필요 없으며, setEnableConsoleLog(...) 자동 수집과 상호 독립적입니다.
import {
FTSDK, FTSDKConfig, FTLoggerConfig, FTLogger, SDKLogLevel, Status
} from '@guancecloud/ft_sdk/Index';
const sdkConfig = FTSDKConfig.builder('YOUR_DATAKIT_URL')
.setDebug(true)
.setSdkLogLevel(SDKLogLevel.D);
FTSDK.install(sdkConfig, this.context);
FTSDK.installLogConfig(new FTLoggerConfig()
.setEnableCustomLog(true)
.setPrintCustomLogToConsole(true));
FTLogger.logBackground('登录成功', Status.INFO);
SDK 내부 로그를 로컬 파일에 기록¶
온라인 또는 간헐적 문제를 해결할 때 SDK 내부 진단 로그를 앱 샌드박스의 로컬 파일에 기록하여 이후 내보내기 및 분석에 활용할 수 있습니다. 반드시 setDebug(true)를 함께 활성화해야 하며, setSdkLogLevel(...)을 통해 기록할 로그 레벨을 제어할 수 있습니다.
import { FTSDK, FTSDKConfig, SDKLogLevel } from '@guancecloud/ft_sdk/Index';
const sdkConfig = FTSDKConfig.builder(datawayUrl, clientToken)
.setDebug(true)
.setSdkLogLevel(SDKLogLevel.D)
.setEnableInnerLogFile(true, {
singleFileMaxSize: 5 * 1024 * 1024,
totalFileMaxSize: 50 * 1024 * 1024,
flushBatchSize: 20,
flushIntervalMs: 200
});
FTSDK.install(sdkConfig, this.context);
FTInnerLogFileConfig¶
setEnableInnerLogFile(true, config)에 FTInnerLogFileConfig를 전달하여 내부 로그 파일 기록 정책을 조정할 수 있습니다:
| 필드 | 유형 | 필수 | 설명 |
|---|---|---|---|
singleFileMaxSize |
number |
아니요 | 단일 로그 파일 크기, 기본값 5MB, 범위 1MB ~ 10MB |
totalFileMaxSize |
number |
아니요 | 로그 파일 총 크기 임계값, 기본값 50MB, 범위 10MB ~ 100MB. 임계값을 초과하면 가장 오래된 이전 로테이션 파일부터 정리하며, 현재 파일은 유지됩니다 |
flushBatchSize |
number |
아니요 | 일괄 기록 개수, 기본값 20, 범위 1 ~ 100 |
flushIntervalMs |
number |
아니요 | 새로 고침 간격, 기본값 200ms, 범위 50ms ~ 5000ms |
로그 파일은 기본적으로 앱 샌드박스의 filesDir/ft_sdk_logs/ 디렉터리에 기록됩니다:
- 현재 로그 파일:
ft_inner_current.log - 이전 로테이션 파일:
ft_inner_*.log
로그 총 크기가 구성된 임계값을 초과하면 SDK는 가장 오래된 이전 로테이션 파일부터 정리하고 현재 로그 파일은 유지합니다. 내부 로그 파일에는 SDK 자체의 진단 로그만 기록되며, FTLogger가 기록한 비즈니스 Log는 포함되지 않습니다.
내부 로그의 완전성을 위해
FTSDK.install(...)전에 이 구성을 설정하고setDebug(true)를 함께 활성화해야 합니다. 구성 범위를 벗어난 값은 SDK에서 허용 범위로 잘라낸 후 정수로 반올림합니다.
데이터 업로드 및 캐시¶
데이터가 업로드되지 않음¶
다음 순서로 확인하는 것이 좋습니다:
- 사전 조건이 완료되었는지, 특히 DataKit 및 RUM 수집기 구성이 완료되었는지 확인합니다
- 앱 기기가
datakitUrl또는datawayUrl에 액세스할 수 있는지 확인합니다 setProxy(...),setProxyAuthenticator(...)또는setDns(...)를 구성한 경우 프록시, 인증 정보, DNS 서버 또는 DoH 주소가 올바른지 확인합니다. 이러한 구성은 SDK 데이터 업로드 요청에만 적용됩니다- Debug 디버깅 활성화를 참고하여 초기화 및 업로드 로그를 확인합니다
- RUM에서
installRUMConfig가 실행되었고 검증할 수집 항목이 하나 이상 활성화되었는지 확인합니다 - SDK는 기본적으로 업로드 데이터에
deflate압축을 활성화합니다. 서버 또는 네트워크 경로가 호환되지 않는 것으로 의심되면 임시로setCompressIntakeRequests(false)를 설정하여 대조 검증을 수행할 수 있습니다 0.1.18이상 버전은 기본적으로 메인 프로세스에서만 초기화됩니다. 하위 프로세스에서 설치를 수행하는 경우 설치 전에setOnlySupportMainProcess(false)를 호출해야 하는지 확인합니다- 실제 샘플링 값과 원격 재정의를 확인합니다. 새 백분율 API의
1은 1%이고, 기존setSamplingRate(1)은 100%입니다. 자세한 내용은 RUM 초기화 구성을 참고하십시오
캐시 및 동기화¶
- SDK 자동 동기화는 10초 집계 창을 사용하므로, 수집 후 즉시 업로드되지 않는 것은 정상 동작입니다
FTSDKConfig.setAutoSync(false)또는FTSDK.setAutoSync(false)를 통해 자동 동기화를 비활성화한 경우 SDK 초기화의FTSDK.flushSyncData()를 수동으로 호출해야 합니다- SDK 초기화 후
FTSDK.setAutoSync(true)를 통해 자동 동기화를 다시 활성화할 수 있습니다 FTSDK.flushSyncData()는 10초 집계 창을 기다리지 않고, 대기 중인 RUM 및 Log worker 큐를 최대한 플러시한 후 즉시 업로드를 스케줄링합니다- 로컬 캐시에 이상이 있는 경우
FTSDK.clearAllData()를 사용하여 미업로드 데이터를 정리한 후 다시 검증할 수 있습니다 - FileStore를 사용하는 경우 먼저 섀도 모드인지 확인합니다. 섀도 모드에서는 여전히 SQLite가 읽기와 업로드를 담당하며, 동시에 쓰기를 FileStore에 미러링하여 마이그레이션 전 검증에 사용합니다. 자세한 구성은 SDK 초기화를 참고하십시오
- 기존 SQLite 캐시를 처음 마이그레이션할 때는
setNeedTransformOldCache(true)를 명시적으로 호출해야 합니다. 용량이 부족하거나 기존 캐시가 손상된 경우 원본 캐시는 유지되며, 조건을 수정한 후 다시 시작하면 처리를 계속할 수 있습니다
RUM 자동 수집¶
플러그인은 설치되었지만 자동 수집이 적용되지 않음¶
ft_sdk 0.1.18 이상 버전을 사용하는 경우 플러그인은 소스 코드가 속한 모듈의 oh-package.json5를 기준으로 SDK 의존성을 판단합니다. 자동 수집이 필요한 각 HAP, HAR 또는 HSP는 자체 dependencies에 핵심 패키지를 선언해야 하며, Replay는 Replay 패키지도 선언해야 합니다. 프로젝트 루트 디렉터리, 다른 모듈 또는 devDependencies에만 두면 현재 모듈의 계측이 활성화되지 않습니다.
HAP의 hvigorfile.ts에 ftConsoleLogPlugin()이 등록되었는지 확인한 후 클린 빌드를 한 번 수행합니다. 런타임에서는 로그, Action 또는 Replay 구성을 각각 활성화해야 합니다. sdk_pkg_info.track을 사용하여 등록된 플러그인 버전을 확인할 수 있습니다. 옵셔널 체이닝 형태의 console?.info(...), hilog.info?.(...)는 자동 로그 수집 범위에 포함되지 않습니다.
DevEco Studio의 Build 출력 또는 .hvigor/outputs/build-logs/build.log에서 [GuanceBuild]를 검색하면 기능 이름, 소스 파일, 행/열 위치 및 건너뛴 이유를 확인할 수 있습니다. 이러한 빌드 시점 힌트는 FTSDKConfig.setDebug(true)에 의존하지 않습니다.
콜드 스타트 Action이 나타나지 않음¶
- 플러그인이 적용되었는지, 진입점에서 가능한 한 이른 시점에 SDK, RUM 설치를 완료하고
setEnableTraceUserAction(true)를 활성화했는지 확인합니다. - 자동 첫 프레임 수집은 API 22+가 필요합니다. 첫 UI 프레임이 관찰되지 않으면 완전한 콜드 스타트 Action이 업로드되지 않습니다.
- 백그라운드 소스 시작은 동일 프로세스가 처음으로 UI를 표시할 때까지 대기합니다.
0.1.18에서는app_launch_type=background가 유지되며, 소요 시간에는 백그라운드 대기 시간이 포함됩니다. UI가 전혀 없는 프로세스는 해당 Action을 생성하지 않습니다. - Session 샘플링 및
setActionTrackingHandler(...)가 시작 이벤트를 필터링했는지 확인합니다. 사용자 정의 Handler는getSourceType()을 통해 시작 소스를 구분해야 하며, 시작 이벤트의getSource()는null입니다. - 앱 초기화 단계가 불완전한 경우 HAP의
module.json5에AbilityStage가srcEntry로 구성되었는지 확인합니다. 구성되지 않은 경우에는 대략적인 단계 시간만 얻을 수 있습니다.
페이지 또는 Session 귀속이 예상과 다름¶
먼저 이벤트 발생 시점의 포그라운드/백그라운드 상태를 확인합니다. 최신 SDK는 시작 이벤트에 ApplicationLaunch를 사용하고, 백그라운드 또는 페이지가 없는 이벤트에는 BackgroundView, RootView를 사용합니다. 이들은 SDK가 관리하는 View입니다. Session은 사용자 조작이 15분 넘게 없거나, 지속 시간이 4시간을 초과하면 갱신됩니다.
자동 View가 활성화된 경우 동일 페이지에 대해 수동 startView(...)를 다시 호출하지 않도록 합니다. 0.1.18부터 동일한 이름의 View를 수동으로 반복 시작해도 새 레코드가 생성됩니다. 사용 방법은 View 수동 수집을 참고하십시오.
UI 버벅임이 수집되지 않음¶
RUM 구성에서 setEnableTrackAppUIBlock(true, blockDurationMs)를 활성화했는지 확인합니다. HarmonyOS의 UI 버벅임 수집은 시스템 MAIN_THREAD_JANK 이벤트에만 의존합니다. SDK는 이벤트의 begin_time, end_time을 사용하여 소요 시간을 계산하고, blockDurationMs 임계값을 초과한 포그라운드 버벅임만 업로드합니다.
시스템 이벤트에는 시작 유예 기간, 연속 타임아웃 요구 사항 및 프로세스 수준 보고 제한이 있으므로, 단일 블로킹 테스트만으로 수집 적용 여부를 판단해서는 안 됩니다. 문제 해결 시 SDK Debug 로그를 활성화하고 hilog에서 [FT-UI-BLOCK]을 필터링하여 시스템 이벤트 리스너가 등록되었는지와 버벅임이 보고되었는지 확인할 수 있습니다.
네트워크 요청 자동 수집¶
HttpInterceptorChain이 적용되지 않음¶
@kit.NetworkKit의 HttpInterceptorChain 자동 수집이 적용되지 않는 경우 다음을 우선 확인하는 것이 좋습니다:
- 현재 기기 또는 컴파일 대상이 HarmonyOS API 22 이상인지 확인합니다. API 22 미만에서는 이 기능을 지원하지 않습니다
- 프로젝트에
ft_sdk.har및ft_sdk_ext.har가 설치되었고oh-package.json5에@guancecloud/ft_sdk및@guancecloud/ft_sdk_ext로 선언한 후ohpm install을 완료했는지 확인합니다 setEnableTraceUserResource(true)를 활성화했는지 확인합니다. Trace Headers 자동 주입이 필요한 경우 Trace 구성의setEnableAutoTrace(true)도 활성화해야 합니다@kit.NetworkKit의 동시 요청 시나리오에서 각 요청에 대해 독립적인HttpRequest와HttpInterceptorChain을 각각 생성하더라도 여전히 예외가 발생할 수 있는 것으로 알려져 있습니다:{"code":2300003,"message":"Invalid URL format or missing URL"}- 위 오류가 발생하면 우선 직렬 검증으로 전환하는 것이 좋습니다. 동시 시나리오에서는 RCP 또는 Axios 호환 모드로 변경하거나, 고동시성 경로에서
HttpInterceptorChain사용을 일시적으로 피할 수 있습니다
Resource를 수집할 수 없음¶
HTTP 요청이 이미 생성되고 자동 수집 인터셉터가 마운트되었지만 SDK 초기화와 RUM 구성이 나중에 수행된 경우, 요청은 성공했으나 Resource 데이터가 생성되지 않을 수 있습니다.
다음을 우선 확인하는 것이 좋습니다:
HttpRequest를 먼저 생성하거나createFTHttpInterceptorChain()또는applyFTHttpTrack()을 먼저 호출한 후 나중에FTSDK.installRUMConfig()를 실행했는지 확인합니다- RUM 구성에서
setEnableTraceUserResource(true)를 활성화했는지 확인합니다
원인 설명:
HttpInterceptorChain을 생성할 때 현재 RUM 구성을 즉시 읽어 Resource 자동 수집 활성화 여부를 결정합니다- 이 단계가
FTSDK.installRUMConfig()이전에 수행되면 SDK가 읽는 기본값은false입니다 - 이후 SDK 초기화를 완료하더라도 이미 생성된 자동 수집 인터셉터 인스턴스는 자동으로 활성화 상태로 갱신되지 않으므로
Resource가 생성되지 않습니다
권장 처리 방식:
- 먼저
FTSDK.install(),FTSDK.installRUMConfig()를 완료한 후HttpRequest를 생성하고HttpInterceptorChain을 마운트합니다 - 요청 객체 또는 인터셉터 체인이 미리 생성된 경우 SDK 초기화 완료 후 다시 생성하고 다시 마운트해야 합니다
- SDK 초기화 전에 자동 수집 객체를 먼저 생성해야 하는 경우, 생성 시 스위치를 명시적으로 전달하여 기본 구성 값에 의존하지 않도록 할 수 있습니다
선택적 작성 예시:
applyFTAxiosTrack(client, {
enableTraceInterceptor: true,
enableResourceInterceptor: true
});
// 이후 FTSDK.install(...) 및 FTSDK.installRUMConfig(...)를 완료한 후 비즈니스 요청을 보냅니다.
참고:
enableTraceInterceptor,enableResourceInterceptor를 명시적으로 전달하는 것은 자동 수집 메커니즘 자체가 활성화 상태임을 보장할 뿐입니다- SDK 초기화 완료 전에 이미 전송된 요청은 RUM 컨텍스트가 아직 초기화되지 않아
Resource데이터를 생성하거나 보완하지 못할 수 있습니다 - 따라서 SDK 초기화를 먼저 완료한 후 자동 수집 객체를 생성하고 사용하는 방식을 여전히 더 권장합니다
유사한 처리 방식은 RCP와 HttpInterceptorChain에도 동일하게 적용됩니다:
- Axios:
applyFTAxiosTrack(client, { enableTraceInterceptor: true, enableResourceInterceptor: true }) - RCP:
createFTRCPInterceptors(true, true)또는createFTRCPTrackConfig({ enableTraceInterceptor: true, enableResourceInterceptor: true }) - HTTP:
createFTHttpInterceptorChain({ enableTraceInterceptor: true, enableResourceInterceptor: true })또는applyFTHttpTrack(request, { enableTraceInterceptor: true, enableResourceInterceptor: true })
Resource는 존재하지만 Network Error가 없음¶
요청에 HTTP 응답이 없는 경우 먼저 FTRUMConfig.setNetworkErrorHandler(...) 및 연동 레벨 networkErrorHandler를 확인합니다. Handler가 true를 반환하면 상태 코드가 0인 Resource를 유지하고, 그로부터 파생된 Network Error만 건너뜁니다. HTTP 4xx/5xx는 이 필터의 영향을 받지 않습니다. 자세한 내용은 로컬 네트워크 실패 필터링을 참고하십시오.
네트워크 단계 또는 요청 크기 누락¶
RCP는 플랫폼에서 timeInfo를 제공해야 하고, HTTP/Axios는 performanceTiming이 필요합니다. 플랫폼이 노출하지 않거나, 타임스탬프 순서가 비정상이거나, 연결 재사용 등의 경우 일부 단계가 누락될 수 있으며 SDK는 값을 임의로 보완하지 않습니다. HTTPS의 연결 소요 시간은 0.1.18부터 TLS를 포함하므로 더 이상 SSL 소요 시간과 합산할 수 없습니다.
요청 크기, 프로토콜 및 연결 재사용도 플랫폼 또는 연동 측에서 제공하는 유효한 값에 의존합니다. 누락된 값을 0 또는 false로 해석해서는 안 됩니다. 요청 시작 시점의 대역폭, 검증 상태 및 신호도 모든 기기에서 얻을 수 있는 것은 아닙니다. Resource 성능 설명 및 애플리케이션 데이터 수집을 참고하십시오.
세션 리플레이¶
- 핵심 패키지, Replay 패키지 및 플러그인 버전을 확인하고 HarmonyOS 세션 리플레이(실험적)에 따라 설치를 완료합니다.
- SDK, RUM을 먼저 초기화한 후 Replay를 초기화하고 전용
filesDir을 전달했는지 확인합니다.setDelayInit(true)를 구성한 경우 명시적으로start()를 호출해야 합니다. - 샘플링에 포함되었는지 확인합니다. Replay의
setSampleRate(10)은 10%이며 RUM 샘플링과 독립적으로 구성됩니다. 오류 전용 샘플링 모드에서는 연관된 RUM Error가 있어야 업로드 큐에 들어갑니다. - 플러그인이 현재 모듈 및 페이지를 처리했는지 확인합니다. 플러그인을 사용하지 않는 경우 표시되는 페이지 루트 노드를 수동으로 등록했는지 확인합니다. 초기화 또는
isEnabled()가true를 반환하는 것만으로는 유효한 리플레이 프레임이 저장되었음을 증명할 수 없습니다. - 텍스트, 이미지 및 터치는 기본적으로 마스킹됩니다. 화면 내용이 마스킹되었거나 터치 위치가 없는 경우 먼저 개인정보 보호 정책을 확인한 후 수집 이상 여부를 판단합니다.
- ArkWeb는 네이티브 WebView RUM Bridge와 웹페이지 Browser SDK가 녹화를 시작해야 합니다. 네이티브 Replay는 웹페이지 SDK가 로드되기 전에 준비되어야 하며, 필요한 경우 웹페이지를 다시 로드합니다.
- 핵심 업로드 주소가 유효한지 확인합니다. 로컬 DataKit을 사용하는 경우 리플레이 수신 구성을 확인합니다.
disable()는 새 수집만 중지하며, 이미 수락된 프레임은 계속 저장되고 자동 업로드는 계속해서 대기열을 비웁니다. 중지 후에도 업로드 요청이 남아 있는 것이 녹화가 계속되고 있음을 의미하지는 않습니다.