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.0~1.0 |
| Error Session 추가 샘플링 | SessionErrorSampleRate |
session_error_sample_rate |
0.0 |
0.0~1.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_tracking을 1로 초기화합니다. 자동 시작 Action이 필요하지 않은 경우 guance_sdk_init() 호출 전에 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가 필요한 경우:
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를 연결하는 데 사용됩니다:
일반 모드는 Android SDK와 동일하게 동작합니다: 동시에 하나의 활성 Action만 유지됩니다. 100ms 이내에 연속으로 StartAction을 호출하면 새 호출이 무시되고, 100ms 이후에 다시 호출하면 이전 Action이 종료되고 새 Action이 시작됩니다. Action은 View가 전환될 때 종료되며, 최대 약 5초 동안 지속됩니다.
비즈니스 완료 대기 Action¶
비즈니스 작업이 비동기 로직을 포함해야 하는 경우 needWait 모드를 활성화합니다. 이 모드에서만 StopAction과 쌍으로 사용해야 합니다:
또는 ActionId를 저장하여 비즈니스 종료 시 GuanceSdk.StopAction(actionId)를 호출할 수 있습니다.
needWait Action은 명시적으로 종료되기 전까지 새 Action으로 대체되지 않지만, 약 5초의 최대 지속 시간과 View 전환 제한은 동일하게 적용됩니다. Action 시작 시 빈 ID가 반환되면 이 호출이 수락되지 않은 것이므로 StopAction을 호출하지 않아야 합니다.
소요 시간이 알려진 Action¶
AddAction은 이미 종료되었고 소요 시간이 알려진 독립적인 Action을 직접 보고하는 데 사용됩니다. 100ms 고빈도 보호 및 5초 제한의 영향을 받지 않으며, 이후에 생성된 Resource, Error 또는 Long Task도 연결되지 않습니다.
View¶
새 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가 추가로 생성됩니다. 비즈니스 의미에 따라 중복 보고를 피해야 합니다.
자동 수집된 .NET 치명적 예외는 error_type=windows_crash를 사용하고, Native SEH 및 C++ std::terminate는 error_type=native_crash를 사용합니다. Crash의 error_source는 모두 logger입니다. Native 크래시 모니터링은 다음 시작 시 크래시 Error를 복구합니다. 크래시 핸들러에서 수동 Error API를 호출하지 마세요. 전체 유형 및 필드 설명은 애플리케이션 데이터 수집을 참조하세요.
Long Task¶
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¶
수동 이벤트는 먼저 로컬 큐에 들어갑니다. 중요한 프로세스 후 즉시 업로드를 시도해야 하는 경우:
애플리케이션이 정상적으로 종료될 때는 여전히 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
}
});
SampleRate와 OnErrorSampleRate의 범위는 모두 0.0~1.0입니다. 초기화 후 수동으로 녹화를 제어할 수 있습니다:
수동 시작은 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 모니터링을 참조하세요.