跳转至

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 采样 SessionSamplingRate(NuGet 0.1.0-alpha.8 起) session_sampling_rate(vcpkg 0.1.0-alpha.9 起) 100 0~100
Error Session 追加采样 SessionOnErrorSamplingRate(NuGet 0.1.0-alpha.8 起) session_on_error_sampling_rate(vcpkg 0.1.0-alpha.9 起) 0 0~100
普通 Session 采样(旧) SampleRate(已废弃) 旧结构 sample_rate(已废弃) 1 0~1;改用 SessionSamplingRate / session_sampling_rate。
Error Session 追加采样(旧) SessionErrorSampleRate(已废弃) 旧结构 session_error_sample_rate(已废弃) 0 0~1;改用 SessionOnErrorSamplingRate / session_on_error_sampling_rate。

新字段使用 float 百分比,支持 0.1(表示 0.1%)等小数。采样决策在同一个 Session 内保持一致。建议先使用 100 验证接入,再根据数据量调整。

若同一个 .NET 配置对象同时设置新旧字段,以新字段为准,包括显式设置 0;新字段非法时不会回退到旧字段。Native 使用 ABI 安全的 guance_sdk_config_v2 和 guance_sdk_init_v2()。

采集边界

能力 .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 或手动上报

开启采集

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_v2_init() 会将 enable_app_launch_tracking 初始化为 1;不需要自动启动 Action 时,应在调用 guance_sdk_init_v2() 前设置为 0:

guance_sdk_config_v2 config;
guance_sdk_config_v2_init(&config);
config.enable_app_launch_tracking = 0;
字段 默认值 说明
enable_app_launch_tracking 1 自动采集冷启动和热启动 Action;设为 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

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:

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 配对使用:

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

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

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

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

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

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

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

await GuanceSdk.FlushAsync();
guance_sdk_flush(rum);

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

Session Replay

从 NuGet 0.1.0-alpha.9、vcpkg 0.1.0-alpha.10 起,Replay 实现由可选组件提供。先按可选组件安装添加同版本组件,再启用以下配置;既有配置、控制及隐私 API 保留。Electron 的补充运行时安装方式见 Electron 监测。

Replay 关闭时不会加载组件或创建 Replay 上传通道;配置开启但组件缺失、版本不匹配或加载失败时,SDK 禁用 Replay 并输出组件诊断,普通 RUM、Log、Trace 继续工作。安装组件本身不会开启录制。C# 可读取初始化返回客户端的 IsSessionReplayAvailable,Native 可调用 guance_rum_is_session_replay_available(rum),分别判断组件是否可用;可用状态不代表当前 Session 已采样或已开始录制。

Replay 参数

.NET / C#(SessionReplay) Native(sdk_config_v2) 默认值 说明
Enabled session_replay_enabled false / 0 是否启用录制。
SamplingRate(NuGet 0.1.0-alpha.8 起) session_replay_sampling_rate(vcpkg 0.1.0-alpha.9 起) 100 普通 Session 的 Replay 采样百分比,0~100,支持小数。
OnErrorSamplingRate(NuGet 0.1.0-alpha.8 起) session_replay_on_error_sampling_rate(vcpkg 0.1.0-alpha.9 起) 0 Error Session 追加采样百分比,0~100,支持小数。
TextAndInputPrivacy — MaskAll 文本与输入隐私策略。
TouchPrivacy — Show 指针和触控隐私策略。
ImagePrivacy — MaskAll 图片隐私策略。
SegmentRecordLimit session_replay_segment_record_limit 500 单个 Replay 分段记录数上限。
SegmentBytesLimit session_replay_segment_bytes_limit 1 MiB 单个分段未压缩字节上限。
FlushInterval — 5 s 活跃分段的 Flush 间隔。
MaxNodeCount — 2000 单次快照节点上限。
MaxTreeDepth — 64 UI 树深度上限。
MaxTextLength — 256 单节点文本长度上限。
MaxAttributeValueLength — 512 单个属性值长度上限。
CaptureImages — true 设为 false 时覆盖图片策略,隐藏所有图片。
MaxImageBytes — 512 KiB 单张图片编码字节上限。
MaxImageDimension — 1024 图片编码宽高上限。
LargeImagePrivacyThreshold — 100 MaskLargeOnly 的图片面积阈值。
CustomRenderedTypeNameMarkers — 内置自定义渲染类型标记 按类型名片段识别不透明或自定义渲染内容。
SensitiveTextPatterns — 邮箱、银行卡号、电话号码模式 识别敏感文本的正则表达式集合。
SampleRate(已废弃) 旧结构 session_replay_sample_rate(已废弃) 1 兼容旧 0~1 单位,改用对应新采样字段。
OnErrorSampleRate(已废弃) 旧结构 session_replay_on_error_sample_rate(已废弃) 0 兼容旧 0~1 单位,改用对应新采样字段。
实验性能力

Windows Session Replay 默认关闭,可以显式开启和验证,属于实验性能力。接入方需要自行评估回放兼容性、隐私、性能和数据量,不应将当前行为作为稳定兼容承诺。

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

GuanceSdk.Init(new GuanceConfig
{
    // DatawayUrl / ClientToken / RumAppId ...
    SessionReplay = new RumSessionReplayConfig
    {
        Enabled = true,
        SamplingRate = 100, // NuGet 0.1.0-alpha.8 起支持
        OnErrorSamplingRate = 0, // NuGet 0.1.0-alpha.8 起支持
        TextAndInputPrivacy = SessionReplayTextAndInputPrivacy.MaskAll,
        TouchPrivacy = SessionReplayTouchPrivacy.Show,
        ImagePrivacy = SessionReplayImagePrivacy.MaskAll
    }
});

SamplingRate 与 OnErrorSamplingRate(NuGet 0.1.0-alpha.8 起支持)均为 float 百分比,范围为 0~100。初始化后可以手动控制录制:

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

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

guance_sdk_config_v2 config;
guance_sdk_config_v2_init(&config);
config.session_replay_enabled = 1;
config.session_replay_sampling_rate = 100.0f; // vcpkg 0.1.0-alpha.9 起支持
config.session_replay_on_error_sampling_rate = 0.0f; // vcpkg 0.1.0-alpha.9 起支持

guance_sdk_handle rum = guance_sdk_init_v2(&config);
if (guance_rum_is_session_replay_available(rum)) {
    guance_rum_register_replay_window(
        rum,
        reinterpret_cast<uintptr_t>(main_window));
    guance_rum_start_session_replay(rum);
}

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

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

相关文档

文档评价

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