HarmonyOS 애플리케이션 연동¶
HarmonyOS 애플리케이션의 메트릭 데이터를 수집하여 애플리케이션 성능을 시각적으로 분석합니다.
읽기 경로¶
- 최초 연동: 먼저 연동 방식 선택을 확인합니다. 수동 연동은 빠른 시작을 참고할 수 있습니다.
- 전체 연동: 이 문서를 계속 읽습니다.
- 이전 버전 패키지 이름 마이그레이션: 이전 설정 마이그레이션을 확인합니다.
- HAR 패키지 다운로드: HAR 획득 방법을 확인합니다.
- 초기화 파라미터: SDK 초기화, RUM 설정, Log 설정, Trace 설정을 확인합니다.
- 고급 기능: “고급 시나리오” 그룹의 전용 페이지를 확인합니다.
- 세션 리플레이: HarmonyOS 세션 리플레이(실험적)을 확인합니다.
- 데이터 모델: 애플리케이션 데이터 수집을 확인합니다.
- 문제 진단: 트러블슈팅을 확인합니다.
사전 조건¶
주의
RUM Headless 서비스를 이미 활성화한 경우 사전 조건이 자동으로 구성되어 있으므로 애플리케이션을 바로 연동할 수 있습니다.
로컬 환경에 배포하는 경우 다음 데이터 수신 측 설정을 완료해야 합니다. 공용 DataWay를 사용하는 경우 DataKit을 직접 배포할 필요가 없습니다.
- DataKit 설치
- RUM 수집기 설정
- DataKit을 공용 네트워크에서 접근 가능하게 설정하고 IP 지리 정보 라이브러리 설치
애플리케이션 연동¶
- RUM > 애플리케이션 생성 > HarmonyOS로 이동합니다.
- 애플리케이션 이름과 애플리케이션 ID를 입력합니다.
- 「연동 방식 선택」에서 Agent 자동 연동 또는 수동 연동을 선택한 다음 「연동 설정」을 완료합니다.
연동 방식 선택¶
애플리케이션 설정 페이지에서 「Agent 자동 연동」 또는 「수동 연동」을 선택한 다음 「연동 설정」을 완료합니다. 이미 애플리케이션이 있는 경우 설정 페이지로 바로 이동하여 연동을 계속할 수 있습니다.
| 연동 방식 | 사용 사례 | 작업 진입점 |
|---|---|---|
| Agent 자동 연동 | 프로그래밍 어시스턴트가 프로젝트를 분석하고 SDK 연동을 완료하기를 원하는 경우 | 콘솔에서 생성된 프롬프트를 복사하여 애플리케이션 코드 저장소에서 프로그래밍 어시스턴트에게 전달해 실행 |
| 수동 연동 | SDK를 직접 설치하고 파라미터를 설정하기를 원하는 경우 | 데이터 보고 방식을 확인한 다음 이 문서와 빠른 시작에 따라 설정을 완료 |
Agent 자동 연동¶
- 현재 애플리케이션의 설정 페이지에서 「Agent 자동 연동」을 선택합니다.
- 「연동 설정」의 전체 프롬프트를 복사하고, 현재 애플리케이션의 연동 정보를 사용하는지 확인합니다.
- 애플리케이션 코드 저장소에서 프로그래밍 어시스턴트를 열고 프롬프트를 붙여넣으면, Agent가 연동 가이드에 따라 프로젝트를 분석하고 SDK 설정을 완료합니다.
- 애플리케이션을 빌드하고 실행하여 페이지 방문 등의 작업을 트리거한 후, 현재 애플리케이션의 탐색기에서 데이터 수신 여부를 확인합니다.
페이지에 사용자 API Key 또는 임시 인증 코드가 준비되지 않았다는 안내가 표시되면, 안내에 따라 보완한 후 프롬프트를 다시 복사합니다.
수동 연동¶
애플리케이션 설정 페이지에서 「수동 연동」을 선택하고 데이터 보고 방식을 확인합니다.
- 공용 DataWay: RUM 데이터를 직접 수신하며 DataKit 수집기를 설치할 필요가 없습니다.
- 로컬 환경 배포: 사전 조건을 충족한 후 RUM 데이터를 수신합니다.
아래 설치와 빠른 시작에 따라 SDK 설치, 초기화 및 검증을 완료합니다. 이미 SDK 설정이 있는 경우 먼저 확인하여 재사용하고, 중복 초기화를 피해야 합니다.
설치¶
Hvigor Plugin 설정 추가¶
console.*, hilog.* 자동 수집과 콜드 스타트 자동 수집은 @cloudcare/hvigor-ohos-plugin에 의존합니다. 이 플러그인은 빌드 시점 도구 패키지이며 애플리케이션 모듈의 oh-package.json5 런타임 의존성이 아닙니다.
주의: 콜드 스타트 측정은 첫 UI 프레임 렌더링을 종료 조건으로 합니다.
@cloudcare/hvigor-ohos-plugin0.1.1은ft_sdk0.1.17 이상을 요구합니다. HarmonyOS API 22 이상에서는 실제 첫 프레임을 수집합니다. API 22 미만에서는 완전한launch_coldAction과 콜드 스타트 총 소요 시간을 생성할 수 없습니다.
프로젝트 수준 hvigor/hvigor-config.json5에 플러그인 의존성을 추가합니다.
그런 다음 애플리케이션 HAP 모듈의 hvigorfile.ts에 플러그인을 등록합니다.
import { hapTasks } from '@ohos/hvigor-ohos-plugin';
import { ftConsoleLogPlugin } from '@cloudcare/hvigor-ohos-plugin';
export default {
system: hapTasks,
plugins: [ftConsoleLogPlugin()]
};
플러그인은 애플리케이션 src/main/ets 내의 호출만 변환하며, 디스크의 소스 코드나 SDK 의존성을 다시 작성하지 않습니다. 컴파일로 생성된 콜드 스타트 코드는 ft_sdk를 참조하므로 애플리케이션에는 여전히 ft_sdk 런타임 의존성이 유지되어야 합니다. 설정을 완료한 후 클린 빌드를 한 번 수행합니다. 플러그인을 설치하지 않으면 console, hilog 또는 콜드 스타트 데이터가 자동으로 수집되지 않습니다.
ft_sdk 0.1.18 이상 버전의 자동 수집은 Hvigor 플러그인과 함께 사용해야 합니다. 계측이 필요한 각 소스 모듈(HAP, HAR 또는 HSP)은 자체 oh-package.json5의 dependencies에 ft_sdk를 선언해야 합니다. Replay 자동 수집에는 ft_session_replay도 선언해야 합니다. 프로젝트 루트 디렉터리, 다른 모듈 또는 devDependencies에만 선언하면 해당 모듈의 자동 수집이 활성화되지 않습니다. 자세한 내용은 세션 리플레이 연동을 참고하세요.
콜드 스타트의 경우 진입점에서 가능한 한 이른 시점에 RUM을 설치하고 setEnableTraceUserAction(true)를 활성화해야 합니다. 완전한 애플리케이션 초기화 단계를 얻으려면 HAP의 module.json5에서 AbilityStage를 srcEntry로 설정하는 것을 권장합니다. 설정하지 않으면 새 버전 플러그인은 근사 단계 시간만 제공할 수 있습니다.
주의: 콜백을 포함한
windowStage.loadContent('pages/Index', (err) => { ... })작성 방식을 권장합니다. 플러그인은onWindowStageCreate()시작 부분에서 첫 프레임 리스너 등록을 시도하고, 페이지 로드 성공 콜백에서 등록을 추가로 시도합니다. 콜백이 없으면onWindowStageCreate()시작 부분에서 한 번만 등록을 시도합니다.
0.1.18에서는 프로세스당 최대 한 번 launch_cold를 보고하며, 동일 프로세스의 첫 UI 프레임 렌더링을 기다린 후 보고합니다. 소요 시간은 프로세스 시작부터 첫 프레임까지 계산되며, 첫 프레임 이전의 백그라운드 대기 시간을 포함합니다. 포그라운드/백그라운드 전환은 이미 기록된 단계 경계를 재설정하지 않습니다. 끝까지 UI 첫 프레임이 없는 프로세스는 콜드 스타트 Action을 생성하지 않습니다. 시작 Action은 여전히 Session 샘플링과 Action 필터의 제어를 받습니다.
SDK 추가¶
프로젝트 연동 방식에 따라 다음 설치 방안 중 하나를 선택할 수 있습니다.
방안 1: ohpm으로 설치¶
서드파티 저장소 설정이 완료된 경우 ohpm으로 바로 설치할 수 있습니다.
ohpm install @guancecloud/ft_sdk
ohpm install @guancecloud/ft_sdk_ext # 선택 사항
ohpm install @guancecloud/ft_native # 선택 사항
ohpm install @guancecloud/ft_session_replay # 선택 사항, 세션 리플레이(실험적)
방안 2: 로컬 HAR로 설치¶
HarmonyOS 공식 문서(HAR 패키지 가져오기 가이드)에 따라 먼저 HAR 획득 방법을 참고하여 설치 패키지를 준비한 다음, HAR 파일을 프로젝트의 libs 디렉터리에 두고 oh-package.json5에 필요한 scoped 의존성을 추가합니다.
{
"dependencies": {
"@guancecloud/ft_sdk": "file:../libs/ft_sdk.har",
"@guancecloud/ft_sdk_ext": "file:../libs/ft_sdk_ext.har", //선택 사항
"@guancecloud/ft_native": "file:../libs/ft_native.har", //선택 사항
"@guancecloud/ft_session_replay": "file:../libs/ft_session_replay.har" //선택 사항, 세션 리플레이(실험적)
}
}
HAR 패키지 의존성을 사용하는 경우, 프로젝트 루트 디렉터리의 oh-package.json5에 overrides를 함께 추가하여 모듈 내부의 원격 의존성을 로컬 HAR로 다시 작성하는 것을 권장합니다. 이렇게 하면 ft_sdk_ext가 원격 저장소에서 @guancecloud/ft_sdk를 계속 해석하지 않습니다.
그런 다음 실행합니다.
설치가 완료되면 HAR 패키지가 프로젝트의 oh_modules/ 디렉터리에 설치됩니다. scoped 의존성을 사용하는 경우 디렉터리는 일반적으로 oh_modules/@guancecloud/ft_sdk, oh_modules/@guancecloud/ft_sdk_ext, oh_modules/@guancecloud/ft_native, oh_modules/@guancecloud/ft_session_replay 형태로 나타납니다.
바이트코드 HAR 빌드 설정¶
ft_sdk 0.1.15, ft_sdk_ext 0.1.15 및 ft_native 0.1.1 배포 패키지는 바이트코드 HAR을 사용합니다. 이러한 패키지 중 하나를 연동할 때 다음을 확인하세요.
- 프로젝트는 HarmonyOS API 12 이상을 사용해야 합니다.
ft_sdk_ext의HttpInterceptorChain기능은 HarmonyOS API 22 이상을 요구합니다. - 프로젝트 루트 디렉터리의
build-profile.json5에서 실제 빌드 제품에 대해 정규화된 OHMUrl을 활성화합니다. 동일한 이름의 설정이 이미 있으면strictMode내용만 병합하면 됩니다.
{
"app": {
"products": [
{
"name": "default",
"buildOption": {
"strictMode": {
"useNormalizedOHMUrl": true
}
}
}
]
}
}
oh-package.json5의 의존성 이름은 SDK 패키지 이름과 일치해야 합니다. 코드는 각 패키지가 공개하는Index진입점에서만 API를 가져오고,src/main/...등의 내부 경로는 사용하지 않아야 합니다.- Release 패키지는 ArkGuard 난독화가 활성화되어 있으며, HAR과 함께 배포되는 소비자 난독화 규칙을 통해 공개 API를 유지합니다. SDK 패키지 내의
consumer-rules.txt를 삭제하거나 교체하지 마세요. 애플리케이션 자체에서 난독화를 활성화해도 SDK의 공개 기능을 정상적으로 호출할 수 있습니다.
HAR 획득 방법¶
새로운 HAR 획득 방법¶
- 해당 ohpm 페이지로 이동합니다.
- 대상 버전의
dist.tarball을 찾습니다. dist.tarball에서 해당 HAR 패키지를 다운로드하고 추출합니다.
해당 주소:
@guancecloud/ft_sdk: https://repo.harmonyos.com/ohpm/@guancecloud/ft_sdk@guancecloud/ft_sdk_ext: https://repo.harmonyos.com/ohpm/@guancecloud/ft_sdk_ext@guancecloud/ft_native: https://repo.harmonyos.com/ohpm/@guancecloud/ft_native
참고:
- 새 방식으로 다운로드할 때는 프로젝트 연동 버전과 일치하는
dist.tarball을 선택하세요. ft_sdk_ext와ft_sdk는 동일한 버전을 유지하는 것을 권장합니다.- 다운로드한 HAR 파일은 프로젝트의
libs/디렉터리에 넣어 로컬 HAR 방식으로 계속 연동할 수 있습니다.
이전 HAR 다운로드 방식¶
- 이전 버전
ft_sdk.har파일 다운로드: 다운로드 주소 - 필요에 따라
ft_sdk_ext.har파일 다운로드: 다운로드 주소 - 필요에 따라
ft_native.har파일 다운로드: 다운로드 주소
패키지 설명¶
실제 필요한 기능에 따라 관련 패키지를 선택적으로 추가하세요.
ft_sdk.har는 코어 패키지로 반드시 설치해야 합니다. 서드파티 저장소를 통해 설치할 때 해당 패키지 이름은@guancecloud/ft_sdk입니다.ft_sdk_ext.har는 확장 패키지입니다.@kit.NetworkKit기반HttpInterceptorChain자동 수집 기능이 필요할 때 설치합니다. 이 기능은 HarmonyOS API 22 이상을 요구합니다. 서드파티 저장소를 통해 설치할 때 해당 패키지 이름은@guancecloud/ft_sdk_ext입니다.ft_native.har는 선택 패키지로, Native Crash 등 네이티브 기능이 필요할 때만 설치합니다. 서드파티 저장소를 통해 설치할 때 해당 패키지 이름은@guancecloud/ft_native입니다.ft_session_replay.har는 선택 세션 리플레이 패키지로 코어 SDK에 의존합니다. 버전 요구 사항, 설치 및 초기화는 HarmonyOS 세션 리플레이(실험적)를 참고하세요.- 실제로 사용하는 HAR 파일만
libs/디렉터리에 넣으면 됩니다. 디렉터리가 없으면 먼저 생성하고, HAR 파일이 현재 프로젝트 루트 디렉터리에 있으면libs/디렉터리로 먼저 이동하세요.
가져오기 방식¶
다음과 같이 가져올 수 있습니다.
HttpInterceptorChain 기반 HTTP 자동 수집 기능을 사용하려면 @guancecloud/ft_sdk_ext에서 가져옵니다.
설명:
@guancecloud/ft_sdk: 기본 연동 및 Axios 호환 모드의 가져오기 진입점@guancecloud/ft_sdk_ext:HttpInterceptorChain자동 수집의 가져오기 진입점(HarmonyOS API 22 이상 필요)applyFTAxiosTrack등 Axios 호환 경로는 여전히@guancecloud/ft_sdk에서 내보냅니다.
권한 설명¶
SDK에는 다음 권한 선언이 자동으로 포함되어 있으므로 수동으로 추가 설정할 필요가 없습니다.
| 권한 이름 | 용도 설명 |
|---|---|
ohos.permission.INTERNET |
네트워크 액세스 권한으로, 데이터 보고 및 네트워크 요청 추적에 사용됩니다. |
ohos.permission.GET_WIFI_INFO |
WiFi 정보 조회 권한으로, 네트워크 유형 감지 및 신호 강도 수집에 사용됩니다. |
ohos.permission.GET_NETWORK_INFO |
네트워크 정보 조회 권한으로, 네트워크 상태 모니터링 및 유형 식별에 사용됩니다. |
상세 설정 진입점¶
고급 시나리오¶
- 사용자 정의 태그와 전역 컨텍스트
- 데이터 수집 사용자 정의 규칙
- 데이터 수집 마스킹
- 동적 설정과 동적 업데이트 주소
- WebView 데이터 모니터링
- HarmonyOS 세션 리플레이(실험적)
이전 설정 마이그레이션¶
이 문서는 HarmonyOS SDK를 이전 버전 패키지 이름 및 딥 경로 가져오기에서 현재의 scoped 패키지 이름과 공개 Index 진입점으로 마이그레이션하는 방법을 설명하며, 다음 세 가지 유형의 프로젝트에 적용됩니다.
- 로컬 HAR 방식으로 연동했으며
ft_sdk.har,ft_sdk_ext.har,ft_native.har를 사용한 적이 있는 프로젝트 ohpm으로 설치했지만 여전히 이전 버전의 scope가 없는 패키지 이름 설정 또는 딥 경로 가져오기를 사용하는 프로젝트@guancecloud/scoped 패키지 이름으로 마이그레이션했지만 코드가 여전히@guancecloud/ft_sdk/src/main/...또는@guancecloud/ft_sdk_ext/src/main/...딥 경로에서 가져오는 프로젝트
마이그레이션 내용 개요¶
ft_sdk->@guancecloud/ft_sdkft_sdk_ext->@guancecloud/ft_sdk_extft_native->@guancecloud/ft_native@guancecloud/ft_sdk/src/main/...->@guancecloud/ft_sdk/Index@guancecloud/ft_sdk_ext/src/main/...->@guancecloud/ft_sdk_ext/Index
참고:
- HAR 파일 이름 자체는
ft_sdk.har,ft_sdk_ext.har,ft_native.har를 그대로 사용할 수 있습니다. - 조정해야 하는 것은
oh-package.json5의 의존성 이름과 코드의 가져오기 경로이며, SDK가 공개하는Index진입점을 통일해서 사용하는 것을 권장합니다. - 로컬 HAR 설치든
ohpm설치든 의존성 이름은 scoped 패키지 이름으로 통일해 마이그레이션하고, 코드 가져오기는 공개Index진입점으로 통일해 마이그레이션해야 합니다. @guancecloud/.../src/main/...는 이전 버전의 scoped 딥 경로 작성 방식이며, 마이그레이션 참고 자료로는 사용할 수 있지만 최신 권장 연동 방식은 아닙니다.- 로컬 HAR 패키지를 다시 받아야 하는 경우 HAR 획득 방법을 참고하세요.
설정 파일 변경¶
이전 작성 방식:
//root/entry/oh-package.json5
{
"dependencies": {
"ft_sdk": "file:../libs/ft_sdk.har",
"ft_sdk_ext": "file:../libs/ft_sdk_ext.har",
"ft_native": "file:../libs/ft_native.har"
}
}
이전 scoped 딥 경로 작성 방식:
//root/entry/oh-package.json5
{
"dependencies": {
"@guancecloud/ft_sdk": "file:../libs/ft_sdk.har",
"@guancecloud/ft_sdk_ext": "file:../libs/ft_sdk_ext.har",
"@guancecloud/ft_native": "file:../libs/ft_native.har"
}
}
//root/oh-package.json5
{
"overrides": {
"@guancecloud/ft_sdk": "file:./libs/ft_sdk.har"
}
}
ohpm으로 설치하는 경우에도 의존성 이름을 scoped 패키지 이름으로 변경해야 합니다. 예:
ohpm install @guancecloud/ft_sdk
ohpm install @guancecloud/ft_sdk_ext
ohpm install @guancecloud/ft_native
비교 설명:
- 새 작성 방식은 의존성 이름을 기존
ft_sdk,ft_sdk_ext,ft_native에서 scoped 패키지 이름으로 변경합니다. ohpm으로 설치하는 경우에도 새로운 scoped 패키지 이름으로 설치 명령을 실행해야 합니다.overrides는 프로젝트 루트 디렉터리의oh-package.json5에 설정해야 합니다.- 프로젝트가 로컬 HAR 방식으로
ft_sdk_ext.har를 연동할 때overrides["@guancecloud/ft_sdk"]는 그 내부의 원격 의존성을 로컬ft_sdk.har로 다시 작성하는 데 사용됩니다. ft_sdk.har또는ft_native.har만 사용하는 경우 실제 필요에 따라 해당dependencies를 유지할 수 있습니다.
코드 가져오기 변경¶
이전 작성 방식:
import { FTSDK } from 'ft_sdk/src/main/ets/components/FTSDK';
import { FTSDKConfig } from 'ft_sdk/src/main/ets/components/Configs';
import { createFTHttpInterceptorChain } from 'ft_sdk_ext/src/main/ets/components/network/FTHttpAutoTrackExt';
새 작성 방식:
import { FTSDK } from '@guancecloud/ft_sdk/src/main/ets/components/FTSDK';
import { FTSDKConfig } from '@guancecloud/ft_sdk/src/main/ets/components/Configs';
import { createFTHttpInterceptorChain } from '@guancecloud/ft_sdk_ext/src/main/ets/components/network/FTHttpAutoTrackExt';
새 작성 방식:
import { FTSDK, FTSDKConfig } from '@guancecloud/ft_sdk/Index';
import { createFTHttpInterceptorChain } from '@guancecloud/ft_sdk_ext/Index';
마이그레이션 단계¶
- HAR 파일을 프로젝트의
libs/디렉터리에 넣습니다. - 프로젝트의 의존성 이름을 기존 패키지 이름에서 새로운 scoped 패키지 이름으로 변경합니다.
- 프로젝트가 로컬 HAR 방식으로
ft_sdk_ext.har를 사용하는 경우 프로젝트 루트 디렉터리의oh-package.json5에overrides를 추가합니다. - 프로젝트가
ohpm으로 설치하는 경우 새로운 scoped 패키지 이름으로 설치 명령을 다시 실행합니다. 프로젝트가 로컬 HAR로 설치하는 경우ohpm install을 실행합니다. - 코드의 이전 가져오기 경로 또는 이전의
@guancecloud/.../src/main/...scoped 딥 경로를 공개Index진입점으로 교체합니다.
자주 묻는 질문¶
전역 변수를 추가할 때 충돌 필드를 피하는 방법¶
사용자 정의 필드가 SDK 데이터와 충돌하지 않도록 태그 이름에 비즈니스 접두사를 추가하는 것을 권장합니다(예: df_tag_name). SDK 전역 변수와 RUM, Log에 동일한 이름의 필드가 있는 경우 RUM, Log의 필드가 SDK 전역 변수를 덮어씁니다.
사용자 정의 태그 사용 방법은 사용자 정의 태그와 전역 컨텍스트를 계속 읽어보세요.