Windows 애플리케이션 데이터 수집¶

Windows 문서는 RUM, Log 및 HTTP Trace의 세 가지 데이터 기능을 모두 다룹니다. .NET / C#, Native C/C++, WebView2 및 Electron 네이티브 Bridge는 동일한 Windows SDK 제품 ID를 사용합니다. Electron Renderer의 Browser RUM은 수집과 직렬화만 담당하며, 신뢰 필드와 Session은 Main Process 어댑터 계층과 Windows Native Core가 통합 관리하고, 큐와 업로드는 Native Core가 처리합니다.

데이터 유형¶

데이터 영역	역할	업로드 동작
RUM	Session, View, Action, Resource, Error 및 Long Task 기록	RUM 큐에 기록하고 RUM Intake로 업로드
Log	애플리케이션 로그를 기록하고 현재 RUM 컨텍스트와 연결 가능	별도 Log 큐에 기록하고 Logging Intake로 업로드
HTTP Trace	아웃바운드 요청에 Trace Header를 주입하고 해당 RUM Resource와 연결 가능	APM Span을 별도로 업로드하지 않음

전역 속성¶

필드	유형	설명
`app_id`	string	콘솔에서 생성한 애플리케이션 ID.
`service`	string	`.NET`의 `GuanceConfig.ServiceName`, Native의 `guance_sdk_config.service_name` 또는 Electron 네이티브 설정.
`env`	string	`prod`, `gray`, `pre`, `common` 또는 `local`.
`version`	string	애플리케이션 버전.
`sdk_name`	string	Windows .NET, Native Core, WebView2 및 Electron 네이티브 Bridge는 `df_windows_rum_sdk`로 고정.
`sdk_version`	string	현재 Windows SDK 어셈블리 또는 Native Core 버전. Electron Adapter는 애플리케이션과 함께 제공되는 Native SDK 버전을 전달해야 하며, 비즈니스 애플리케이션 버전으로 대체할 수 없음.
`application_uuid`	string	현재 애플리케이션 설치 인스턴스 식별자.
`session_id`	string	현재 사용자 Session 식별자.
`session_type`	string	Windows SDK는 `user`로 고정.
`session_has_replay`	boolean	현재 Session에서 업로드 가능한 Replay 데이터가 생성되었는지 여부.
`session_sample_rate`	number	현재 일반 Session 샘플링 비율.
`session_on_error_sample_rate`	number	Error Session 추가 샘플링 비율.
`view_id`	string	현재 활성 View 식별자.
`action_id`	string	현재 활성 Action 식별자. 존재할 때 기록.
`userid`	string	RUM 애플리케이션 ID별로 영속화된 익명 사용자 식별자 또는 사용자 API로 설정한 사용자 ID.
`user_name`, `user_email`	string	사용자 API를 호출하여 설정한 후 기록.
`is_signin`	string	사용자가 설정된 경우 `T`, 그렇지 않으면 `F`.
`os`, `os_version`	string	Windows 이름 및 버전.
`os_version_major`	string	Windows 주 버전.
`device`, `model`	string	확인 가능할 때 기록하는 Windows 디바이스 및 모델 정보.
`arch`	string	프로세스가 실행되는 디바이스 아키텍처.
`screen_size`	string	확인 가능할 때 기본 모니터 크기 기록.
`locale`	string	현재 로캘 설정.
`network_type`	string	`wifi`, `ethernet`, `mobile`, `none` 또는 `unknown`.

사용자 정의 컨텍스트는 존재하지 않는 필드만 보충하며 SDK 예약 필드를 덮어쓸 수 없습니다.

기타 데이터 유형 속성¶

Session은 콘솔에서 동일한 session_id 아래의 이벤트를 집계하여 생성한 사용자 방문 과정으로, 별도로 Session API를 호출할 필요가 없습니다.

유형	설명	일반적인 출처
View	창 또는 비즈니스 페이지의 표시 주기와 성능	Window/Form 라이프사이클, WinUI 3 명시적 연결, Native 창 이벤트, WebView2 탐색
Action	사용자 작업 및 소요 시간	클릭, 메뉴, 선택, 전환, 입력, 단축키 또는 수동 Action
Resource	네트워크 요청, 상태 및 소요 시간	`HttpClient`, WinHTTP, WebView2 Fetch/XHR/Resource 또는 수동 Resource
Error	애플리케이션 및 페이지 오류	처리되지 않은 .NET 예외, Native 크래시 복구, WebView2 JavaScript Error 또는 수동 Error
Long Task	UI 메인 스레드 장시간 차단	Windows UI 스레드 탐지 또는 수동 Long Task

