콘텐츠로 이동

RUM 설정

Windows SDK는 C#과 Native C/C++에서 동일한 View, Action, Resource, Error 및 Long Task를 수집합니다. C#은 UI 프레임워크 자동 수집을 제공하며, Native는 명시적인 C ABI와 HWND, WinHTTP 대상 어댑터를 사용합니다.

RUM 초기화 설정

샘플링 설정

의미 .NET / C# Native C/C++ 기본값 범위
일반 Session 샘플링 SampleRate sample_rate 1.0 0.01.0
Error Session 추가 샘플링 SessionErrorSampleRate session_error_sample_rate 0.0 0.01.0

샘플링 결정은 동일한 Session 내에서 일관되게 유지됩니다. 먼저 1.0으로 연동을 검증한 후 데이터 양에 따라 조정하는 것을 권장합니다.

수집 범위

기능 .NET / C# Native C/C++
View WPF, WinForms 자동 수집, WinUI 3은 Window 명시적 연결 Window 수명 주기에서 View C ABI 호출
Action 일반 UI 컨트롤 및 앱 시작 자동 수집 앱 시작 자동 수집, 비즈니스 작업은 Action C ABI 호출
Resource HttpClient 자동 수집 WinHTTP 어댑터 또는 수동 Resource C ABI
Error 처리되지 않은 예외 자동 수집, 수동 Error 지원 Native 크래시 복구 또는 수동 Error
Long Task UI 스레드 탐지 또는 수동 보고 HWND Watchdog 또는 수동 보고

수집 활성화

GuanceSdk.EnableAutomaticInstrumentation(new AutomaticInstrumentationOptions
{
    EnableWpf = true,
    EnableWinForms = true,
    EnableWinUI = true,
    EnableWebView = true,
    EnableHttpClient = true,
    EnableUnhandledException = true,
    EnableUiThreadBlock = true,
    EnableAppLaunch = true,
    UiThreadBlockThreshold = TimeSpan.FromMilliseconds(500),
    UiThreadProbeInterval = TimeSpan.FromMilliseconds(250),
    UiThreadLongTaskCooldown = TimeSpan.FromSeconds(5)
});

자동 수집 매개변수

매개변수 기본값 설명
EnableWpf true WPF Window 및 일반 컨트롤을 자동 수집합니다.
EnableWinForms true WinForms Form 및 일반 컨트롤을 자동 수집합니다.
EnableWinUI true WinUI 3 컨트롤 수집을 활성화합니다. Window는 여전히 명시적 연결이 필요합니다.
EnableWebView true 지원되는 WebView2 컨트롤을 자동으로 발견합니다.
EnableHttpClient true .NET HTTP 진단 이벤트를 통해 Resource를 수집합니다.
EnableUnhandledException true 애플리케이션 도메인 및 UI 프레임워크의 처리되지 않은 예외를 수집합니다.
EnableUiThreadBlock true UI 스레드 차단을 모니터링합니다.
EnableAppLaunch true 애플리케이션 시작 단계를 수집합니다.
UiThreadBlockThreshold 500 ms Long Task 임계값입니다.
UiThreadProbeInterval 250 ms UI 스레드 탐지 간격입니다.
UiThreadLongTaskCooldown 5 s 연속 차단 보고의 병합 쿨다운 시간입니다.

반복 호출해도 동일한 수집기가 중복 등록되지 않지만, 애플리케이션은 시작 흐름에서 한 번만 호출해야 합니다.

Native SDK 초기화 후 기본적으로 콜드 스타트와 핫 스타트를 자동 수집하며, 각각 action_type=launch_cold, action_type=launch_hot인 Action을 생성합니다. guance_sdk_config_init()enable_app_launch_tracking1로 초기화합니다. 자동 시작 Action이 필요하지 않은 경우 guance_sdk_init() 호출 전에 0으로 설정해야 합니다:

guance_sdk_config config;
guance_sdk_config_init(&config);
config.enable_app_launch_tracking = 0;

자동 수집은 현재 프로세스의 최상위 창과 첫 번째 합성 프레임을 관찰합니다. 콜드 스타트 Action에는 애플리케이션 코드 실행 전, 애플리케이션 초기화 및 첫 번째 프레임의 세 단계가 포함됩니다. 애플리케이션이 백그라운드에서 다시 포그라운드로 전환되면 핫 스타트 Action이 생성됩니다. 애플리케이션은 guance_rum_add_launch_action()를 사용하여 호스트가 측정한 시작 단계를 보고할 수 있습니다. 수동으로 콜드 스타트를 보고하면 SDK는 더 이상 중복된 자동 콜드 스타트 Action을 생성하지 않습니다.

