Troubleshooting¶

SDK Initialization Error Validation¶

.NET / C# Configuration Validation¶

GuanceSdk.Init() immediately validates key configuration:

Native C/C++ Initialization or Loading Failure¶

1. Confirm that your application, import library, and guance_windows_native.dll use the same architecture. The current vcpkg port only provides a dynamic x64-windows build; for other architectures, use a build from source with the matching architecture.
2. Ensure 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 for the .NET wrapper layer and are not equivalent to C/C++ headers and import libraries.
3. Call guance_sdk_config_init() first, then fill in the endpoint, Token, application ID, service name, version, and environment.
4. For public DataWay, provide the endpoint and Client Token; for a local deployment (Datakit), provide an accessible Datakit endpoint.
5. If guance_sdk_init() returns a null Handle, check required fields, cache directory permissions, and process architecture.

SDK Running Normally but No Data¶

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 the correct base endpoint and Client Token.
3. Whether the local deployment (Datakit) is accessible 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 has been enabled.
6. 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));
}

When the enqueue count is 0, first check sampling, View, and collection switches; when retries keep increasing, check network, proxy, DNS, and upload endpoint; when terminal failures increase, check Token, permissions, and server-side status codes.

No View or Action in the Desktop UI¶

WPF and WinForms¶

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

WinUI 3¶

WinUI 3 windows must be explicitly associated before Activate(). For multi-window applications, associate each window individually:

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 ended 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, so it will not automatically discover all MFC or custom framework events.

No Log Data¶

Log and RUM use independent queues. RUM running normally does not mean Log is enabled, and vice versa.

Requests Do Not Have Trace Headers¶

1. Confirm that EnableAutoTrace or enable_auto_trace is enabled.
2. Confirm the sample rate is not 0, and check that 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 is determined by the selected format; do not search only for an HTTP Header named trace_id.
5. Do not propagate Trace Headers to untrusted targets.

If the request already has a Trace Header with the same name, check whether the HTTP library or business code overwrites it after the SDK injects it.

Trace or Log Not Associated with RUM¶

• Enable EnableLinkRumData or enable_link_rum_data in the Trace/Log configuration respectively.
• Initiate the request or write the Log while an active View or Action exists; the SDK does not retroactively modify contexts that have already ended.
• Trace association information is written into 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 in 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 dynamic controls, it is recommended to explicitly associate them after initialization is complete.
4. After the control is Unloaded or Disposed, reassociate 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 again. If the page itself also initializes Browser RUM, do not manually report the same page events again.

No Data in Electron¶

First determine which Electron integration method the application uses. The Session and upload owner differ between the two methods, so configurations cannot be mixed.

Duplicate Data¶

• Initialize the 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 that are already covered by automatic collection.
• For WinUI 3, use only one association method per window.
• The Electron renderer should ensure the initialization entry point is executed only once.

Queued Data Remaining on Exit¶

await GuanceSdk.ShutdownAsync();

guance_sdk_flush(rum);
guance_sdk_shutdown(rum);

Do not simply trigger an asynchronous shutdown and then immediately terminate the process. Native crash errors are recovered and enqueued on the next startup; no network upload occurs within the crashing process.

Enable Debug Logging¶

Set Debug = true or debug = 1 in a test environment. In C#, you can use GuanceSdk.AddDiagnosticListener() to record SDK-level details, source, and message. 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 reproducible steps.

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