View¶

필드	유형	설명
`view_id`	string	View의 고유 식별자.
`view_name`	string	창, 페이지 또는 비즈니스 View 이름.
`view_referrer`	string	이전 View 이름.
`time_spent`	integer	View 지속 시간(나노초).
`is_active`	boolean	업로드 시 View가 여전히 활성 상태인지 여부.
`view_action_count`	integer	View에서 생성된 Action 수.
`view_resource_count`	integer	View에서 생성된 Resource 수.
`view_error_count`	integer	View에서 생성된 Error 수.
`view_long_task_count`	integer	View에서 생성된 Long Task 수.
`view_update_time`	integer	이번 View 업데이트의 Unix 나노초 타임스탬프.

Action¶

필드	유형	설명
`action_id`	string	Action의 고유 식별자.
`action_name`	string	컨트롤, 명령 또는 비즈니스 동작 이름.
`action_type`	string	예: `click`, `key`, `launch_cold` 또는 `launch_hot`.
`duration`	integer	Action 지속 시간(나노초).
`action_resource_count`	integer	Action 범위 내 Resource 수.
`action_error_count`	integer	Action 범위 내 Error 수.
`action_long_task_count`	integer	Action 범위 내 Long Task 수.
`app_pre_application_init_time`	integer	시작 Action에서 애플리케이션 코드 실행 전 소요 시간.
`app_application_init_time`	integer	시작 Action에서 애플리케이션 초기화 단계 소요 시간.
`app_first_frame_init_time`	integer	시작 Action에서 첫 프레임 단계 소요 시간.

Resource¶

필드	유형	설명
`resource_id`	string	Resource의 고유 식별자.
`resource_url`	string	개인정보 보호 정책 적용 후의 요청 URL.
`resource_url_host`	string	요청 호스트 이름.
`resource_url_path`	string	요청 경로.
`resource_url_path_group`	string	정규화된 경로 그룹.
`resource_method`	string	HTTP 메서드.
`resource_status`	integer	HTTP 상태 코드. 응답을 받지 못하면 유효한 상태를 기록하지 않음.
`resource_status_group`	string	상태 코드 그룹(예: `2xx`).
`resource_type`	string	`http`, `native` 또는 애플리케이션에서 전달한 리소스 유형.
`duration`	integer	Resource 총 소요 시간(나노초).
`resource_size`	integer	응답 본문 바이트 수. 확인 가능할 때 기록.
`resource_request_size`	integer	요청 본문 바이트 수. 확인 가능할 때 기록.
`resource_dns`, `resource_tcp`, `resource_ssl`, `resource_ttfb`	integer	안정적으로 확인 가능할 때 기록하는 네트워크 단계 소요 시간(나노초).
`resource_http_protocol`	string	HTTP 프로토콜 버전.
`trace_id`, `span_id`	string	Trace와 RUM 연결이 활성화된 후 기록.
`request_header`, `response_header`	string	개인정보 보호 설정이 허용하는 경우에만 기록하는 Header 스냅샷.
`network_instrumentation`, `network_library`	string	자동 수집 진입점 및 식별된 네트워크 라이브러리.

단계별 소요 시간은 resource_timing_source, resource_timing_precision, resource_timing_duration, resource_timing_phase 및 resource_ttfb_estimated를 통해 출처와 정밀도를 표시합니다. 신뢰할 수 있는 단계 데이터가 없으면 SDK는 총 소요 시간만 기록합니다.

Error¶

필드	유형	설명
`error_type`	string	자동 수집은 아래 표의 표준 유형을 사용하며, 수동 Error는 애플리케이션에서 전달한 유형을 사용.
`error_source`	string	Crash 및 애플리케이션 예외는 `logger`, 네트워크 오류는 `network`, WebView2 페이지 오류는 `webview`.
`error_situation`	string	`run`은 실행 중을 의미하며, 다음 시작 시 복구되는 Native Crash는 `startup`.
`error_message`	string	오류 요약. Crash에는 예외 유형, 예외 코드 또는 주소 등의 진단 정보가 포함됨.
`error_stack`	string	전체 예외 또는 호출 스택. 전체 Native 호출 스택을 얻을 수 없으면 최소한 명령 주소를 기록.

