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 샘플링 | SessionSamplingRate(NuGet 0.1.0-alpha.8부터) |
session_sampling_rate(vcpkg 0.1.0-alpha.9부터) |
100 |
0~100 |
| Error Session 추가 샘플링 | SessionOnErrorSamplingRate(NuGet 0.1.0-alpha.8부터) |
session_on_error_sampling_rate(vcpkg 0.1.0-alpha.9부터) |
0 |
0~100 |
| 일반 Session 샘플링(이전) | SampleRate(사용 중단됨) |
이전 구조 sample_rate(사용 중단됨) |
1 |
0~1; SessionSamplingRate / session_sampling_rate를 사용하세요. |
| Error Session 추가 샘플링(이전) | SessionErrorSampleRate(사용 중단됨) |
이전 구조 session_error_sample_rate(사용 중단됨) |
0 |
0~1; SessionOnErrorSamplingRate / session_on_error_sampling_rate를 사용하세요. |
새 필드는 float 백분율을 사용하며 0.1(0.1%를 의미) 같은 소수를 지원합니다. 샘플링 결정은 동일한 Session 내에서 일관되게 유지됩니다. 먼저 100으로 연동을 검증한 다음 데이터 양에 따라 조정하는 것이 좋습니다.
동일한 .NET 구성 개체에 새 필드와 이전 필드를 동시에 설정한 경우, 명시적으로 0을 설정한 경우를 포함하여 새 필드가 우선합니다. 새 필드가 유효하지 않으면 이전 필드로 폴백되지 않습니다. Native는 ABI 안전한 guance_sdk_config_v2 및 guance_sdk_init_v2()를 사용합니다.
수집 경계¶
| 기능 | .NET / C# | Native C/C++ |
|---|---|---|
| View | WPF, WinForms 자동; WinUI 3는 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_v2_init()는 enable_app_launch_tracking을 1로 초기화합니다. 자동 시작 Action이 필요하지 않으면 guance_sdk_init_v2()를 호출하기 전에 0으로 설정해야 합니다:
guance_sdk_config_v2 config;
guance_sdk_config_v2_init(&config);
config.enable_app_launch_tracking = 0;
| 필드 | 기본값 | 설명 |
|---|---|---|
enable_app_launch_tracking |
1 |
콜드 스타트 및 핫 스타트 Action을 자동 수집합니다. 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는 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 설정을 참고하세요.
세션 리플레이¶
NuGet 0.1.0-alpha.9, vcpkg 0.1.0-alpha.10부터 Replay 구현은 선택 구성 요소로 제공됩니다. 먼저 선택 구성 요소 설치에 따라 동일한 버전의 구성 요소를 추가한 후 아래 구성을 활성화하세요. 기존 설정, 제어 및 개인정보 보호 API는 유지됩니다. Electron의 추가 런타임 설치 방법은 Electron 모니터링을 참고하세요.
Replay가 꺼져 있으면 구성 요소를 로드하지 않으며 Replay 업로드 채널도 생성하지 않습니다. 구성은 활성화되었지만 구성 요소가 없거나, 버전이 일치하지 않거나, 로드에 실패한 경우 SDK는 Replay를 비활성화하고 구성 요소 진단을 출력하며, 일반 RUM, Log, Trace는 계속 작동합니다. 구성 요소를 설치하는 것만으로는 녹화가 활성화되지 않습니다. C#에서는 초기화 시 반환된 클라이언트의 IsSessionReplayAvailable을 읽을 수 있고, Native에서는 guance_rum_is_session_replay_available(rum)을 호출하여 각각 구성 요소 사용 가능 여부를 확인할 수 있습니다. 사용 가능 상태는 현재 Session이 샘플링되었거나 녹화가 시작되었음을 의미하지 않습니다.
Replay 파라미터¶
.NET / C#(SessionReplay) |
Native(sdk_config_v2) |
기본값 | 설명 |
|---|---|---|---|
Enabled |
session_replay_enabled |
false / 0 |
녹화 활성화 여부. |
SamplingRate(NuGet 0.1.0-alpha.8부터) |
session_replay_sampling_rate(vcpkg 0.1.0-alpha.9부터) |
100 |
일반 Session의 Replay 샘플링 백분율, 0~100, 소수점 지원. |
OnErrorSamplingRate(NuGet 0.1.0-alpha.8부터) |
session_replay_on_error_sampling_rate(vcpkg 0.1.0-alpha.9부터) |
0 |
Error Session 추가 샘플링 백분율, 0~100, 소수점 지원. |
TextAndInputPrivacy |
— | MaskAll |
텍스트 및 입력 개인정보 보호 정책. |
TouchPrivacy |
— | Show |
포인터 및 터치 개인정보 보호 정책. |
ImagePrivacy |
— | MaskAll |
이미지 개인정보 보호 정책. |
SegmentRecordLimit |
session_replay_segment_record_limit |
500 |
단일 Replay 세그먼트의 레코드 수 상한. |
SegmentBytesLimit |
session_replay_segment_bytes_limit |
1 MiB |
단일 세그먼트의 압축되지 않은 바이트 상한. |
FlushInterval |
— | 5 s |
활성 세그먼트의 Flush 간격. |
MaxNodeCount |
— | 2000 |
단일 스냅샷 노드 수 상한. |
MaxTreeDepth |
— | 64 |
UI 트리 깊이 상한. |
MaxTextLength |
— | 256 |
단일 노드 텍스트 길이 상한. |
MaxAttributeValueLength |
— | 512 |
단일 속성 값 길이 상한. |
CaptureImages |
— | true |
false로 설정하면 이미지 정책을 재정의하여 모든 이미지를 숨깁니다. |
MaxImageBytes |
— | 512 KiB |
단일 이미지 인코딩 바이트 상한. |
MaxImageDimension |
— | 1024 |
이미지 인코딩 가로세로 상한. |
LargeImagePrivacyThreshold |
— | 100 |
MaskLargeOnly의 이미지 면적 임계값. |
CustomRenderedTypeNameMarkers |
— | 기본 제공 사용자 지정 렌더링 유형 마커 | 유형 이름 조각으로 불투명하거나 사용자 지정 렌더링된 콘텐츠를 식별합니다. |
SensitiveTextPatterns |
— | 이메일, 카드 번호, 전화번호 패턴 | 민감한 텍스트를 식별하는 정규식 컬렉션. |
SampleRate(사용 중단됨) |
이전 구조 session_replay_sample_rate(사용 중단됨) |
1 |
이전 0~1 단위와 호환됩니다. 해당하는 새 샘플링 필드를 사용하세요. |
OnErrorSampleRate(사용 중단됨) |
이전 구조 session_replay_on_error_sample_rate(사용 중단됨) |
0 |
이전 0~1 단위와 호환됩니다. 해당하는 새 샘플링 필드를 사용하세요. |
실험적 기능
Windows Session Replay는 기본적으로 꺼져 있으며, 명시적으로 활성화하고 검증할 수 있는 실험적 기능입니다. 도입자는 리플레이 호환성, 개인정보 보호, 성능 및 데이터 양을 직접 평가해야 하며, 현재 동작을 안정적인 호환성 보장으로 간주해서는 안 됩니다.
초기화 시 Replay 샘플링 및 기본 개인정보 보호 정책을 명시적으로 활성화하고 설정합니다:
GuanceSdk.Init(new GuanceConfig
{
// DatawayUrl / ClientToken / RumAppId ...
SessionReplay = new RumSessionReplayConfig
{
Enabled = true,
SamplingRate = 100, // NuGet 0.1.0-alpha.8부터 지원됨
OnErrorSamplingRate = 0, // NuGet 0.1.0-alpha.8부터 지원됨
TextAndInputPrivacy = SessionReplayTextAndInputPrivacy.MaskAll,
TouchPrivacy = SessionReplayTouchPrivacy.Show,
ImagePrivacy = SessionReplayImagePrivacy.MaskAll
}
});
SamplingRate와 OnErrorSamplingRate(NuGet 0.1.0-alpha.8부터 지원)는 모두 float 백분율이며 범위는 0~100입니다. 초기화 후에는 녹화를 수동으로 제어할 수 있습니다:
수동 시작은 Enabled = false를 우회할 수 없습니다. 먼저 초기화 설정에서 활성화해야 합니다. 요소 수준 개인정보 보호 API는 Windows 세션 리플레이 개인정보 보호 재정의를 참고하세요.
guance_sdk_config_v2 config;
guance_sdk_config_v2_init(&config);
config.session_replay_enabled = 1;
config.session_replay_sampling_rate = 100.0f; // vcpkg 0.1.0-alpha.9부터 지원됨
config.session_replay_on_error_sampling_rate = 0.0f; // vcpkg 0.1.0-alpha.9부터 지원됨
guance_sdk_handle rum = guance_sdk_init_v2(&config);
if (guance_rum_is_session_replay_available(rum)) {
guance_rum_register_replay_window(
rum,
reinterpret_cast<uintptr_t>(main_window));
guance_rum_start_session_replay(rum);
}
Native Replay는 독립적인 영구 큐와 v1/write/rum/replay 업로드 채널을 사용합니다. guance_rum_start_session_replay()와 guance_rum_stop_session_replay()로 녹화를 수동으로 제어할 수 있지만, 시작 호출 역시 비활성화된 초기화 설정을 덮어쓰지 않습니다.
WebView2 및 Electron의 페이지 녹화는 네이티브 브리지를 통해 동일한 네이티브 Session, 세그먼트, 큐 및 업로드 채널로 전달됩니다. 각각 WebView2 모니터링 및 Electron 모니터링을 참고하세요.