최상위 창을 생성한 후 UI Watchdog 및 크래시 복구를 활성화할 수 있습니다:

guance_sdk_native_monitoring_config monitoring;
guance_sdk_native_monitoring_config_init(&monitoring);
monitoring.enable_ui_hang_monitoring = 1;
monitoring.main_window_handle = reinterpret_cast<uintptr_t>(main_window);
monitoring.enable_native_crash_reporting = 1;
monitoring.enable_minidump = 0;

if (!guance_sdk_enable_native_monitoring(rum, &monitoring)) {
    // HWND 또는 설정이 잘못되었습니다.
}

Native 모니터링 매개변수

guance_sdk_native_monitoring_config는 버전 관리 구조체이므로 먼저 초기화 함수를 호출해야 합니다.

필드 기본값 설명
enable_ui_hang_monitoring 0 HWND UI Watchdog을 활성화할지 여부입니다.
enable_native_crash_reporting 0 SEH 및 다음 시작 시 크래시 복구를 활성화할지 여부입니다.
main_window_handle 0 현재 프로세스가 소유한 유효한 최상위 HWND입니다.
ui_probe_interval_ms 250 UI 탐지 간격입니다.
long_task_threshold_ms 500 Long Task 임계값입니다.
hang_threshold_ms 5000 Application Not Responding 임계값입니다.
hang_report_cooldown_ms 5000 지속적인 멈춤 보고 쿨다운 시간입니다.
crash_cache_path SDK 기본 디렉터리 크래시 봉투 및 선택적 Dump의 로컬 디렉터리입니다.
enable_minidump 0 로컬 미니 Dump를 유지할지 여부입니다. Dump는 RUM에 업로드되지 않습니다.
max_crash_files 3 크래시 파일 수 상한입니다.
max_crash_file_bytes 32 MiB 크래시 파일 총 바이트 상한입니다.

C++ 애플리케이션은 guance_sdk.hpp를 포함하여 호스트 측 어댑터가 std::terminate 핸들러를 올바르게 설치하고 복원하도록 해야 합니다. 크래시가 발생한 프로세스는 네트워크 또는 큐 쓰기를 수행하지 않습니다. 다음 초기화 시 제한된 크래시 봉투가 RUM Error로 변환됩니다.

네트워크 Resource

EnableHttpClient = true로 설정하면 URL, 메서드, 상태 코드, 총 소요 시간, 요청/응답 크기 및 HTTP 프로토콜이 자동으로 기록됩니다. 명시적 Handler가 필요한 경우:

using var http = new HttpClient(
    GuanceSdk.CreateHttpMessageHandler(new HttpClientHandler()));

C++ WinHTTP는 범위 어댑터를 사용합니다:

guance::rum::WinHttpResource resource(
    rum,
    request,
    "https://api.example.com/items",
    "GET");
resource.send();
resource.receive();

다른 네트워크 라이브러리는 guance_rum_start_resource()guance_rum_stop_resource_ext()를 호출합니다. Trace Header 및 RUM 연결에 대한 자세한 내용은 Trace 설정을 참조하세요.

애플리케이션은 실제 네트워크 단계 소요 시간을 얻을 수 있을 때만 DNS, TCP, TLS 또는 TTFB를 기록해야 하며, 누락된 단계를 추정해서는 안 됩니다.

RUM 수동 계측

자동 수집으로 비즈니스 의미를 표현할 수 없는 경우 Action, View, Error, Long Task 및 Resource를 수동으로 보고할 수 있습니다. .NET / C#은 GuanceSdk를 사용하고, Native C/C++은 guance_rum.h의 C ABI를 사용합니다. 두 방식 모두 동일한 Windows RUM 데이터 유형을 생성합니다.

중복 수집 방지

수동 API와 자동 수집은 동일한 Session에 기록됩니다. 창, 컨트롤, HttpClient, WinHTTP 또는 WebView2에서 이미 자동 수집된 데이터는 수동으로 다시 보고하지 마세요.

Action

자동 종료 Action

사용자 작업을 수집하고 작업 중에 생성된 Resource, Error 및 Long Task를 연결하는 데 사용됩니다:

var action = GuanceSdk.StartAction("SaveOrder", "click");
if (!action.IsAccepted)
{
    // 이 호출은 고빈도 보호에 의해 무시되었습니다.
}

일반 모드에서는 StopAction을 호출할 필요가 없으며, 반환된 RumActionScope를 해제해도 Action이 종료되지 않습니다.

const char* action_id = guance_rum_start_action(rum, "SaveOrder", "click");
if (action_id[0] == '\0') {
    // 이 호출은 고빈도 보호에 의해 무시되었습니다.
}

