故障排查¶

初始化失败¶

.NET / C# 配置校验¶

RumSdk.Init() 会立即校验关键配置：

异常信息	处理方式
`RumAppId is required.`	设置控制台中创建的应用 ID。
`ServiceName is required.`	设置非空 `ServiceName`。
`Version is required.`	设置应用版本。
`Env must be one of...`	使用 `prod`、`gray`、`pre`、`common` 或 `local`。
`Either DatawayUrl or DatakitUrl is required.`	至少设置一个上报地址。
`ClientToken is required when DatawayUrl is configured.`	公网 DataWay 模式补充 Client Token。
`SampleRate must be between 0 and 1.`	将采样率调整到 `0.0`～`1.0`。

Native C/C++ 初始化或加载失败¶

确认应用、导入库和 guance_rum_native.dll 使用相同架构：x86、x64 或 ARM64。
确认 DLL 位于应用目录或 Windows DLL 搜索路径中；NuGet 包中的 Native 运行时资产不等同于 C/C++ 头文件和导入库。
先调用 guance_rum_config_init()，再填写地址、Token、应用 ID、服务名、版本和环境。
公网 DataWay 需要地址和 Client Token；本地环境部署（Datakit）需要填写可访问的 Datakit 地址。
guance_rum_init() 返回空 Handle 时，检查必填项、缓存目录权限和进程架构。

控制台没有 RUM 数据¶

依次检查：

App ID 是否与当前工作空间中的“自定义”应用一致。
公网 DataWay 是否同时设置正确的基础地址和 Client Token。
本地环境部署（Datakit）是否可从应用进程访问，且 RUM 采集器已经启用。
RUM SampleRate 或 sample_rate 是否大于 0。
是否已经启动 View 或开启对应自动采集。
应用退出前是否等待或调用关闭 API。

.NET / C# 诊断Native C/C++ 诊断

var snapshot = RumSdk.GetDiagnosticsSnapshot();
Console.WriteLine(
    $"sampled={snapshot.SessionSampled}, " +
    $"enqueued={snapshot.RumEventsEnqueued}, " +
    $"uploaded={snapshot.RumUploadSuccessCount}, " +
    $"retry={snapshot.RumUploadRetryCount}, " +
    $"terminal={snapshot.RumUploadTerminalFailureCount}, " +
    $"lastStatus={snapshot.LastRumUploadStatusCode}, " +
    $"lastError={snapshot.LastRumUploadError}");

guance_rum_diagnostics diagnostics{};
if (guance_rum_get_diagnostics(rum, &diagnostics)) {
    printf("queued=%lld uploaded=%lld retries=%lld status=%lld error=%lld\n",
        static_cast<long long>(diagnostics.rum_events_enqueued),
        static_cast<long long>(diagnostics.rum_upload_success_count),
        static_cast<long long>(diagnostics.rum_upload_retry_count),
        static_cast<long long>(diagnostics.last_rum_upload_status_code),
        static_cast<long long>(diagnostics.last_rum_upload_error_code));
}

入队计数为 0 时优先检查采样、View 和采集开关；重试持续增加时检查网络、代理、DNS 和上报地址；终止失败增加时检查 Token、权限和服务端状态码。

桌面 UI 没有 View 或 Action¶

WPF 和 WinForms¶

在第一个窗口创建前调用 EnableAutomaticInstrumentation()。
确认 EnableWpf 或 EnableWinForms 没有关闭。
为关键控件设置稳定的 Name、标题或可访问性名称。
动态 WinForms 控件会在 Application Idle 扫描；消息循环长时间没有空闲时可能延迟发现。

WinUI 3¶

WinUI 3 窗口必须在 Activate() 前显式关联，多窗口应用需要逐个关联：

window = new MainWindow().UseGuanceRum("MainWindow");
// 或 RumSdk.AttachWinUIWindow(window, "MainWindow");
window.Activate();

Native C/C++¶

窗口创建后调用 guance_rum_start_view()，窗口关闭前调用 guance_rum_stop_view()。
Action 需要在命令、菜单或输入消息处理边界显式开始和结束。
UI Watchdog 需要当前进程拥有的有效顶层 HWND。
Native SDK 不安装通用窗口或控件 Hook，不会自动发现所有 MFC 或自定义框架事件。

没有 Log 数据¶

.NET / C#Native C/C++

确认 RumConfig.LogConfig 已设置，且 EnableCustomLog = true。
检查 SampleRate、LevelFilters 和消息是否超过 30 KiB UTF-8 上限。
自动采集 System.Diagnostics.Trace 时，确认 EnableTraceCapture = true；它仍要求开启 EnableCustomLog。
读取 GetLogDiagnosticsSnapshot()，分别检查配置、采样、级别和容量丢弃计数。