자동 수집 유형¶

시나리오	`error_type`	`error_source`	설명
처리되지 않은 .NET 예외로 인한 프로세스 종료	`windows_crash`	`logger`	`error_message`에 전체 예외 유형과 메시지가 포함되고, `error_stack`에 `Exception.ToString()`이 포함됨.
처리되지 않은 SEH 또는 C++ `std::terminate`	`native_crash`	`logger`	크래시 정보를 안전하게 디스크에 저장하고 다음 시작 시 복구. 예외 코드, 주소 또는 `std::terminate` 정보가 `error_message`에 기록됨.
Native UI Watchdog이 애플리케이션 무응답 감지	`anr_error`	`logger`	애플리케이션이 응답을 복구한 후 업로드하며, 지속 시간이 `error_message`에 기록됨.
`HttpClient` 요청 예외 또는 자동 Resource가 HTTP 4xx/5xx 반환	`network_error`	`network`	Error가 해당 Resource와 연결되고 URL, 메서드 및 상태 정보를 포함함.
WebView2 JavaScript Error	JavaScript `Error.name`, 없는 경우 `JavaScriptError`	`webview`	`error_message` 및 `error_stack`은 페이지 예외에서 가져옴.
처리되지 않은 WebView2 Promise rejection	rejection의 `name`, 없는 경우 `UnhandledPromiseRejection`	`webview`	`error_message` 및 `error_stack`은 rejection reason에서 가져옴.
WebView2 탐색 실패	`WebView2NavigationError`	`webview`	`error_message`에 탐색 실패 상태가 포함됨.
WebView2 프로세스 실패	`WebView2ProcessFailed`	`webview`	`error_message`에 프로세스 실패 유형 또는 원인이 포함됨.

관찰되지 않은 Task 예외와 WinForms가 포착한 후 애플리케이션 실행을 계속 허용하는 UI 스레드 예외는 Crash가 아닙니다. error_type은 해당 .NET 예외 유형을 사용하고 error_source는 logger입니다. 예외 분류와 진단 세부 정보는 error_type, error_message, error_stack에 통일되어 반영됩니다.

Long Task¶

필드	유형	설명
`duration`	integer	Long Task 지속 시간(나노초).
`long_task_stack`	string	확인 가능할 때 기록되는 호출 스택.
`long_task_source`	string	자동 또는 수동 수집 출처.
`long_task_delay`	integer	UI 스레드에서 감지된 차단 지연.
`long_task_threshold`	integer	적용되는 Long Task 임계값.
`long_task_cooldown`	integer	연속 차단 보고의 쿨다운 시간.
`long_task_suppressed_count`	integer	쿨다운 동안 병합된 중복 보고 수.

RUM 기능 매트릭스¶

연동 방식	View	Action	Resource	Error	Long Task
WPF	자동	자동	`HttpClient`	처리되지 않은 예외	UI 스레드 모니터링
WinForms	자동	자동	`HttpClient`	처리되지 않은 예외	UI 스레드 모니터링
WinUI 3	창 연결 후 자동	자동	`HttpClient`	처리되지 않은 예외	UI 스레드 모니터링
Native C/C++	창 이벤트 명시적 연동	메시지 또는 명령 명시적 연동	WinHTTP 어댑터 또는 수동 API	크래시 복구 또는 수동 API	`HWND` Watchdog 또는 수동 API
WebView2	페이지 탐색	페이지 상호작용	Fetch/XHR/Resource	JavaScript Error	renderer Long Task 미수집
Electron Native Bridge	Browser RUM	Browser RUM	Browser RUM	Browser RUM + Main Process 이벤트	Browser RUM; Renderer 무응답은 Main Process에서 업로드

Native SDK는 프로세스 수준 Detour Hook을 설치하지 않습니다. 애플리케이션은 HWND, WinHTTP Handle 또는 비즈니스 라이프사이클 이벤트를 명시적으로 전달해야 합니다. 연동 방식은 데스크톱 UI 프레임워크 및 RUM 수동 계측을 참조하세요.

Log 기능 매트릭스¶