일반 모드는 Android SDK와 동일하게 동작합니다: 동시에 하나의 활성 Action만 유지됩니다. 100ms 이내에 연속으로 StartAction을 호출하면 새 호출이 무시되고, 100ms 이후에 다시 호출하면 이전 Action이 종료되고 새 Action이 시작됩니다. Action은 View가 전환될 때 종료되며, 최대 약 5초 동안 지속됩니다.

비즈니스 완료 대기 Action

비즈니스 작업이 비동기 로직을 포함해야 하는 경우 needWait 모드를 활성화합니다. 이 모드에서만 StopAction과 쌍으로 사용해야 합니다:

using (GuanceSdk.StartAction("SaveOrder", "custom", needWait: true))
{
    await SaveOrderAsync();
}

또는 ActionId를 저장하여 비즈니스 종료 시 GuanceSdk.StopAction(actionId)를 호출할 수 있습니다.

const char* action_id = guance_rum_start_action_ext(
    rum,
    "SaveOrder",
    "custom",
    1);

save_order();

if (action_id[0] != '\0') {
    guance_rum_stop_action(rum, action_id);
}

needWait Action은 명시적으로 종료되기 전까지 새 Action으로 대체되지 않지만, 약 5초의 최대 지속 시간과 View 전환 제한은 동일하게 적용됩니다. Action 시작 시 빈 ID가 반환되면 이 호출이 수락되지 않은 것이므로 StopAction을 호출하지 않아야 합니다.

소요 시간이 알려진 Action

GuanceSdk.AddAction(
    name: "ExportReport",
    type: "custom",
    duration: TimeSpan.FromMilliseconds(320),
    properties: new Dictionary<string, object?>
    {
        ["format"] = "csv"
    });
constexpr int64_t duration_ns = 320LL * 1000 * 1000;
guance_rum_add_action(rum, "ExportReport", "custom", duration_ns);

AddAction은 이미 종료되었고 소요 시간이 알려진 독립적인 Action을 직접 보고하는 데 사용됩니다. 100ms 고빈도 보호 및 5초 제한의 영향을 받지 않으며, 이후에 생성된 Resource, Error 또는 Long Task도 연결되지 않습니다.

View

GuanceSdk.StartView(
    "OrderDetail",
    new Dictionary<string, object?>
    {
        ["order_type"] = "subscription"
    });

// 페이지 종료 시 실행합니다.
GuanceSdk.StopView();
guance_rum_start_view(rum, "OrderDetail");

// 페이지 또는 창 종료 시 실행합니다.
guance_rum_stop_view(rum);

새 View를 시작하면 현재 활성 View가 자동으로 종료됩니다. View 이름은 안정적인 페이지를 설명해야 하며, 주문 번호, 사용자 ID, 객체 주소 또는 검색어를 포함하지 않아야 합니다.

Error

try
{
    await LoadOrdersAsync();
}
catch (Exception exception)
{
    GuanceSdk.AddError(
        exception,
        new Dictionary<string, object?>
        {
            ["operation"] = "load_orders"
        });
}

Exception이 아닌 오류는 GuanceSdk.AddError(stack, message, errorType, source)를 사용할 수 있습니다. 처리되지 않은 예외 자동 수집이 활성화된 경우, 수동으로 보고한 후 동일한 예외를 계속 던져 결국 프로세스가 종료되면 windows_crash가 추가로 생성됩니다. 비즈니스 의미에 따라 중복 보고를 피해야 합니다.

guance_rum_add_error(
    rum,
    "OrderRepository::load_orders",
    "Order request failed",
    "NetworkError",
    "custom");

자동 수집된 .NET 치명적 예외는 error_type=windows_crash를 사용하고, Native SEH 및 C++ std::terminateerror_type=native_crash를 사용합니다. Crash의 error_source는 모두 logger입니다. Native 크래시 모니터링은 다음 시작 시 크래시 Error를 복구합니다. 크래시 핸들러에서 수동 Error API를 호출하지 마세요. 전체 유형 및 필드 설명은 애플리케이션 데이터 수집을 참조하세요.

Long Task

GuanceSdk.AddLongTask(
    duration: TimeSpan.FromMilliseconds(850),
    stack: "ReportRenderer.Render");
constexpr int64_t duration_ns = 850LL * 1000 * 1000;
guance_rum_add_long_task(rum, duration_ns, "ReportRenderer::render");

UI 스레드 차단 모니터링이 이미 활성화된 경우, 동일한 차단에 대해 수동으로 다시 보고하지 마세요.

Resource

var resourceId = GuanceSdk.StartResource(
    "https://api.example.com/orders",
    "GET");