先调用 guance_rum_log_config_init()，再调用 guance_rum_configure_logging()。
确认 enable_custom_log 为 1，并检查 sample_rate 与 level_filter_mask。
Native SDK 不自动拦截 Console、ETW 或第三方日志库，应在现有日志出口调用 guance_rum_add_log() 或 guance_rum_add_logs()。
使用 guance_rum_get_log_diagnostics() 检查入队、丢弃、重试和最后状态码。

Log 与 RUM 使用独立队列。RUM 正常不代表 Log 已启用，反之亦然。

请求没有 Trace Header¶

确认已开启 EnableAutoTrace 或 enable_auto_trace。
确认采样率不为 0，并检查目标 URL 是否通过 ShouldTrace 或 should_trace。
检查服务端要求的传播格式与 TraceType 或 trace_type 是否一致。
Trace Header 由所选格式决定，不要只搜索名为 trace_id 的 HTTP Header。
不要向不受信任的目标放行 Trace Header。

.NET / C#Native C/C++

自动诊断订阅要求 AutomaticInstrumentationOptions.EnableHttpClient = true。自定义 HttpClient 管线可以显式使用 RumSdk.CreateHttpMessageHandler()。

WinHTTP 请求需要使用 guance_rum_winhttp.hpp 适配器；其他 HTTP 库需要调用 guance_rum_create_trace_context() 并把返回 Header 写入请求。

如果请求已有同名 Trace Header，检查 HTTP 库或业务代码是否在 SDK 注入后覆盖了它。

Trace 或 Log 没有关联 RUM¶

分别开启 Trace/Log 配置中的 EnableLinkRumData 或 enable_link_rum_data。
在活动 View 或 Action 存在时发起请求或写入 Log；SDK 不回溯修改已经结束的上下文。
Trace 关联信息写入匹配的 RUM Resource。Windows SDK 不独立上传 APM Span，因此在 Trace 控制台中没有 Span 不等于 Header 注入失败。

WebView2 没有页面数据¶

确认 WebView2 Runtime 已安装且控件可以完成 EnsureCoreWebView2Async()。
确认 EnableWebView = true，或显式调用 AttachWebView()。
动态控件建议在初始化完成后显式关联。
控件被 Unloaded 或 Disposed 后，需要在新实例上重新关联。
注册诊断监听器，检查 WebView2 initialization failed 或 did not succeed。

同一个控件重复调用 AttachWebView() 不会重复注入。若页面本身也初始化了 Browser RUM，不要再对同一页面事件进行重复手动上报。

Electron 没有数据¶

Browser RUM 只在 renderer 中初始化。
file:// 页面设置 sessionPersistence: "local-storage"。
每个独立 renderer 页面都需要初始化。
main process 不会自动把 RUM 实例传给远程页面。
检查 Browser RUM 的 applicationId、site/datakitOrigin、Token 和采样率。
不要将 Electron 初始化替换为 Windows NuGet 或 Native C++ SDK。

完整排查方式请参考 Electron 应用接入。

数据重复¶

应用启动过程中只初始化一次对应 SDK Handle。
.NET 重复调用 RumSdk.Init() 会异步释放旧客户端，初始化边界重叠可能造成重复采集。
自动采集已经覆盖的控件交互、HttpClient 或 WinHTTP 请求不要再次手动上报。
WinUI 3 同一个窗口只使用一种关联写法。
Electron renderer 应保证初始化入口只执行一次。

退出时仍有队列数据¶

.NET / C#Native C/C++

await RumSdk.ShutdownAsync();

guance_rum_flush(rum);
guance_rum_shutdown(rum);

不要只触发异步关闭后立即终止进程。Native 崩溃 Error 会在下一次启动时恢复并入队，不会在崩溃进程中执行网络上传。

仍无法定位¶

在测试环境开启 Debug = true 或 debug = 1。C# 可通过 RumSdk.AddDiagnosticListener() 记录 SDK 级别、来源和消息。提交问题时提供：

SDK 版本、运行时或编译器版本和 Windows 版本；
UI 框架、进程架构和接入语言；
已脱敏的配置；
RUM 与 Log 诊断计数、状态码；
可复现的最小步骤。

不要提交 Client Token、认证 Header、Cookie、用户敏感信息或本地绝对路径。

故障排查¶

初始化失败¶

.NET / C# 配置校验¶

Native C/C++ 初始化或加载失败¶

控制台没有 RUM 数据¶

桌面 UI 没有 View 或 Action¶

WPF 和 WinForms¶

WinUI 3¶

Native C/C++¶

没有 Log 数据¶

请求没有 Trace Header¶

Trace 或 Log 没有关联 RUM¶

WebView2 没有页面数据¶

Electron 没有数据¶

数据重复¶

退出时仍有队列数据¶

仍无法定位¶

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