콘텐츠로 이동

빠른 시작

Windows SDK는 독립적으로 배포되는 두 개의 패키지를 동시에 제공합니다. .NET/C# 애플리케이션은 NuGet을 통해 Guance.Windows를 사용하고, Native C/C++ 애플리케이션은 GuanceCloud의 vcpkg 레지스트리를 통해 guance-windows-native를 사용합니다. 두 패키지는 동일한 RUM 애플리케이션 ID와 데이터 전송 방식을 사용하지만, 패키지 버전, 업그레이드 주기 및 변경 로그는 서로 독립적입니다.

사전 준비

  1. 「실제 사용자 모니터링(RUM)」에서 「커스텀」 애플리케이션을 생성하고 애플리케이션 ID를 획득합니다.
  2. 데이터 전송 방식을 하나 준비합니다:
  3. 공용 DataWay: 전송 주소와 Client Token
  4. 로컬 환경 배포(DataKit): 애플리케이션 프로세스가 접근 가능한 DataKit 주소
  5. 애플리케이션이 Windows 10 이상에서 실행되는지 확인합니다.

연동 절차

  1. 애플리케이션 기술 스택에 따라 NuGet 또는 vcpkg 패키지를 선택합니다.
  2. 의존성을 설치하고 RUM 애플리케이션 및 전송 구성을 입력합니다.
  3. SDK를 초기화하고 필요에 따라 자동 수집, Log, Trace 및 Session Replay를 활성화합니다.
  4. 애플리케이션을 실행하고 콘솔에서 데이터 전송 성공을 확인합니다.

패키지 선택

애플리케이션 유형 패키지 설치 방식 현재 지원
.NET / C# Guance.Windows NuGet.org net6.0, net8.0, net6.0-windows10.0.17763.0, net8.0-windows10.0.17763.0; x86, x64, ARM64 네이티브 런타임 자산
Native C/C++ guance-windows-native GuanceCloud vcpkg 레지스트리 Windows x64, 비 UWP; 첫 번째 버전은 동적 라이브러리
버전 정보

본 문서에서는 [latest_version]을 사용하여 최신 버전을 나타냅니다. NuGet 검색 인터페이스에서 시험판 패키지를 활성화해야 합니다. 프로덕션 프로젝트에서는 [latest_version]을 검증된 특정 버전으로 대체하고 의존성을 고정하세요.

.NET / C#: NuGet 사용

프로젝트 디렉터리에서 설치:

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

또는 프로젝트 파일에 추가:

<PackageReference Include="Guance.Windows" Version="[latest_version]" />

NuGet 패키지는 런타임 식별자(RID)에 따라 다음 Native DLL을 자동으로 포함하므로 수동으로 복사할 필요가 없습니다:

runtimes/win-x64/native/guance_windows_native.dll
runtimes/win-arm64/native/guance_windows_native.dll
runtimes/win-x86/native/guance_windows_native.dll

Native C/C++: vcpkg 사용

GuanceCloud 레지스트리 구성

프로젝트 루트 디렉터리에 vcpkg-configuration.json을 생성하거나 업데이트합니다. 기본 레지스트리 기준선을 프로젝트에서 검증된 Microsoft vcpkg 커밋으로 대체하고, <latest-guance-vcpkg-registry-commit>은 GuanceCloud 레지스트리의 최신 커밋을 나타냅니다. 연동 시에는 플레이스홀더를 실제 커밋으로 대체하고 고정하여 빌드 재현성을 보장하세요.

{
  "default-registry": {
    "kind": "git",
    "repository": "https://github.com/microsoft/vcpkg",
    "baseline": "<compatible-microsoft-vcpkg-commit>"
  },
  "registries": [
    {
      "kind": "git",
      "repository": "https://github.com/GuanceCloud/gc-vcpkg-registry.git",
      "baseline": "<latest-guance-vcpkg-registry-commit>",
      "packages": [
        "guance-windows-native"
      ]
    }
  ]
}

의존성 선언 및 설치

프로젝트 루트 디렉터리의 vcpkg.json에 포트를 선언합니다:

{
  "dependencies": [
    "guance-windows-native"
  ]
}

그런 다음 매니페스트 모드로 설치합니다:

vcpkg install

CMake 링크

CMake 구성 시 vcpkg toolchain 파일을 전달하고, CMakeLists.txt에서 패키지를 찾아 링크합니다:

find_package(GuanceWindowsNative CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE Guance::WindowsNative)

C 헤더 파일 guance_sdk.h, 각 신호 전용 C 헤더 파일 guance_rum.h, guance_trace.h, guance_log.h 또는 C++ 도우미 헤더 파일 guance_sdk.hpp를 사용할 수 있습니다. 전체 C API는 공개된 guance_sdk.h를 참조하세요.

최소 초기화 예제

초기화 시에는 반드시 RUM 애플리케이션 ID, 서비스 이름, 환경 및 애플리케이션 버전을 입력해야 합니다. 공용 DataWay 모드는 DatawayUrl과 ClientToken을 사용하며, 로컬 환경 배포(DataKit)를 사용하는 경우 DatakitUrl만 설정하고 공용 네트워크 토큰은 필요하지 않습니다.

using Guance.Windows;

