故障排查¶

SDK 初始化异常校验¶

.NET / C# 配置校验¶

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

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

1. 确认应用、导入库和 guance_windows_native.dll 使用相同架构。当前 vcpkg 端口只提供动态 x64-windows；其他架构需要使用匹配架构的源码构建产物。
2. 确认 DLL 位于应用目录或 Windows DLL 搜索路径中；NuGet 包中的 x86、x64 和 ARM64 Native 运行时资产供 .NET 包装层使用，不等同于 C/C++ 头文件和导入库。
3. 先调用 guance_sdk_config_init()，再填写地址、Token、应用 ID、服务名、版本和环境。
4. 公网 DataWay 需要地址和 Client Token；本地环境部署（Datakit）需要填写可访问的 Datakit 地址。
5. guance_sdk_init() 返回空 Handle 时，检查必填项、缓存目录权限和进程架构。

SDK 正常运行但是没有数据¶

控制台没有 RUM 数据¶

依次检查：

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

var snapshot = GuanceSdk.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_sdk_diagnostics diagnostics{};
if (guance_sdk_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");
// 或 GuanceSdk.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 数据¶

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

请求没有 Trace Header¶

1. 确认已开启 EnableAutoTrace 或 enable_auto_trace。
2. 确认采样率不为 0，并检查目标 URL 是否通过 ShouldTrace 或 should_trace。
3. 检查服务端要求的传播格式与 TraceType 或 trace_type 是否一致。
4. Trace Header 由所选格式决定，不要只搜索名为 trace_id 的 HTTP Header。
5. 不要向不受信任的目标放行 Trace 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 没有页面数据¶

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

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

Electron 没有数据¶

先确认应用采用哪种 Electron 接入方式，两种方式的 Session 和上传所有者不同，不能混用配置。

数据重复¶

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

Replay 已启用但没有数据¶

1. .NET 升级到 NuGet 0.1.0-alpha.9 后，确认已安装同版本的 Guance.Windows.SessionReplay。通过初始化配置的 DiagnosticListener 检查 session_replay_component，区分缺包、版本不匹配和加载失败。
2. Native 升级到 vcpkg 0.1.0-alpha.10 后，确认启用 replay Feature，且 Replay DLL 与基础 DLL 相邻、版本和架构一致。检查标准错误输出中的 Replay 组件诊断，不要只检查 session_replay_enabled。
3. 使用客户端 IsSessionReplayAvailable 或 guance_rum_is_session_replay_available() 确认组件可用，再检查采样率、活动 View 和录制启停状态。组件可用不代表当前 Session 已采样。
4. Electron Full Mode 确认已通过 --with-replay 或 --replay-archive 安装并打包补充组件；Mixed Mode 确认宿主 Native 和 Bridge Server 均启用 Replay。WebView2/Electron 的 getCapabilities() 不含 records 时，页面不应强制启动录制。

仅安装基础包时普通 RUM、Log、Trace 仍可工作。具体安装方式见可选组件安装。

退出时仍有队列数据¶

await GuanceSdk.ShutdownAsync();

guance_sdk_flush(rum);
guance_sdk_shutdown(rum);

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

开启 Debug 调试¶

Native 在测试环境设置 debug = 1；C# 没有运行时 Debug 配置字段，可通过初始化配置的 DiagnosticListener 或 GuanceSdk.AddDiagnosticListener() 记录 SDK 级别、来源和消息。提交问题时提供：

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

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