문제 해결¶

이 문서는 HarmonyOS SDK 초기화 및 데이터 업로드 시 발생하는 이상 현상에 대한 기본적인 문제 해결 진입점을 제공합니다.

초기화 및 로그 진단¶

초기화 실패¶

SDK 초기화에 실패하면 다음 사항을 우선 확인하세요.

1. datakitUrl, datawayUrl, clientToken이 배포 방식에 따라 올바르게 설정되어 있는지 확인합니다.
2. ft_sdk.har, ft_native.har이 libs 디렉터리에 올바르게 배치되었는지, oh-package.json5에서 각각 @guancecloud/ft_sdk, @guancecloud/ft_native로 선언한 후 ohpm install을 실행했는지 확인합니다.
3. 앱이 문서대로 oh-package.json5 종속성 선언을 완료했는지 확인합니다.
4. SDK 초기화가 앱 시작 단계에서 수행되었는지 확인합니다.

SDK 초기화 이상 검증¶

hilog에서 Tag가 [FT-SDK] 접두사인 로그가 있는지 확인합니다. SDK 초기화, 구성 적용, 데이터 동기화 등 내부 로그는 이 접두사를 통해 출력되므로 초기화 실패, 구성 미적용, 네트워크 동기화 이상 등을 파악하는 데 사용할 수 있습니다.

Debug 모드 활성화¶

다음 구성을 통해 SDK Debug 모드를 활성화할 수 있습니다. setDebug(true)는 SDK 내부 로그의 전체 스위치입니다. 활성화하면 콘솔 hilog에 SDK 디버그 로그가 출력되며, [FT-SDK] 문자열을 필터링하여 SDK 내부 로그를 찾을 수 있습니다. setSdkLogLevel(...)는 출력 임계값을 제어합니다.

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 버전 배포 시에는 이 구성을 해제할 것을 권장합니다.

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를 전달하여 내부 로그 파일 기록 정책을 조정할 수 있습니다.

로그 파일은 기본적으로 앱 샌드박스 filesDir/ft_sdk_logs/ 디렉터리에 기록됩니다.

• 현재 로그 파일: ft_inner_current.log
• 이력 순환 파일: ft_inner_*.log

로그 총 크기가 구성된 임계값을 초과하면 SDK는 가장 오래된 이력 순환 파일부터 삭제하며 현재 로그 파일은 유지됩니다. 내부 로그 파일에는 SDK 자체 진단 로그만 기록되며, FTLogger로 기록한 비즈니스 Log는 포함되지 않습니다.

내부 로그의 완전성을 위해 FTSDK.install(...) 호출 전에 이 구성을 설정하고 setDebug(true)도 함께 활성화해야 합니다. 구성 범위를 벗어난 값은 SDK가 허용 범위로 잘라내고 반올림 처리합니다.

데이터 업로드 및 캐시¶

데이터가 업로드되지 않는 경우¶

다음 순서로 문제를 확인하는 것이 좋습니다.

1. 전제 조건이 완료되었는지 확인합니다. 특히 DataKit 및 RUM 수집기 구성을 확인합니다.
2. 앱 기기에서 datakitUrl 또는 datawayUrl에 접근할 수 있는지 확인합니다.
3. setProxy(...), setProxyAuthenticator(...) 또는 setDns(...)를 설정한 경우 프록시, 인증 정보, DNS 서버 또는 DoH 주소가 올바른지 확인합니다. 이 구성은 SDK 데이터 업로드 요청에만 적용됩니다.
4. Debug 모드 활성화를 참조하여 초기화 및 업로드 로그를 확인합니다.
5. RUM에서 installRUMConfig를 실행했고 검증이 필요한 수집 항목을 하나 이상 활성화했는지 확인합니다.
6. SDK는 업로드 데이터에 기본적으로 deflate 압축을 적용합니다. 서버 또는 네트워크 구간의 비호환이 의심되는 경우 임시로 setCompressIntakeRequests(false)를 설정하여 대조 검증할 수 있습니다.

캐시 및 동기화¶

• 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 자동 수집¶

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 자동 수집이 적용되지 않으면 다음 사항을 우선 확인하세요.

1. 현재 기기 또는 컴파일 대상이 HarmonyOS API 22 이상인지 확인합니다. API 22 미만에서는 이 기능을 지원하지 않습니다.
2. 프로젝트에 ft_sdk.har와 ft_sdk_ext.har가 설치되어 있고, oh-package.json5에서 @guancecloud/ft_sdk 및 @guancecloud/ft_sdk_ext로 선언한 후 ohpm install을 완료했는지 확인합니다.
3. setEnableTraceUserResource(true)가 활성화되어 있는지 확인합니다. Trace Headers 자동 주입이 필요하면 Trace 구성의 setEnableAutoTrace(true)도 활성화해야 합니다.
4. @kit.NetworkKit의 동시 요청 시나리오에서 각 요청에 별도의 HttpRequest와 HttpInterceptorChain을 생성하더라도 {"code":2300003,"message":"Invalid URL format or missing URL"} 예외가 발생할 수 있는 것으로 알려져 있습니다.
5. 위 오류가 발생하면 우선 직렬 방식으로 전환하여 검증하는 것이 좋습니다. 동시성 시나리오에서는 RCP 또는 Axios 호환 모드를 사용하거나, 고동시성 구간에서 HttpInterceptorChain 사용을 일시적으로 피하세요.

Resource가 수집되지 않는 경우¶

HTTP 요청이 생성되고 자동 수집 인터셉터가 이미 장착되었지만 SDK 초기화와 RUM 구성이 나중에 실행되면, 요청은 성공하더라도 Resource 데이터가 생성되지 않을 수 있습니다.

다음 사항을 우선 확인하세요.

1. HttpRequest를 먼저 생성하고 createFTHttpInterceptorChain() 또는 applyFTHttpTrack()을 호출한 뒤에 FTSDK.installRUMConfig()를 실행했는지 확인합니다.
2. RUM 구성에서 setEnableTraceUserResource(true)가 활성화되어 있는지 확인합니다.

원인 설명:

• HttpInterceptorChain은 생성 시 현재 RUM 구성을 즉시 읽어 Resource 자동 수집 활성화 여부를 결정합니다.
• 이 단계가 FTSDK.installRUMConfig()보다 먼저 실행되면 SDK가 읽는 기본값은 false입니다.
• 이후 SDK 초기화를 완료하더라도 이미 생성된 자동 수집 인터셉터 인스턴스는 활성화 상태로 자동 갱신되지 않으므로 Resource가 생성되지 않습니다.

권장 처리 방법:

1. 먼저 FTSDK.install()와 FTSDK.installRUMConfig()를 완료한 다음 HttpRequest를 생성하고 HttpInterceptorChain을 장착하세요.
2. 요청 객체나 인터셉터 체인이 미리 생성된 경우, SDK 초기화 완료 후 다시 생성하고 다시 장착해야 합니다.
3. SDK 초기화 전에 자동 수집 객체를 먼저 생성해야 한다면, 생성 시 스위치를 명시적으로 전달하여 기본 구성 값에 의존하지 않도록 할 수 있습니다.

선택적 작성 예시:

applyFTAxiosTrack(client, {
  enableTraceInterceptor: true,
  enableResourceInterceptor: true
});

sdk.init();

주의:

• 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 })

관련 문서¶

• 설치 및 진입 페이지: 앱 연동 참조
• 초기화 파라미터: SDK 초기화 참조
• RUM 네트워크 수집: RUM 구성 참조
• Trace 분산 추적: Trace 구성 참조