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 属性的处理方式请参考隐私与权限说明。用户、自定义上下文和手动事件属性需要由应用在写入前完成业务脱敏。