Troubleshooting¶
SDK Initialization Error Checks¶
.NET / C# Configuration Validation¶
GuanceSdk.Init() validates critical configuration immediately:
| Error Message | Resolution |
|---|---|
RumAppId is required. |
Set the application ID created in the console. |
ServiceName is required. |
Set a non-empty ServiceName. |
Version is required. |
Set the application version. |
Env must be one of... |
Use prod, gray, pre, common, or local. |
Either DatawayUrl or DatakitUrl is required. |
Set at least one reporting endpoint. |
ClientToken is required when DatawayUrl is configured. |
Add the Client Token for public DataWay mode. |
SampleRate must be between 0 and 1. |
Set the sample rate to a value between 0.0 and 1.0. |
Native C/C++ Initialization or Loading Failures¶
- Confirm that the application, import library, and
guance_windows_native.dlluse the same architecture. The current vcpkg port only provides dynamicx64-windows; for other architectures, use source build artifacts built for the matching architecture. - Confirm that the DLL is in the application directory or in the Windows DLL search path. The x86, x64, and ARM64 native runtime assets in the NuGet package are intended for the .NET wrapper layer; they are not equivalent to C/C++ headers and import libraries.
- Call
guance_sdk_config_init()first, then populate the endpoint, Token, application ID, service name, version, and environment. - Public DataWay requires an endpoint and Client Token; for a local deployment (Datakit), provide an accessible Datakit endpoint.
- If
guance_sdk_init()returns a null Handle, check required fields, cache directory permissions, and the process architecture.
SDK Runs Normally but No Data¶
No RUM Data in the Console¶
Check the following in order:
- Whether the App ID matches the "Custom" application in the current Workspace.
- Whether the public DataWay has both the correct base URL and Client Token configured.
- Whether the local deployment (Datakit) is reachable from the application process and the RUM collector is enabled.
- Whether the RUM
SampleRateorsample_rateis greater than0. - Whether a View has been started or the corresponding automatic collection has been enabled.
- Whether the application waits for or calls the shutdown API before exiting.
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));
}
If the enqueued count is 0, first check sampling, View, and collection switches. If retries keep increasing, check network, proxy, DNS, and the reporting endpoint. If terminal failures increase, check the Token, permissions, and server status codes.
No View or Action in the Desktop UI¶
WPF and WinForms¶
- Call
EnableAutomaticInstrumentation()before the first window is created. - Confirm that
EnableWpforEnableWinFormsis not disabled. - Set a stable
Name, title, or accessibility name for key controls. - Dynamic WinForms controls are scanned during Application Idle; if the message loop has no idle time for a long period, discovery may be delayed.
WinUI 3¶
WinUI 3 windows must be explicitly attached before Activate(). For multi-window applications, attach each window individually:
window = new MainWindow().UseGuanceRum("MainWindow");
// Or GuanceSdk.AttachWinUIWindow(window, "MainWindow");
window.Activate();
Native C/C++¶
- Call
guance_rum_start_view()after a window is created, and callguance_rum_stop_view()before it closes. - Actions must be explicitly started and ended at command, menu, or input message handling boundaries.
- The UI Watchdog requires a valid top-level
HWNDowned by the current process. - The Native SDK does not install universal window or control hooks, so it cannot automatically discover all MFC or custom framework events.
No Log Data¶
- Confirm that
GuanceConfig.Loggingis set andEnableCustomLog = true. - Check
SampleRate,LevelFilters, and whether messages exceed the 30 KiB UTF-8 limit. System.Diagnostics.Traceoutput is not automatically forwarded by the SDK. Explicitly callAddLog()orAddLogs()at the application's existing log output points.- Read
GetLogDiagnosticsSnapshot()and check the configuration, sampling, level, and capacity discard counts separately.
- Call
guance_log_config_init()first, then callguance_log_configure(). - Confirm that
enable_custom_logis1, and checksample_rateandlevel_filter_mask. - The Native SDK does not automatically intercept Console, ETW, or third-party logging libraries. Call
guance_log_add()orguance_log_add_batch()at your existing log output points. - Use
guance_log_get_diagnostics()to check enqueue, discard, retry, and the last status code.
Log and RUM use separate queues. RUM working normally does not mean Log is enabled, and vice versa.
Requests Have No Trace Header¶
- Confirm that
EnableAutoTraceorenable_auto_traceis enabled. - Confirm that the sample rate is not
0, and check whether the target URL passesShouldTraceorshould_trace. - Check that the propagation format required by the server matches
TraceTypeortrace_type. - The trace header is determined by the selected format, so do not only search for an HTTP header named
trace_id. - Do not forward trace headers to untrusted targets.
Automatic diagnostic subscriptions require AutomaticInstrumentationOptions.EnableHttpClient = true. Custom HttpClient pipelines can explicitly use GuanceSdk.CreateHttpMessageHandler().
WinHTTP requests must use the guance_rum_winhttp.hpp adapter. For other HTTP libraries, call guance_trace_create_context() and write the returned header into the request.
If the request already has a trace header with the same name, check whether the HTTP library or business code overwrote it after SDK injection.
Trace or Log Is Not Correlated with RUM¶
- Enable
EnableLinkRumDataorenable_link_rum_datain the Trace/Log configuration separately. - Start requests or write logs while an active View or Action exists; the SDK does not retroactively modify contexts that have already ended.
- Trace correlation information is written to the matching RUM resource. The Windows SDK does not upload APM spans independently, so the absence of a span in the trace console does not mean header injection failed.
No Page Data for WebView2¶
- Confirm that the WebView2 Runtime is installed and the control can complete
EnsureCoreWebView2Async(). - Confirm that
EnableWebView = true, or explicitly callAttachWebView(). - For dynamic controls, explicitly attach after initialization completes.
- After a control is
UnloadedorDisposed, attach it again on the new instance. - Register a diagnostic listener and check for
WebView2 initialization failedordid not succeed.
Calling AttachWebView() repeatedly on the same control does not inject more than once. If the page itself also initialized Browser RUM, do not manually report the same page events again.
No Data for Electron¶
First confirm which Electron integration mode the application uses. The two modes have different Session and upload owners, and their configurations must not be mixed.
- In Full Mode, check the runtime downloaded by npm or the
native.directoryspecified by the CLI; in Mixed Mode, check that the C++ host has initialized the SDK and started a Bridge Server matchingnative.pipeName. See Electron Monitoring for the installation steps for both modes. - In Full Mode, the packaged directory is
resources/native/outside the ASAR and should contain the Bridge EXE, base DLLs, and manifest with the same version and architecture. When using Replay, also include the supplemental DLL andreplay-manifest.json. In Mixed Mode, the host deploys the base and optional DLLs. - In Full Mode, provide the complete Native configuration through
native.settings, and check startup and component loading diagnostics. Exit code2indicates a missing reporting endpoint or RUM Application ID; exit code3indicates Native Core initialization or Log configuration failure. - Browser RUM/Logs are initialized only in monitored Renderers. Each window requires installing a Preload, registering trusted
webContents, and performing one minimal initialization. In the Renderer, only fill in the placeholder parameters required for Bridge mode; do not fill in real Tokens, application IDs, or reporting endpoints. - Direct upload requests for RUM, Log, or Replay should not appear in the Renderer DevTools Network. Check whether the fixed IPC channel receives messages and whether the Main Process accepts the trusted Renderer. In Full Mode, check the Bridge EXE stdin/stdout transport; in Mixed Mode, check the named-pipe connection.
- Check the Native Host RUM, Log, and Replay enqueue counts, upload status codes, retries, and final failure counts. When the application exits, wait for the Adapter's
stop()to complete. In Mixed Mode, have the host close its SDK Handle afterward to avoid losing queued data.
The Bridge cannot automatically capture Electron Main Process crashes. The Renderer unresponsive and render-process-gone events must be listened to by the Main Process and converted into trusted Bridge commands. See Electron Monitoring for the full integration approach.
- Browser RUM is initialized only in the Renderer, and each independent Renderer page must be initialized.
- For
file://pages, setsessionPersistence: "local-storage". - The Main Process does not automatically pass the RUM instance to remote pages.
- Check the Browser RUM
applicationId,site/datakitOrigin, Token, and sample rate. - This mode does not start the Windows Native Bridge. For full troubleshooting, see Web RUM Electron App Integration.
Duplicate Data¶
- Initialize the corresponding SDK Handle only once during application startup.
- In .NET, repeated calls to
GuanceSdk.Init()asynchronously release the old client, and overlapping initialization boundaries can cause duplicate collection. - Do not manually report control interactions,
HttpClientrequests, or WinHTTP requests already covered by automatic collection. - For WinUI 3, use only one attachment method for the same window.
- For Electron, ensure the initialization entry runs only once in the renderer.
Replay Is Enabled but No Data¶
- After upgrading .NET to NuGet
0.1.0-alpha.9, confirm that the same version ofGuance.Windows.SessionReplayis installed. Use theDiagnosticListenerconfigured during initialization to checksession_replay_component, and distinguish missing package, version mismatch, and load failure. - After upgrading Native to vcpkg
0.1.0-alpha.10, confirm that thereplayfeature is enabled and that the Replay DLL is adjacent to the base DLL with matching version and architecture. Check the Replay component diagnostics in standard error output; do not only checksession_replay_enabled. - Use the client-side
IsSessionReplayAvailableorguance_rum_is_session_replay_available()to confirm the component is available, then check the sample rate, active View, and recording start/stop status. Component availability does not mean the current Session has been sampled. - For Electron Full Mode, confirm that the supplemental components were installed and packaged with
--with-replayor--replay-archive; for Mixed Mode, confirm that both the host Native SDK and the Bridge Server have Replay enabled. If WebView2/ElectrongetCapabilities()does not includerecords, the page should not force recording to start.
When only the base package is installed, normal RUM, Log, and Trace continue to work. See Optional Component Installation for details.
Queued Data Remains on Exit¶
Do not trigger async shutdown and then immediately terminate the process. Native crash errors are recovered and enqueued on the next startup; network upload is not performed in the crashed process.
Enabling Debug Mode¶
For Native, set debug = 1 in a test environment. C# has no runtime Debug configuration field; use the DiagnosticListener configured during initialization or GuanceSdk.AddDiagnosticListener() to record the SDK level, source, and messages. When submitting an issue, provide:
- SDK version, runtime or compiler version, and Windows version;
- UI framework, process architecture, and integration language;
- Redacted configuration;
- RUM and Log diagnostic counts and status codes;
- Minimal steps to reproduce.
Do not submit Client Tokens, authentication headers, cookies, sensitive user information, or local absolute paths.