Troubleshooting¶

SDK Initialization Error Validation¶

.NET / C# Configuration Validation¶

GuanceSdk.Init() validates key configuration immediately:

Native C/C++ Initialization or Loading Failures¶

1. Confirm that the application, the import library, and guance_windows_native.dll use the same architecture. The current vcpkg port provides only dynamic x64-windows; other architectures require source-built artifacts for the matching architecture.
2. Confirm that the DLL is in the application directory or the Windows DLL search path. The x86, x64, and ARM64 Native runtime assets in the NuGet package are for the .NET wrapper layer and are not equivalent to the C/C++ headers and import library.
3. Call guance_sdk_config_init() first, then fill in the endpoint, Token, application ID, service name, version, and environment.
4. Public DataWay requires an endpoint and a Client Token; for a local deployment (Datakit), provide an accessible Datakit endpoint.
5. If guance_sdk_init() returns a null Handle, check the required fields, cache directory permissions, and process architecture.

SDK Runs Normally but No Data Is Reported¶

No RUM Data in the Console¶

Check the following in order:

1. Whether the App ID matches the "Custom" application in the current Workspace.
2. Whether the public DataWay has both a correct base URL and Client Token configured.
3. Whether the local deployment (Datakit) is reachable from the application process and the RUM collector is enabled.
4. Whether the RUM SampleRate or sample_rate is greater than 0.
5. Whether a View has been started or the corresponding automatic collection is enabled.
6. Whether the application waits for or calls the shutdown API before exiting.

No View or Action in the Desktop UI¶

WPF and WinForms¶

• Call EnableAutomaticInstrumentation() before the first window is created.
• Confirm that EnableWpf or EnableWinForms has not been disabled.
• Set a stable Name, title, or accessibility name for key controls.
• Dynamically created WinForms controls are scanned during Application Idle; discovery may be delayed if the message loop has no idle time for an extended period.

WinUI 3¶

WinUI 3 windows must be explicitly attached before Activate(); multi-window applications must attach each window:

window = new MainWindow().UseGuanceRum("MainWindow");
// Or GuanceSdk.AttachWinUIWindow(window, "MainWindow");
window.Activate();

Native C/C++¶

• Call guance_rum_start_view() after the window is created and guance_rum_stop_view() before the window is closed.
• Actions must be explicitly started and stopped at command, menu, or input message handling boundaries.
• The UI Watchdog requires a valid top-level HWND owned by the current process.
• The Native SDK does not install generic window or control hooks and cannot automatically discover all MFC or custom framework events.

No Log Data¶

1. Confirm that GuanceConfig.Logging is configured and EnableCustomLog = true.
2. Check SampleRate, LevelFilters, and whether messages exceed the 30 KiB UTF-8 limit.
3. System.Diagnostics.Trace output is not forwarded automatically by the SDK; explicitly call AddLog() or AddLogs() at the application's existing log sinks.
4. Read GetLogDiagnosticsSnapshot() and check the configuration, sampling, level, and capacity drop counts.

1. Call guance_log_config_init() first, then call guance_log_configure().
2. Confirm that enable_custom_log is 1, and check sample_rate and level_filter_mask.
3. The Native SDK does not intercept Console, ETW, or third-party logging libraries automatically; call guance_log_add() or guance_log_add_batch() at existing log sinks.
4. Use guance_log_get_diagnostics() to check enqueued, dropped, and retried counts 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 Headers¶

1. Confirm that EnableAutoTrace or enable_auto_trace is enabled.
2. Confirm that the sample rate is not 0, and check whether the target URL passes ShouldTrace or should_trace.
3. Check whether the propagation format required by the server matches TraceType or trace_type.
4. The trace header format depends on the selected format; do not search only for an HTTP header named trace_id.
5. Do not forward trace headers to untrusted targets.

Automatic instrumentation subscription requires AutomaticInstrumentationOptions.EnableHttpClient = true. Custom HttpClient pipelines can explicitly use GuanceSdk.CreateHttpMessageHandler().

