Windows 애플리케이션 연동¶
Windows SDK는 .NET/C#과 Native C/C++에 통합된 RUM, Log, HTTP Trace 연관 기능을 제공합니다. 애플리케이션은 런타임에 따라 연동 방식을 선택하며, 데이터는 동일한 애플리케이션 ID, 서비스, 환경 차원을 사용하여 콘솔로 전달됩니다.
읽기 경로¶
- 최초 연동: 먼저 연동 방식 선택을 확인합니다. 수동 연동은 빠른 시작을 참고합니다.
- 전체 연동: 이 문서를 계속 읽습니다.
- 파라미터 상세: SDK 초기화, RUM 설정, Log 설정, Trace 설정을 확인합니다.
- 고급 기능: "고급 시나리오" 그룹의 전용 페이지를 확인합니다.
- 문제 해결: 트러블슈팅을 확인합니다.
사전 요구 사항¶
지원 범위¶
| 항목 | 지원 범위 |
|---|---|
| 운영 체제 | Windows 10+ |
| .NET 대상 프레임워크 | net6.0 / net8.0 |
| Native 표준 | C11 ABI, C++17 어댑터 |
| NuGet Native RIDs | win-x64 / win-x86 / win-arm64 |
| vcpkg Native | 동적 x64-windows, 비 UWP |
| 배포 방식 | NuGet / vcpkg |
| 데이터 보고 | 공용 네트워크 DataWay, 로컬 환경 배포(Datakit) |
| RUM | View, Action, Resource, Error, Long Task |
| Log | 사용자 정의/배치 Log, 독립 큐, RUM 연관; C#은 System.Diagnostics.Trace 수집 지원 |
| Trace | HTTP Header 전파 및 RUM Resource 연관, 독립 APM Span 업로드하지 않음 |
| Session Replay | 기본적으로 비활성화됨. 일치하는 선택적 컴포넌트를 설치한 후 명시적으로 활성화해야 함. WPF, WinForms, WinUI 3, WebView2, Electron, Native 지원. 현재 실험적 기능 |
기능 경계
Session Replay는 명시적으로 활성화하고 검증할 수 있지만 여전히 실험적 기능이며 안정적인 호환성 보장에 포함되지 않습니다. Avalonia, .NET MAUI, UWP에는 별도의 자동 수집 어댑터가 없으며, Native C ABI를 재사용할 수 있는 프레임워크는 윈도우와 컨트롤 수명 주기를 직접 관리해야 합니다.
애플리케이션 연동¶
SDK 및 런타임 선택¶
| SDK 및 런타임 | 적용 애플리케이션 | 설치 방식 | UI 경계 |
|---|---|---|---|
| .NET / C# | WPF, WinForms, WinUI 3 | Guance.Windows NuGet |
프레임워크 자동 수집; WinUI 3은 Window를 명시적으로 연관 |
| Native C/C++ | Win32, HWND 기반 데스크톱 프레임워크 |
CMake, 헤더 파일, 가져오기 라이브러리, guance_windows_native.dll |
윈도우와 컨트롤 수명 주기를 C ABI로 명시적 호출 |
| WebView2 | .NET 호스트의 Edge WebView2 | .NET SDK와 함께 제공 | 컨트롤 자동 검색 또는 명시적 연관 |
| Electron | Electron Renderer + Windows Native Bridge | Browser SDK + guance-windows-native[electron-bridge] |
Browser SDK는 수집과 직렬화만 수행; 신뢰할 수 있는 Main Process와 네이티브 측이 Session, 큐, 업로드를 관리 |
애플리케이션 생성¶
Guance 콘솔에 로그인하고 「RUM」으로 이동한 뒤 「애플리케이션 생성」을 클릭합니다:
- 애플리케이션 이름과 애플리케이션 ID를 입력합니다.
- 애플리케이션 유형에서 「사용자 정의」를 선택합니다.
- 애플리케이션 ID를 저장하여
RumAppId또는rum_app_id에 사용합니다.
동일한 Windows 제품의 C#, C++, WebView2, Electron은 동일한 애플리케이션 ID를 사용할 수 있으며, service, version 및 런타임 태그로 데이터를 구분합니다.
연동 방식 선택¶
애플리케이션 설정 페이지에서 「Agent 자동 연동」 또는 「수동 연동」을 선택한 후 「연동 설정」을 완료합니다. 기존 애플리케이션은 설정 페이지로 바로 이동하여 연동을 계속할 수 있습니다.
| 연동 방식 | 사용 사례 | 작업 진입점 |
|---|---|---|
| Agent 자동 연동 | 프로그래밍 어시스턴트가 프로젝트를 분석하고 SDK 연동을 완료하기를 원하는 경우 | 콘솔에서 생성된 프롬프트를 복사하여 애플리케이션 코드 저장소에서 프로그래밍 어시스턴트에게 실행하도록 전달 |
| 수동 연동 | SDK를 직접 설치하고 파라미터를 설정하려는 경우 | 데이터 보고 방식을 확인한 후 이 문서와 빠른 시작에 따라 설정 완료 |
Agent 자동 연동¶
- 현재 애플리케이션의 설정 페이지에서 「Agent 자동 연동」을 선택합니다.
- 「연동 설정」의 전체 프롬프트를 복사하고, 현재 애플리케이션의 연동 정보가 사용되는지 확인합니다.
- 애플리케이션 코드 저장소에서 프로그래밍 어시스턴트를 열고 프롬프트를 붙여넣으면, Agent가 연동 가이드에 따라 프로젝트를 분석하고 SDK 설정을 완료합니다.
- 애플리케이션을 빌드하고 실행하여 페이지 접근 등의 작업을 트리거한 뒤, 현재 애플리케이션의 탐색기에서 데이터 수신을 확인합니다.
페이지에서 개인 API Key 또는 임시 인증 코드가 준비되지 않았다고 표시되면, 안내에 따라 보완한 후 프롬프트를 다시 복사합니다.
수동 연동¶
애플리케이션 설정 페이지에서 「수동 연동」을 선택하고 데이터 보고 방식을 확인합니다:
- 공용 네트워크 DataWay: 현재 애플리케이션의 연동 설정에서 보고 주소와 Client Token을 가져오며, DataKit을 직접 배포할 필요가 없습니다.
- 로컬 환경 배포: 이미 배포된 DataKit을 사용하여 데이터를 수신하며, 애플리케이션이 해당 보고 주소에 접근할 수 있어야 합니다.
아래 설치와 빠른 시작에 따라 SDK 설치, 초기화 및 검증을 완료합니다. 이미 SDK 설정이 있는 경우 먼저 확인하고 재사용하여 중복 초기화를 피해야 합니다.
설치¶
Session Replay를 사용하는 경우 동일 버전의 Guance.Windows.SessionReplay를 추가합니다. 설치 및 마이그레이션 요구 사항은 선택적 컴포넌트 설치를 참고합니다.
예시:
SDK vcpkg 레지스트리를 통해 guance-windows-native를 설치하는 것을 권장합니다. 레지스트리, 매니페스트 및 CMake 설정은 빠른 시작에 따라 완료하고, 설치 후 공개 CMake Target을 링크합니다:
find_package(GuanceWindowsNative CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE Guance::WindowsNative)
SDK 소스를 디버깅해야 하는 경우 직접 빌드할 수도 있습니다:
git clone https://github.com/GuanceCloud/datakit-windows-desktop.git
cd datakit-windows-desktop
cmake -S src/Guance.Windows.Native -B build/native -A x64
cmake --build build/native --config Release
공개 헤더 파일:
guance_rum.h: C11 ABI로, C와 C++ 모두 사용 가능;guance_sdk.hpp: C++ 스코프 Resource 및std::terminate어댑터;guance_rum_winhttp.hpp: 동기 및 비동기 WinHTTP Resource/Trace 어댑터.
애플리케이션, 가져오기 라이브러리, DLL의 아키텍처는 반드시 일치해야 합니다. 현재 vcpkg 포트는 동적 x64-windows만 제공하며, NuGet 패키지에 포함된 x86, x64, ARM64 Native DLL은 .NET 래퍼 레이어에서 사용되고 C/C++ 헤더 파일과 가져오기 라이브러리는 포함하지 않습니다. Session Replay는 동일 port의 replay Feature를 통해 설치합니다.
Main Process Adapter와 Renderer Browser SDK를 설치합니다:
Electron 전체 모드에서는 npm Adapter가 기본 런타임을 다운로드하고 Bridge EXE를 관리합니다. Replay를 사용하는 경우 동일 버전, 동일 아키텍처의 Replay 보충 아카이브를 명시적으로 설치하고 기본 런타임과 함께 ASAR 외부에 패키징해야 합니다.
C++로 초기화하는 혼합 모드에서는 호스트가 named-pipe Bridge Server를 시작하고 Electron Adapter가 기존 SDK Handle에 연결합니다. Replay 컴포넌트는 호스트의 vcpkg replay Feature에서 제공됩니다. 전체 설치, 패키징 및 기능 경계는 Electron 모니터링을 참고합니다.
소스 코드 주소: Windows SDK 소스 코드
초기화 설명¶
보고 방식¶
| 런타임 | 주소 | 자격 증명 |
|---|---|---|
| .NET / C# | GuanceConfig.DatawayUrl |
GuanceConfig.ClientToken |
| Native C/C++ | guance_sdk_config.dataway_url |
guance_sdk_config.client_token |
| 런타임 | 주소 | 자격 증명 |
|---|---|---|
| .NET / C# | GuanceConfig.DatakitUrl |
Client Token 불필요 |
| Native C/C++ | guance_sdk_config.datakit_url |
Client Token 불필요 |
로컬 환경 배포를 사용하기 전에 DataKit을 설치하고 RUM 수집기를 활성화해야 합니다.
초기화 순서¶
SDK는 디스크 큐를 사용하여 RUM과 Log를 캐시합니다. 정상 종료 시 종료 절차를 완료하여 프로세스가 종료될 때 아직 영속화되지 않은 작업이 남지 않도록 합니다.
상세 설정 진입점¶
- 기본 주소, 식별 정보, 큐 및 수명 주기: SDK 초기화
- View, Action, Resource, Error, Long Task: RUM 설정
- 사용자 정의 로그 및 자동 Trace 출력: Log 설정
- HTTP Trace Header와 RUM 연관: Trace 설정
고급 시나리오¶
- WPF, WinForms, WinUI 3 및 Native UI: 데스크톱 UI 프레임워크
- WebView2 페이지 모니터링: WebView2 모니터링
- Electron Renderer 및 Native Bridge: Electron 모니터링
- 프라이버시, 권한 및 데이터 마스킹: 프라이버시 및 권한 설명
자주 묻는 질문¶
초기화, 데이터 보고, 데스크톱 UI, WebView2, Electron, Log, Trace 및 Session Replay 관련 문제는 트러블슈팅을 참고합니다.