빠른 시작¶

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

사전 준비¶

「RUM」에서 「사용자 지정」 애플리케이션을 생성하고 애플리케이션 ID를 가져옵니다.
데이터 전송 방식을 하나 준비합니다.
퍼블릭 DataWay: 전송 주소와 Client Token
로컬 환경 배포(DataKit): 애플리케이션 프로세스에서 액세스할 수 있는 DataKit 주소
애플리케이션이 Windows 10 이상에서 실행되는지 확인합니다.

연동 단계¶

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

패키지 선택¶

애플리케이션 유형	패키지	설치 방법	현재 지원
.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 런타임 자산
Native C/C++	`guance-windows-native`	SDK 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 사용¶

SDK 레지스트리 구성¶

프로젝트 루트에 vcpkg-configuration.json을 생성하거나 업데이트합니다. 기본 레지스트리 baseline을 프로젝트에서 검증한 Microsoft vcpkg 커밋으로 교체하세요. <latest-sdk-vcpkg-registry-commit>은 SDK 레지스트리의 최신 커밋을 나타냅니다. 연동 시 자리 표시자를 실제 커밋으로 교체하고 고정하여 빌드를 재현 가능하게 만드세요.

{
  "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-sdk-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)

guance_sdk.h C 헤더, 각 신호 전용 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만 설정하고 공용 토큰은 필요하지 않습니다.

.NET / C#: DataWay.NET / C#: DataKitNative C/C++: DataWayNative C/C++: DataKit

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를 종료합니다:

.NET / C#Native C/C++

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 구성을 참조하세요.

연동 성공 확인¶

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

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

다음 단계¶

전체 기본 매개변수, 캐시, 진단 및 수명 주기 구성: SDK 초기화
RUM, Log, Trace 구성: RUM 구성, Log 구성, Trace 구성
데스크톱 UI, WebView2, Electron: 데스크톱 UI 프레임워크, WebView2 모니터링, Electron 모니터링
개인 정보 및 데이터 보호: 개인 정보 및 권한 설명

업그레이드 및 변경 로그¶

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 레지스트리 baseline을 업데이트하세요. 두 릴리스 스트림은 변경 로그에서 구분되어 표시됩니다.

자주 묻는 질문¶

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