콘텐츠로 이동

빠른 시작

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

애플리케이션은 Agent 자동 연결과 수동 연결을 지원합니다. 다음 단계에서는 수동 연결의 최소 구성을 설명합니다.

사전 준비

  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 런타임 자산
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을 생성하거나 업데이트합니다. 기본 레지스트리 기준선은 프로젝트에서 검증한 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)

C 헤더 파일 guance_sdk.h, 각 시그널 전용 C 헤더 파일 guance_rum.h, guance_trace.h, guance_log.h, 또는 C++ 보조 헤더 파일 guance_sdk.hpp를 사용할 수 있습니다. 전체 C API는 공개된 guance_sdk.h를 참고하십시오.

선택적 구성 요소 설치

NuGet 0.1.0-alpha.9 및 vcpkg 0.1.0-alpha.10부터 Session Replay는 선택적 구성 요소로 제공됩니다. RUM, Log, Trace만 사용하는 경우에는 기본 패키지만 설치하면 됩니다. 기존 Replay 애플리케이션을 패키지가 분리된 버전으로 업그레이드할 때는 Replay 구성 요소를 추가로 설치해야 하며, 기존 구성과 제어 호출은 유지됩니다.

기능 .NET / C# Native C/C++
Session Replay Guance.Windows.SessionReplay 동일한 port의 replay Feature, guance_windows_replay.dll 설치

.NET에서 Replay를 사용할 때는 다음 구성 요소를 추가하고 [latest_version]을 기본 패키지와 동일한 NuGet 버전으로 고정합니다:

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

Replay NuGet 패키지는 동일한 버전의 기본 패키지에 정확히 종속됩니다. 관리형 Replay 패키지에는 Native Replay DLL이 포함되지 않습니다. Native 애플리케이션은 replay Feature를 선택합니다:

{
  "dependencies": [
    {
      "name": "guance-windows-native",
      "features": ["replay"]
    }
  ]
}

설치 후 Native Replay DLL은 동일한 버전, 동일한 아키텍처의 guance_windows_native.dll과 같은 디렉터리에 있어야 합니다. 구성 요소를 설치해도 Replay가 자동으로 활성화되지 않으므로, 활성화 및 녹화 시작을 구성해야 합니다. RUM 구성을 참고하십시오.

Electron Full Mode에서는 npm Adapter가 빌드 단계에서 Replay 보충 런타임을 설치하며, Mixed Mode에서는 Native 호스트가 replay Feature를 설치합니다. Electron 모니터링을 참고하십시오.

최소 초기화 예제

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

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_v2 config; // vcpkg 0.1.0-alpha.9부터 지원
guance_sdk_config_v2_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.application_version = "1.0.0";

guance_sdk_handle sdk = guance_sdk_init_v2(&config);
if (sdk == nullptr) {
    // 초기화 실패를 처리합니다.
}
#include "guance_sdk.h"

guance_sdk_config_v2 config; // vcpkg 0.1.0-alpha.9부터 지원
guance_sdk_config_v2_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.application_version = "1.0.0";

guance_sdk_handle sdk = guance_sdk_init_v2(&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가 배포 환경 아키텍처와 일치하는지 확인하십시오.

문서 평가

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