GuanceSdk.StopResource(
    resourceId,
    statusCode: 200,
    timing: RumResourceTiming.FromTotalElapsed(
        TimeSpan.FromMilliseconds(120),
        source: "manual"),
    responseSize: 2048,
    requestSize: 0,
    resourceType: "http");

애플리케이션이 이미 DNS, TCP, TLS 및 TTFB를 측정한 경우 RumResourceTiming.FromPhases()를 사용하여 단계별 소요 시간을 기록할 수 있습니다. 신뢰할 수 있는 데이터가 없으면 총 소요 시간만 기록하세요.

C++ 애플리케이션은 ResourceScope를 사용하여 예외 또는 조기 반환 시에도 Resource가 종료되도록 보장할 수 있습니다:

#include "guance_sdk.hpp"

guance::rum::ResourceScope resource(
    rum,
    "https://api.example.com/orders",
    "GET",
    "http");

const auto response = send_request();
resource.complete(
    response.status_code,
    response.body_size,
    response.request_size);

순수 C 애플리케이션은 guance_rum_start_resource()guance_rum_stop_resource()를 쌍으로 호출할 수 있습니다. trace_id, span_id, 요청 크기 또는 HTTP 프로토콜을 기록해야 하는 경우 guance_rum_stop_resource_ext()를 사용하세요.

요청이 실패한 경우에도 Resource를 종료하고 상태 코드를 0으로 설정해야 합니다. HttpClient 또는 WinHTTP 자동 Resource가 활성화된 경우, 동일한 요청에 대해 수동 API를 다시 호출하지 마세요.

Flush

수동 이벤트는 먼저 로컬 큐에 들어갑니다. 중요한 프로세스 후 즉시 업로드를 시도해야 하는 경우:

await GuanceSdk.FlushAsync();
guance_sdk_flush(rum);

애플리케이션이 정상적으로 종료될 때는 여전히 ShutdownAsync() 또는 guance_sdk_shutdown()을 호출해야 합니다. HTTP Trace 전파 및 애플리케이션 로그는 각각 Trace 설정Log 설정을 참조하세요.

Session Replay

실험적 기능

Windows Session Replay는 기본적으로 비활성화되어 있으며, 명시적으로 활성화하고 검증할 수 있지만 아직 안정적인 릴리스 범위에 포함되지 않았습니다. 연동하는 측은 리플레이 호환성, 개인정보 보호, 성능 및 데이터 양을 직접 평가해야 하며, 현재 동작을 안정적인 호환성 약속으로 간주해서는 안 됩니다.

초기화 시 명시적으로 활성화하고 Replay 샘플링 및 기본 개인정보 보호 정책을 설정합니다:

GuanceSdk.Init(new GuanceConfig
{
    // DatawayUrl / ClientToken / RumAppId ...
    SessionReplay = new RumSessionReplayConfig
    {
        Enabled = true,
        SampleRate = 1.0,
        OnErrorSampleRate = 0.0,
        TextAndInputPrivacy = SessionReplayTextAndInputPrivacy.MaskAll,
        TouchPrivacy = SessionReplayTouchPrivacy.Show,
        ImagePrivacy = SessionReplayImagePrivacy.MaskAll
    }
});

SampleRateOnErrorSampleRate의 범위는 모두 0.01.0입니다. 초기화 후 수동으로 녹화를 제어할 수 있습니다:

GuanceSdk.StartSessionReplayRecording();
GuanceSdk.StopSessionReplayRecording();

수동 시작은 Enabled = false를 우회할 수 없습니다. 초기화 설정에서 먼저 활성화해야 합니다. 요소 수준 개인정보 보호 API는 Windows Session Replay 개인정보 보호 재정의를 참조하세요.

guance_sdk_config config;
guance_sdk_config_init(&config);
config.session_replay_enabled = 1;
config.session_replay_sample_rate = 1.0;
config.session_replay_on_error_sample_rate = 0.0;

guance_sdk_handle rum = guance_sdk_init(&config);
guance_rum_register_replay_window(
    rum,
    reinterpret_cast<uintptr_t>(main_window));

Native Replay는 독립적인 영속 큐와 v1/write/rum/replay 업로드 채널을 사용합니다. guance_rum_start_session_replay()guance_rum_stop_session_replay()로 수동으로 녹화를 제어할 수 있지만, 시작 호출도 비활성화된 초기화 설정을 재정의하지 않습니다.

WebView2 및 Electron의 페이지 record는 네이티브 Bridge를 통해 동일한 네이티브 Session, 세그먼트, 큐 및 업로드 채널로 전달됩니다. 자세한 내용은 각각 WebView2 모니터링Electron 모니터링을 참조하세요.

관련 문서

문서 평가

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