문제 해결¶

이 문서는 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);

릴리즈 버전을 배포할 때는 이 구성을 비활성화하는 것이 좋습니다.

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가 기록하는 비즈니스 로그는 포함하지 않습니다.

내부 로그의 완전성을 보장하려면 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()를 사용하여 미업로드 데이터를 정리한 후 다시 검증할 수 있습니다.

네트워크 요청 자동 수집¶

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 헤더를 자동으로 주입해야 하는 경우 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 구성 참조