RUM 配置¶

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

RUM 初始化配置¶

采样配置¶

语义	.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++

GuanceSdk.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)
});

自动采集参数¶

参数	默认值	说明
`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 SDK 初始化后默认自动采集冷启动和热启动，并分别生成 action_type=launch_cold、action_type=launch_hot 的 Action。guance_sdk_config_init() 会将 enable_app_launch_tracking 初始化为 1；不需要自动启动 Action 时，应在调用 guance_sdk_init() 前设置为 0：

guance_sdk_config config;
guance_sdk_config_init(&config);
config.enable_app_launch_tracking = 0;

自动采集会观察当前进程的顶层窗口与首个合成帧。冷启动 Action 包含应用代码运行前、应用初始化和首帧三个阶段；应用从后台重新进入前台时会生成热启动 Action。应用仍可使用 guance_rum_add_launch_action() 上报宿主已测量的启动阶段；手动上报冷启动后，SDK 不会再生成重复的自动冷启动 Action。

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

guance_sdk_native_monitoring_config monitoring;
guance_sdk_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_sdk_enable_native_monitoring(rum, &monitoring)) {
    // HWND 或配置无效。
}

Native 监控参数¶

guance_sdk_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_sdk.hpp，让宿主侧适配器正确安装并恢复 std::terminate 处理器。崩溃进程不执行网络或队列写入；下一次初始化将受限的崩溃信封转换为 RUM Error。

网络 Resource¶

.NET / C#Native C/C++

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

using var http = new HttpClient(
    GuanceSdk.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 手动埋点¶

自动采集无法表达业务语义时，可以手动上报 Action、View、Error、Long Task 和 Resource。.NET / C# 使用 GuanceSdk，Native C/C++ 使用 guance_rum.h 中的 C ABI；两种接入产生相同的 Windows RUM 数据类型。

避免重复采集

手动 API 和自动采集写入同一 Session。已经由窗口、控件、HttpClient、WinHTTP 或 WebView2 自动采集的数据，不要再次手动上报。

Action¶

自动结束的 Action¶

用于采集用户操作，并关联操作期间产生的 Resource、Error 和 Long Task：

.NET / C#Native C/C++

var action = GuanceSdk.StartAction("SaveOrder", "click");
if (!action.IsAccepted)
{
    // 本次调用被高频保护忽略。
}

普通模式不需要调用 StopAction，释放返回的 RumActionScope 也不会结束 Action。

const char* action_id = guance_rum_start_action(rum, "SaveOrder", "click");
if (action_id[0] == '\0') {
    // 本次调用被高频保护忽略。
}

普通模式与 Android SDK 行为一致：同一个时刻只保留一个活动 Action；100 ms 内连续调用 StartAction 会忽略新调用，超过 100 ms 后再次调用会结束上一个 Action 并开始新的 Action。Action 在 View 切换时结束，且最长持续约 5 秒。

等待业务结束的 Action¶

业务操作必须覆盖一段异步逻辑时，启用 needWait 模式。只有该模式需要与 StopAction 配对使用：

.NET / C#Native C/C++

using (GuanceSdk.StartAction("SaveOrder", "custom", needWait: true))
{
    await SaveOrderAsync();
}

也可以保存 ActionId，在业务结束时调用 GuanceSdk.StopAction(actionId)。

const char* action_id = guance_rum_start_action_ext(
    rum,
    "SaveOrder",
    "custom",
    1);

save_order();

if (action_id[0] != '\0') {
    guance_rum_stop_action(rum, action_id);
}

needWait Action 在显式结束前不会被新的 Action 替换，但同样受约 5 秒最长持续时间和 View 切换限制。开始 Action 时如果返回空 ID，表示本次调用未被接受，不应再调用 StopAction。

已知耗时的 Action¶

.NET / C#Native C/C++

GuanceSdk.AddAction(
    name: "ExportReport",
    type: "custom",
    duration: TimeSpan.FromMilliseconds(320),
    properties: new Dictionary<string, object?>
    {
        ["format"] = "csv"
    });

constexpr int64_t duration_ns = 320LL * 1000 * 1000;
guance_rum_add_action(rum, "ExportReport", "custom", duration_ns);

AddAction 用于直接上报已经结束且耗时已知的独立 Action，不受 100 ms 高频保护和 5 秒限制，也不会关联后续产生的 Resource、Error 或 Long Task。

View¶

.NET / C#Native C/C++

GuanceSdk.StartView(
    "OrderDetail",
    new Dictionary<string, object?>
    {
        ["order_type"] = "subscription"
    });

// 页面结束时执行。
GuanceSdk.StopView();

guance_rum_start_view(rum, "OrderDetail");

// 页面或窗口结束时执行。
guance_rum_stop_view(rum);

启动新的 View 会自动结束当前活动 View。View 名称应描述稳定页面，不要包含订单号、用户 ID、对象地址或搜索词。

Error¶

.NET / C#Native C/C++

try
{
    await LoadOrdersAsync();
}
catch (Exception exception)
{
    GuanceSdk.AddError(
        exception,
        new Dictionary<string, object?>
        {
            ["operation"] = "load_orders"
        });
}

非 Exception 错误可以使用 GuanceSdk.AddError(stack, message, errorType, source)。启用未处理异常自动采集时，如果手动上报后继续抛出同一个异常，并最终导致进程终止，还会产生一条 windows_crash；应根据业务语义避免重复上报。

guance_rum_add_error(
    rum,
    "OrderRepository::load_orders",
    "Order request failed",
    "NetworkError",
    "custom");

自动采集的 .NET 致命异常使用 error_type=windows_crash，Native SEH 与 C++ std::terminate 使用 error_type=native_crash；Crash 的 error_source 均为 logger。Native 崩溃监控在下次启动时恢复崩溃 Error；不要在崩溃处理器中再调用手动 Error API。完整类型和字段说明请参考应用数据采集。

Long Task¶

.NET / C#Native C/C++

GuanceSdk.AddLongTask(
    duration: TimeSpan.FromMilliseconds(850),
    stack: "ReportRenderer.Render");

constexpr int64_t duration_ns = 850LL * 1000 * 1000;
guance_rum_add_long_task(rum, duration_ns, "ReportRenderer::render");

已开启 UI 线程阻塞监控时，不要对同一段阻塞再次手动上报。

Resource¶

.NET / C#Native C/C++

var resourceId = GuanceSdk.StartResource(
    "https://api.example.com/orders",
    "GET");

GuanceSdk.StopResource(
    resourceId,
    statusCode: 200,
    timing: RumResourceTiming.FromTotalElapsed(
        TimeSpan.FromMilliseconds(120),
        source: "manual"),
    responseSize: 2048,
    requestSize: 0,
    resourceType: "http");

如果应用已经测量 DNS、TCP、TLS 和 TTFB，可以使用 RumResourceTiming.FromPhases() 写入阶段耗时；没有可靠数据时只写总耗时。

C++ 应用可以使用 ResourceScope 保证异常或提前返回时仍结束 Resource：

#include "guance_sdk.hpp"

guance::rum::ResourceScope resource(
    rum,
    "https://api.example.com/orders",
    "GET",
    "http");

const auto response = send_request();
resource.complete(
    response.status_code,
    response.body_size,
    response.request_size);

纯 C 应用可以配对调用 guance_rum_start_resource() 与 guance_rum_stop_resource()；需要写入 trace_id、span_id、请求大小或 HTTP 协议时使用 guance_rum_stop_resource_ext()。

请求失败时仍需结束 Resource，并将状态码设为 0。启用了 HttpClient 或 WinHTTP 自动 Resource 后，不要为同一请求再次调用手动 API。

Flush¶

手动事件先进入本地队列。如需在关键流程后立即尝试上报：

.NET / C#Native C/C++

await GuanceSdk.FlushAsync();

guance_sdk_flush(rum);

应用正常退出时仍应调用 ShutdownAsync() 或 guance_sdk_shutdown()。HTTP Trace 传播和应用日志分别参考 Trace 配置与 Log 配置。

Session Replay¶

实验性能力

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

.NET / C#Native C/C++

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

GuanceSdk.Init(new GuanceConfig
{
    // 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。初始化后可以手动控制录制：

GuanceSdk.StartSessionReplayRecording();
GuanceSdk.StopSessionReplayRecording();

手动开始不能绕过 Enabled = false；需要先在初始化配置中启用。元素级隐私 API 请参考 Windows 会话重放隐私覆盖。

guance_sdk_config config;
guance_sdk_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_sdk_handle rum = guance_sdk_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 配置¶

RUM 初始化配置¶

采样配置¶

采集边界¶

开启采集¶

自动采集参数¶

Native 监控参数¶

网络 Resource¶

RUM 手动埋点¶

Action¶

自动结束的 Action¶

等待业务结束的 Action¶

已知耗时的 Action¶

View¶

Error¶

Long Task¶

Resource¶

Flush¶

Session Replay¶

相关文档¶

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

RUM 配置¶

RUM 初始化配置¶

采样配置¶

采集边界¶

开启采集¶

自动采集参数¶

Native 监控参数¶

网络 Resource¶

RUM 手动埋点¶

Action¶

自动结束的 Action¶

等待业务结束的 Action¶

已知耗时的 Action¶

View¶

Error¶

Long Task¶

Resource¶

Flush¶

Session Replay¶

相关文档¶

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

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