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

Windows 문서는 RUM, Log, HTTP Trace 세 가지 데이터 유형을 모두 다룹니다. .NET / C#, Native C/C++, WebView2 및 Electron 기본 Bridge는 동일한 Windows SDK 제품 아이덴티티를 사용합니다. 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 속성의 처리 방식은 개인정보 보호 및 권한 설명을 참조하세요. 사용자, 사용자 정의 컨텍스트 및 수동 이벤트 속성은 애플리케이션이 기록하기 전에 비즈니스 수준에서 마스킹을 완료해야 합니다.