연동 방식	사용자 정의 Log	일괄 Log	자동 로그 소스	RUM 연결
.NET / C#	`GuanceSdk.AddLog()`	`GuanceSdk.AddLogs()`	`System.Diagnostics.Trace` 수집 가능	구성 가능
Native C/C++	`guance_log_add()`	`guance_log_add_batch()`	현재 Console, ETW 또는 타사 로그 라이브러리를 가로채지 않음	구성 가능
WebView2	Windows 호스트에서 기록	Windows 호스트에서 기록	페이지 Console을 자동으로 브리지하지 않음	호스트의 현재 RUM 컨텍스트 사용
Electron Native Bridge	Browser Logs API	Browser Logs Adapter에서 변환	Console, 페이지 오류 또는 사용자 정의 범위는 Browser Logs 설정에 따름	Native Session, View 및 Action 컨텍스트 사용

Log는 독립적인 큐를 사용합니다. RUM 연결을 활성화하면 로그 작성 시점의 session_id, view_id, action_id가 Log와 함께 업로드됩니다. 이미 큐에 들어간 Log는 이후 컨텍스트 변경으로 수정되지 않습니다.

Log의 핵심 필드는 message와 status입니다. 동시에 service, env, version, SDK, 애플리케이션, 디바이스 및 사용자 필드가 포함됩니다. RUM 연결을 활성화하면 session_id, view_id, action_id 및 해당 이름도 포함됩니다. GlobalContext, 사용자 확장 속성 및 이벤트 수준 Properties는 사용자 정의 태그로 기록되지만, SDK 예약 필드는 덮어쓸 수 없습니다.

Trace 기능 매트릭스¶

연동 방식	자동 경계	수동 컨텍스트	RUM Resource 연결	독립 Span 업로드
.NET / C#	`HttpClient` 진단 구독 또는 `RumHttpMessageHandler`	`ContextProvider`	구성 가능	지원 안 함
Native C/C++	`guance_rum_winhttp.hpp`	`guance_trace_create_context()` 또는 콜백	구성 가능	지원 안 함
WebView2	페이지 요청은 WebView2/Browser 측에서 처리	페이지 SDK에서 관리	페이지 Resource 브리지	Windows SDK에서 업로드하지 않음
Electron Native Bridge	Browser RUM SDK	Browser RUM SDK	Resource가 Bridge를 통해 Native RUM 큐에 기록	지원 안 함

HTTP Trace는 요청 Header를 생성하거나 전달하며, trace_id, span_id를 해당 RUM Resource에 기록할 수 있습니다. 완전한 APM Span이 필요하면 애플리케이션에서 별도의 APM Tracer를 사용해야 합니다. 구체적인 형식과 대상 필터링 방식은 Trace 설정을 참조하세요.

데이터 연결¶

다섯 가지 RUM 데이터가 현재 session_id를 공유합니다.
Action, Resource, Error 및 Long Task는 현재 view_id에 연결됩니다.
Action 범위 내에서 생성된 Resource, Error 및 Long Task는 해당 action_id에 연결됩니다.
새 View가 시작되면 이전 활성 View가 종료됩니다.
사용자 정보 업데이트는 이후 데이터에만 영향을 미치며 기존 데이터는 수정하지 않습니다.
Log와 HTTP Trace의 RUM 연결 여부는 각각 EnableLinkRumData 또는 enable_link_rum_data로 제어됩니다.

Resource 소요 시간¶

자동 HttpClient Resource는 기본적으로 총 소요 시간을 기록하고 소요 시간 정밀도를 표시합니다. HttpResourceTimingProvider 또는 RumResourceTiming.FromPhases()를 통해 DNS, TCP, TLS 및 TTFB 단계를 추가할 수 있습니다.

Native WinHTTP 어댑터는 요청 시작, 종료, 상태, 바이트 수 및 Trace 연결 정보를 기록합니다. 애플리케이션에 신뢰할 수 있는 단계별 소요 시간이 없으면 이러한 필드를 추정하거나 위조해서는 안 됩니다.

데이터 프라이버시¶

Resource URL 쿼리 매개변수, HTTP Header, Trace 대상 및 Log 속성의 처리 방식은 개인정보 보호 및 권한 설명을 참조하세요. 사용자, 사용자 정의 컨텍스트 및 수동 이벤트 속성은 애플리케이션에서 기록 전에 비즈니스 마스킹을 완료해야 합니다.