콘텐츠로 이동

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를 재사용할 수 있는 프레임워크는 윈도우와 컨트롤 수명 주기를 직접 관리해야 합니다.

애플리케이션 연동

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」으로 이동한 뒤 「애플리케이션 생성」을 클릭합니다:

  1. 애플리케이션 이름과 애플리케이션 ID를 입력합니다.
  2. 애플리케이션 유형에서 「사용자 정의」를 선택합니다.
  3. 애플리케이션 ID를 저장하여 RumAppId 또는 rum_app_id에 사용합니다.

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

연동 방식 선택

애플리케이션 설정 페이지에서 「Agent 자동 연동」 또는 「수동 연동」을 선택한 후 「연동 설정」을 완료합니다. 기존 애플리케이션은 설정 페이지로 바로 이동하여 연동을 계속할 수 있습니다.

연동 방식 사용 사례 작업 진입점
Agent 자동 연동 프로그래밍 어시스턴트가 프로젝트를 분석하고 SDK 연동을 완료하기를 원하는 경우 콘솔에서 생성된 프롬프트를 복사하여 애플리케이션 코드 저장소에서 프로그래밍 어시스턴트에게 실행하도록 전달
수동 연동 SDK를 직접 설치하고 파라미터를 설정하려는 경우 데이터 보고 방식을 확인한 후 이 문서와 빠른 시작에 따라 설정 완료

Agent 자동 연동

  1. 현재 애플리케이션의 설정 페이지에서 「Agent 자동 연동」을 선택합니다.
  2. 「연동 설정」의 전체 프롬프트를 복사하고, 현재 애플리케이션의 연동 정보가 사용되는지 확인합니다.
  3. 애플리케이션 코드 저장소에서 프로그래밍 어시스턴트를 열고 프롬프트를 붙여넣으면, Agent가 연동 가이드에 따라 프로젝트를 분석하고 SDK 설정을 완료합니다.
  4. 애플리케이션을 빌드하고 실행하여 페이지 접근 등의 작업을 트리거한 뒤, 현재 애플리케이션의 탐색기에서 데이터 수신을 확인합니다.

페이지에서 개인 API Key 또는 임시 인증 코드가 준비되지 않았다고 표시되면, 안내에 따라 보완한 후 프롬프트를 다시 복사합니다.

수동 연동

애플리케이션 설정 페이지에서 「수동 연동」을 선택하고 데이터 보고 방식을 확인합니다:

  • 공용 네트워크 DataWay: 현재 애플리케이션의 연동 설정에서 보고 주소와 Client Token을 가져오며, DataKit을 직접 배포할 필요가 없습니다.
  • 로컬 환경 배포: 이미 배포된 DataKit을 사용하여 데이터를 수신하며, 애플리케이션이 해당 보고 주소에 접근할 수 있어야 합니다.

아래 설치와 빠른 시작에 따라 SDK 설치, 초기화 및 검증을 완료합니다. 이미 SDK 설정이 있는 경우 먼저 확인하고 재사용하여 중복 초기화를 피해야 합니다.

설치

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

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를 설치합니다:

npm install @cloudcare/electron-native-adapter@alpha @cloudcare/browser-rum @cloudcare/browser-logs

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 수집기를 활성화해야 합니다.

초기화 순서

// 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 설정

고급 시나리오

자주 묻는 질문

초기화, 데이터 보고, 데스크톱 UI, WebView2, Electron, Log, Trace 및 Session Replay 관련 문제는 트러블슈팅을 참고합니다.

문서 평가

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