콘텐츠로 이동

Windows 앱 연동

Windows SDK는 .NET/C# 및 Native C/C++에 RUM, Log, HTTP Trace를 연관시키는 통합 기능을 제공합니다. 애플리케이션은 런타임에 따라 연동 방식을 선택하며, 데이터는 동일한 앱 ID, 서비스, 환경 차원으로 콘솔에 유입됩니다.

읽기 경로

사전 요구 사항

지원 범위

항목 지원 범위
운영 체제 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를 재사용할 수 있는 프레임워크는 창과 컨트롤 수명 주기를 직접 관리해야 합니다.

앱 연동

연동 방식 선택

연동 방식 적용 앱 설치 방법 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」으로 이동한 다음 「새 앱 만들기」를 클릭합니다:

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

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

설치

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

예시:

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++ scope 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 전체 모드는 먼저 빠른 시작에 따라 SDK vcpkg 레지스트리를 구성한 다음, vcpkg.json에서 guance-windows-native에 electron-bridge 기능을 활성화하고 매니페스트 모드로 vcpkg install --triplet x64-windows를 실행해야 합니다. 이 기능은 Bridge EXE와 일치하는 Native DLL을 설치하며, 두 파일은 반드시 함께 패키징해야 합니다.

C++로 초기화하는 혼합 모드는 Bridge EXE를 시작하지 않으며, C++ 호스트가 기존 SDK Handle에 쓰는 Adapter를 제공합니다. 전체 설치, 패키징, 기능 경계는 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 수집기를 활성화해야 합니다.

초기화 순서

// 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를 캐시합니다. 정상 종료 시 종료 절차를 완료하여 프로세스가 종료될 때 아직 영속화되지 않은 작업이 남지 않도록 합니다.

상세 설정 바로가기

고급 시나리오

자주 묻는 질문

초기화, 데이터 전송, 데스크톱 UI, WebView2, Electron, Log, Trace, Session Replay 관련 문제는 문제 해결을 참고하세요.

문서 평가

이 페이지가 도움이 되었나요?