WinHTTP requests require the guance_rum_winhttp.hpp adapter; other HTTP libraries need to call guance_trace_create_context() and write the returned header into the request.

If a request already carries a trace header with the same name, check whether the HTTP library or business code overwrote it after the SDK injected it.

Trace or Log Not Linked to RUM¶

• Enable EnableLinkRumData or enable_link_rum_data in the Trace and Log configurations respectively.
• Make requests or write Logs while an active View or Action exists; the SDK does not retroactively modify contexts that have already ended.
• Trace link 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 from WebView2¶

1. Confirm that the WebView2 Runtime is installed and the control can complete EnsureCoreWebView2Async().
2. Confirm that EnableWebView = true, or explicitly call AttachWebView().
3. For dynamically created controls, attach them explicitly after initialization completes.
4. After the control is Unloaded or Disposed, re-attach it on the new instance.
5. Register a diagnostic listener and check for WebView2 initialization failed or did not succeed.

Calling AttachWebView() repeatedly on the same control does not inject it twice. If the page itself also initializes Browser RUM, do not manually report the same page events again.

No Data from Electron¶

First confirm which Electron integration approach the application uses. The two approaches have different session and upload owners and cannot be mixed.

1. Confirm that the SDK vcpkg registry is configured and that the electron-bridge feature of guance-windows-native is enabled in the manifest; currently only dynamic x64-windows is supported.
2. In development environments, check vcpkg_installed/x64-windows/tools/guance-windows-native/; in packaged environments, check resources/native/. Both directories must contain both guance_windows_electron_bridge.exe and guance_windows_native.dll.
3. When launching the Bridge, set cwd to the directory containing the EXE and DLL, apply the full Native configuration, and check stdout for [Guance.RUM.NativeBridge] ready. Exit code 2 indicates a missing reporting endpoint or RUM Application ID; exit code 3 indicates Native Core initialization or Log configuration failure.
4. Browser RUM/Logs are initialized only in monitored Renderers; each window requires a Preload installation, trusted webContents registration, and a one-time minimal initialization. In the Renderer, fill in only the placeholder parameters required by Bridge mode; do not fill in the real Token, application ID, or reporting endpoint.
5. The Renderer DevTools Network panel should not show direct upload requests for RUM, Log, or Replay. Check whether messages arrive on the fixed IPC Channel, whether the Main Process accepts trusted Renderers, and whether Native Host stdin is writable.
6. Check the Native Host's RUM, Log, and Replay enqueued counts, upload status codes, retries, and final failure counts. Wait for shutdown() to complete when the application exits to avoid losing queued data.

The Bridge cannot automatically capture Electron Main Process crashes. Renderer unresponsive and render-process-gone events need to be listened for by the Main Process and converted into trusted Bridge commands. For the complete integration approach, see Electron Monitoring.

• Browser RUM is initialized only in the Renderer; every independent Renderer page needs to be initialized.
• For file:// pages, set sessionPersistence: "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 the complete troubleshooting approach, see Web RUM Electron Access.

Duplicate Data¶

• Initialize each corresponding SDK Handle only once during application startup.
• In .NET, repeated calls to GuanceSdk.Init() asynchronously release the old client; overlapping initialization boundaries may cause duplicate collection.
• Do not manually report control interactions, HttpClient, or WinHTTP requests already covered by automatic collection.
• For WinUI 3, use only one attach approach per window.
• Electron renderers must ensure the initialization entry point runs only once.

Queue Data Remains at Exit¶

await GuanceSdk.ShutdownAsync();

guance_sdk_flush(rum);
guance_sdk_shutdown(rum);

Do not just trigger asynchronous shutdown and then terminate the process immediately. Native crash errors are recovered and enqueued at the next startup; no network upload is performed in the crashed process.

Enable Debug Mode¶

Set Debug = true or debug = 1 in test environments. In C#, GuanceSdk.AddDiagnosticListener() can 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
• A minimal set of reproducible steps

Do not submit Client Tokens, authentication headers, cookies, sensitive user information, or local absolute paths.