GuanceSdk.Init(new GuanceConfig
{
    DatawayUrl = "https://openway.<your-domain>",
    ClientToken = "<client-token>",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "prod",
    Version = "1.0.0"
});

GuanceSdk.EnableAutomaticInstrumentation();

using Guance.Windows;

GuanceSdk.Init(new GuanceConfig
{
    DatakitUrl = "http://127.0.0.1:9529",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "local",
    Version = "1.0.0"
});

#include "guance_sdk.h"

guance_sdk_config config;
guance_sdk_config_init(&config);
config.dataway_url = "https://openway.<your-domain>";
config.client_token = "<client-token>";
config.rum_app_id = "<rum-app-id>";
config.service_name = "native-client";
config.env = "prod";
config.version = "1.0.0";

guance_sdk_handle sdk = guance_sdk_init(&config);
if (sdk == nullptr) {
    // 초기화 실패 처리.
}

#include "guance_sdk.h"

guance_sdk_config config;
guance_sdk_config_init(&config);
config.datakit_url = "http://127.0.0.1:9529";
config.rum_app_id = "<rum-app-id>";
config.service_name = "native-client";
config.env = "local";
config.version = "1.0.0";

guance_sdk_handle sdk = guance_sdk_init(&config);

초기화를 한 번 수행한 후, 애플리케이션이 종료되기 전에 명시적으로 큐를 처리하고 SDK를 종료합니다:

await GuanceSdk.ShutdownAsync();

guance_sdk_flush(sdk);
guance_sdk_shutdown(sdk);

선택 사항: Log, Trace 및 Session Replay 초기화

  • .NET/C#은 WPF, WinForms, WinUI 3, HttpClient, 처리되지 않은 예외 및 UI 스레드 차단을 선택적으로 자동 수집할 수 있습니다. 첫 번째 창이 생성되기 전에 GuanceSdk.EnableAutomaticInstrumentation()을 호출하세요. Native C/C++는 공개 C API를 통해 창, 명령 및 네트워크 경계에서 명시적으로 연동합니다.
  • Trace Header는 신뢰할 수 있는 서비스에만 전송해야 합니다. Trace 구성의 대상 주소 허용 목록을 통해 Header를 삽입할 수 있는 요청을 제한하세요.
  • SDK는 기본적으로 개인 정보 보호 구성을 사용합니다. Session Replay는 기본적으로 비활성화되어 있으며 명시적으로 활성화해야 합니다. 이는 아직 실험적인 기능이며 안정적인 호환성 약속에 포함되지 않습니다.

UI, WebView2, Electron 및 각 신호 구성에 대한 자세한 내용은 데스크톱 UI 프레임워크, WebView2 모니터링, Electron 모니터링, RUM 구성, Log 구성 및 Trace 구성을 참조하세요.

연동 성공 확인

  1. 애플리케이션을 시작하고 최소한 하나의 View를 엽니다.
  2. 클릭 작업을 한 번 수행하고, HTTP 요청을 한 번 실행합니다.
  3. 「실제 사용자 모니터링(RUM) > 탐색기」에서 해당 애플리케이션을 선택하고 Session, View, Action 및 Resource 데이터가 나타나는지 확인합니다.
  4. Log 또는 Trace를 활성화한 후, 각각 로그 데이터와 Trace Header/RUM Resource 연동이 정상인지 확인합니다.
  5. Session Replay를 활성화한 후, Replay 업로드 진단 상태가 성공인지 확인하고 세션 상세에서 리플레이 진입점을 확인합니다.

콘솔에 데이터가 표시되지 않으면 문제 해결을 참조하세요.

다음 단계

업그레이드 및 변경 로그

NuGet과 vcpkg는 독립적인 버전 스트림을 사용하므로, 버전 번호가 동일하더라도 동일한 릴리스로 간주할 수 없습니다:

배포 방식 버전 태그 변경 로그
NuGet / C# nuget_<semver> C# 변경 로그
vcpkg / Native C/C++ vcpkg_<semver> Native C/C++ 변경 로그

안정 버전 1.2.3과 1.2.3-alpha.1, 1.2.3-beta.1 형식의 시험판 버전을 지원합니다. 업그레이드 시에는 각 패키지의 변경 로그를 각각 확인하고, NuGet 버전 또는 vcpkg 레지스트리 기준선을 업데이트하세요. 두 배포 스트림은 변경 로그에서 영역별로 구분하여 표시됩니다.

자주 묻는 질문

  • Visual Studio의 NuGet UI에서 패키지를 찾을 수 없는 경우: 「시험판 포함」을 활성화하거나, 본 문서에 제공된 dotnet add package 명령을 사용하세요.
  • vcpkg install에서 포트를 찾을 수 없는 경우: vcpkg-configuration.json의 레지스트리 URL, packages 목록 및 고정된 기준선이 올바른지 확인하고, 프로젝트 루트 디렉터리에서 매니페스트 모드로 설치를 실행하세요.
  • .NET 애플리케이션이 Native DLL을 로드하지 못하는 경우: 프로젝트 대상 프레임워크가 본 페이지에 나열된 지원 프레임워크인지, 그리고 게시 시 RID가 배포 환경 아키텍처와 일치하는지 확인하세요.

문서 평가

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