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-adapternpm 패키지 버전.
다음은 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 속성의 처리 방식은 개인정보 및 권한 설명을 참조하세요. 사용자, 사용자 정의 컨텍스트, 수동 이벤트 속성은 애플리케이션이 기록 전에 비즈니스 수준의 비식별화를 수행해야 합니다.