RUM 配置¶

Windows SDK 在 C# 与 Native C/C++ 中采集相同的 View、Action、Resource、Error 和 Long Task。C# 提供 UI 框架自动采集；Native 使用显式 C ABI 和面向 HWND、WinHTTP 的适配器。

采样配置¶

语义	.NET / C#	Native C/C++	默认值	范围
普通 Session 采样	`SampleRate`	`sample_rate`	`1.0`	`0.0`～`1.0`
Error Session 追加采样	`SessionErrorSampleRate`	`session_error_sample_rate`	`0.0`	`0.0`～`1.0`

采样决策在同一个 Session 内保持一致。建议先使用 1.0 验证接入，再根据数据量调整。

采集边界¶

能力	.NET / C#	Native C/C++
View	WPF、WinForms 自动；WinUI 3 显式关联 Window	在窗口生命周期调用 View C ABI
Action	常用 UI 控件自动采集	在命令或窗口消息中调用 Action C ABI
Resource	`HttpClient` 自动采集	WinHTTP 适配器或手动 Resource C ABI
Error	未处理异常自动采集，支持手动 Error	Native 崩溃恢复或手动 Error
Long Task	UI 线程探测或手动上报	`HWND` Watchdog 或手动上报

开启采集¶

.NET / C#Native C/C++

RumSdk.EnableAutomaticInstrumentation(new AutomaticInstrumentationOptions
{
    EnableWpf = true,
    EnableWinForms = true,
    EnableWinUI = true,
    EnableWebView = true,
    EnableHttpClient = true,
    EnableUnhandledException = true,
    EnableUiThreadBlock = true,
    EnableAppLaunch = true,
    UiThreadBlockThreshold = TimeSpan.FromMilliseconds(500),
    UiThreadProbeInterval = TimeSpan.FromMilliseconds(250),
    UiThreadLongTaskCooldown = TimeSpan.FromSeconds(5)
});

创建顶层窗口后，可以启用 UI Watchdog 和崩溃恢复：

guance_rum_native_monitoring_config monitoring;
guance_rum_native_monitoring_config_init(&monitoring);
monitoring.enable_ui_hang_monitoring = 1;
monitoring.main_window_handle = reinterpret_cast<uintptr_t>(main_window);
monitoring.enable_native_crash_reporting = 1;
monitoring.enable_minidump = 0;

if (!guance_rum_enable_native_monitoring(rum, &monitoring)) {
    // HWND 或配置无效。
}

C# 自动采集参数¶

参数	默认值	说明
`EnableWpf`	`true`	自动采集 WPF Window 和常用控件。
`EnableWinForms`	`true`	自动采集 WinForms Form 和常用控件。
`EnableWinUI`	`true`	开启 WinUI 3 控件采集；Window 仍需显式关联。
`EnableWebView`	`true`	自动发现支持的 WebView2 控件。
`EnableHttpClient`	`true`	通过 .NET HTTP 诊断事件采集 Resource。
`EnableUnhandledException`	`true`	采集应用域和 UI 框架未处理异常。
`EnableUiThreadBlock`	`true`	监测 UI 线程阻塞。
`EnableAppLaunch`	`true`	采集应用启动阶段。
`UiThreadBlockThreshold`	`500 ms`	Long Task 阈值。
`UiThreadProbeInterval`	`250 ms`	UI 线程探测间隔。
`UiThreadLongTaskCooldown`	`5 s`	连续阻塞报告的合并冷却时间。

重复调用不会重复注册同一组采集器，但应用仍应只在启动流程中调用一次。

Native 监控参数¶

guance_rum_native_monitoring_config 是版本化结构，必须先调用初始化函数。

