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 RID	`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를 재사용하는 프레임워크는 창과 컨트롤의 수명 주기를 직접 관리해야 합니다.

앱 통합¶

통합 방식 선택¶

통합 방식	대상 애플리케이션	설치 방법	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와 Native 측에서 Session, 큐, 업로드 관리

앱 생성¶

Guance 콘솔에 로그인하여 「사용자 액세스 모니터링」으로 이동한 후 「앱 생성」을 클릭하세요:

앱 이름과 앱 ID를 입력합니다.
앱 유형으로 「사용자 정의」를 선택합니다.
앱 ID를 저장합니다. RumAppId 또는 rum_app_id에 사용됩니다.

동일한 Windows 제품의 C#, C++, WebView2 및 Electron은 동일한 앱 ID를 사용할 수 있으며, service, version 및 런타임 태그를 통해 데이터를 구분합니다.

설치¶

.NET / C#Native C/C++Electron

dotnet add package Guance.Windows --version [latest_version]

예제:

GuanceCloud 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++ 헤더 파일과 임포트 라이브러리는 포함하지 않습니다.

Renderer에 Browser SDK를 설치합니다:

npm install @cloudcare/browser-rum @cloudcare/browser-logs

Electron 전체 모드를 사용하려면 빠른 시작에 따라 GuanceCloud vcpkg 레지스트리를 먼저 설정한 후, vcpkg.json에서 guance-windows-native의 electron-bridge Feature를 활성화하고 매니페스트 모드로 vcpkg install --triplet x64-windows를 실행하세요. 이 Feature는 Bridge EXE와 일치하는 Native DLL을 설치합니다. 두 파일은 함께 패키징되어야 합니다.

C++ 초기화의 혼합 모드는 Bridge EXE를 시작하지 않으며, C++ 호스트가 기존 SDK Handle에 쓰는 Adapter를 제공합니다. 전체 설치, 패키징 및 기능 경계는 Electron 모니터링을 참조하세요.

소스 코드 주소: GuanceCloud/datakit-windows-desktop

초기화 설명¶

전송 방식¶

공용 DataWay로컬 환경 배포(Datakit)

런타임	주소	자격 증명
.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 수집기를 활성화해야 합니다.

초기화 순서¶

.NET / C#Native C/C++

// config에는 최소한 전송 주소와 RUM 앱 정보가 포함되어야 합니다. Log/Trace는 필요에 따라 추가합니다.
GuanceSdk.Init(config);
GuanceSdk.EnableAutomaticInstrumentation();

// 앱 종료 전에 실행합니다.
await GuanceSdk.ShutdownAsync();

guance_sdk_handle rum = guance_sdk_init(&config);
guance_rum_start_view(rum, "MainWindow");

// 메시지 루프 종료 후 실행합니다.
guance_rum_stop_view(rum);
guance_sdk_shutdown(rum);

Log 또는 Trace가 필요한 경우, guance_sdk_init() 성공 후 각각 guance_log_configure(), guance_trace_configure()를 호출합니다.

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 관련 문제는 장애 진단을 참조하세요.