콘텐츠로 이동

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 버전. WebView2와 Electron 데이터는 해당 식별자를 그대로 사용.
sdk_pkg_info string SDK가 자동 생성하는 JSON 문자열로, 적용되는 Browser SDK 및 Electron Adapter 패키지 버전을 기록. 자세한 내용은 아래 설명 참조.
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 예약 필드는 덮어쓸 수 없습니다.

SDK 컴포넌트 버전

sdk_pkg_info는 NuGet / Native SDK 0.1.0-alpha.11부터 지원됩니다. Electron 연동은 @cloudcare/electron-native-adapter 0.1.0-alpha.6 이상을 함께 사용해야 하며, Full Mode와 Mixed Mode의 규칙은 동일하므로 해당 필드를 수동으로 구성할 필요가 없습니다.

  • web: 현재 Browser RUM 또는 Browser Log 이벤트가 제공하는 Browser SDK 버전.
  • electron: 설치된 @cloudcare/electron-native-adapter npm 패키지 버전.

다음은 Browser SDK 3.3.6과 Electron Adapter 0.1.0-alpha.6을 기준으로 JSON 문자열의 내용을 보여주는 예시입니다.

데이터 소스 sdk_pkg_info 예시
.NET WebView2의 Browser RUM {"web":"3.3.6"}
Adapter 연결 후 Electron 호스트 RUM / Log {"electron":"0.1.0-alpha.6"}
Electron Browser RUM / Log, Full Mode 또는 Mixed Mode {"electron":"0.1.0-alpha.6","web":"3.3.6"}
Browser 버전이 없고 Electron Adapter도 연결되지 않은 .NET / Native 데이터 해당 필드 미기록

Browser 이벤트에 버전이 없으면 web을 생략하고, Electron Adapter가 연결된 경우 electron은 유지합니다. 필드에는 agent, native, replay가 포함되지 않습니다. sdk_name, sdk_version은 계속해서 호스트 Windows SDK를 식별하며, Browser와 Adapter 버전은 컴포넌트 정보로만 기록됩니다.

필드는 호스트 SDK가 실제 컴포넌트 버전에 따라 생성하며, 페이지에서 전달된 sdk_pkg_info를 직접 사용하지 않습니다. WebView2의 Browser RUM Bridge는 Replay를 활성화하지 않았거나 선택적 Replay 컴포넌트를 설치하지 않은 경우에도 사용할 수 있습니다.

기타 데이터 유형 속성

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를 생성하거나 전달하며, 해당 RUM Resource에 trace_id, span_id를 기록할 수 있습니다. 전체 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 속성의 처리 방식은 개인정보 및 권한 설명을 참조하세요. 사용자, 사용자 정의 컨텍스트, 수동 이벤트 속성은 애플리케이션이 기록 전에 비즈니스 수준의 비식별화를 수행해야 합니다.

문서 평가

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