字段	默认值	说明
`enable_ui_hang_monitoring`	`0`	是否启用 `HWND` UI Watchdog。
`enable_native_crash_reporting`	`0`	是否启用 SEH 与下次启动崩溃恢复。
`main_window_handle`	`0`	当前进程拥有的有效顶层 `HWND`。
`ui_probe_interval_ms`	`250`	UI 探测间隔。
`long_task_threshold_ms`	`500`	Long Task 阈值。
`hang_threshold_ms`	`5000`	Application Not Responding 阈值。
`hang_report_cooldown_ms`	`5000`	持续卡顿报告冷却时间。
`crash_cache_path`	SDK 默认目录	崩溃信封和可选 Dump 的本地目录。
`enable_minidump`	`0`	是否保留本地最小 Dump；Dump 不上传到 RUM。
`max_crash_files`	`3`	崩溃文件数量上限。
`max_crash_file_bytes`	`32 MiB`	崩溃文件总字节上限。

C++ 应用应包含 guance_rum.hpp，让宿主侧适配器正确安装并恢复 std::terminate 处理器。崩溃进程不执行网络或队列写入；下一次初始化将受限的崩溃信封转换为 RUM Error。

网络 Resource¶

.NET / C#Native C/C++

EnableHttpClient = true 后自动记录 URL、方法、状态码、总耗时、请求/响应大小和 HTTP 协议。需要显式 Handler 时：

using var http = new HttpClient(
    RumSdk.CreateHttpMessageHandler(new HttpClientHandler()));

C++ WinHTTP 使用作用域适配器：

guance::rum::WinHttpResource resource(
    rum,
    request,
    "https://api.example.com/items",
    "GET");
resource.send();
resource.receive();

其他网络库调用 guance_rum_start_resource() 和 guance_rum_stop_resource_ext()。Trace Header 和 RUM 关联请参考 Trace 配置。

应用只能在获得真实网络阶段耗时时记录 DNS、TCP、TLS 或 TTFB，不应估算缺失阶段。

手动 RUM¶

所有自动边界都可以用手动 API 补充。C# 与 Native C/C++ 的 View、Action、Resource、Error 和 Long Task 对照示例请参考自定义采集规则。

Session Replay¶

实验性能力

Windows Session Replay 默认关闭，可以显式开启和验证，但尚未进入稳定发布范围。接入方需要自行评估回放兼容性、隐私、性能和数据量，不应将当前行为作为稳定兼容承诺。

.NET / C#Native C/C++

初始化时显式开启并设置 Replay 采样与默认隐私策略：

RumSdk.Init(new RumConfig
{
    // DatawayUrl / ClientToken / RumAppId ...
    SessionReplay = new RumSessionReplayConfig
    {
        Enabled = true,
        SampleRate = 1.0,
        OnErrorSampleRate = 0.0,
        TextAndInputPrivacy = SessionReplayTextAndInputPrivacy.MaskAll,
        TouchPrivacy = SessionReplayTouchPrivacy.Show,
        ImagePrivacy = SessionReplayImagePrivacy.MaskAll
    }
});

SampleRate 与 OnErrorSampleRate 的范围均为 0.0～1.0。初始化后可以手动控制录制：

RumSdk.StartSessionReplayRecording();
RumSdk.StopSessionReplayRecording();

手动开始不能绕过 Enabled = false；需要先在初始化配置中启用。元素级隐私 API 请参考隐私与数据脱敏。

guance_rum_config config;
guance_rum_config_init(&config);
config.session_replay_enabled = 1;
config.session_replay_sample_rate = 1.0;
config.session_replay_on_error_sample_rate = 0.0;

guance_rum_handle rum = guance_rum_init(&config);
guance_rum_register_replay_window(
    rum,
    reinterpret_cast<uintptr_t>(main_window));

Native Replay 使用独立持久化队列和 v1/write/rum/replay 上传通道。guance_rum_start_session_replay() 与 guance_rum_stop_session_replay() 可以手动控制录制，但开始调用同样不会覆盖关闭的初始化配置。

WebView2 与 Electron 的页面 record 通过原生 Bridge 进入同一原生 Session、分段、队列和上传通道，分别参考 WebView2 与 Electron。

RUM 配置¶

采样配置¶

采集边界¶

开启采集¶

C# 自动采集参数¶

Native 监控参数¶

网络 Resource¶

手动 RUM¶

Session Replay¶

相关文档¶

文档内容是否对您有帮助？ ×