Skip to content

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

  1. Confirm that the application, import library, and guance_windows_native.dll use the same architecture. The current vcpkg port only provides dynamic x64-windows; for other architectures, use source build artifacts built for the matching architecture.
  2. 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.
  3. Call guance_sdk_config_init() first, then populate the endpoint, Token, application ID, service name, version, and environment.
  4. Public DataWay requires an 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 the process architecture.

SDK Runs 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 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 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));
}

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 EnableWpf or EnableWinForms is 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 call guance_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 HWND owned 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

  1. Confirm that GuanceConfig.Logging is set and EnableCustomLog = true.
  2. Check SampleRate, LevelFilters, and whether messages exceed the 30 KiB UTF-8 limit.
  3. System.Diagnostics.Trace output is not automatically forwarded by the SDK. Explicitly call AddLog() or AddLogs() at the application's existing log output points.
  4. Read GetLogDiagnosticsSnapshot() and check the configuration, sampling, level, and capacity discard counts separately.
  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 automatically intercept Console, ETW, or third-party logging libraries. Call guance_log_add() or guance_log_add_batch() at your existing log output points.
  4. 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

  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 that the propagation format required by the server matches TraceType or trace_type.
  4. The trace header is determined by the selected format, so do not only search for an HTTP header named trace_id.
  5. 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 EnableLinkRumData or enable_link_rum_data in 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

  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, explicitly attach after initialization completes.
  4. After a control is Unloaded or Disposed, attach it again 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 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.

  1. In Full Mode, check the runtime downloaded by npm or the native.directory specified by the CLI; in Mixed Mode, check that the C++ host has initialized the SDK and started a Bridge Server matching native.pipeName. See Electron Monitoring for the installation steps for both modes.
  2. 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 and replay-manifest.json. In Mixed Mode, the host deploys the base and optional DLLs.
  3. In Full Mode, provide the complete Native configuration through native.settings, and check startup and component loading diagnostics. 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 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.
  5. 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.
  6. 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, 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 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, HttpClient requests, 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

  1. After upgrading .NET to NuGet 0.1.0-alpha.9, confirm that the same version of Guance.Windows.SessionReplay is installed. Use the DiagnosticListener configured during initialization to check session_replay_component, and distinguish missing package, version mismatch, and load failure.
  2. After upgrading Native to vcpkg 0.1.0-alpha.10, confirm that the replay feature 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 check session_replay_enabled.
  3. Use the client-side IsSessionReplayAvailable or guance_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.
  4. For Electron Full Mode, confirm that the supplemental components were installed and packaged with --with-replay or --replay-archive; for Mixed Mode, confirm that both the host Native SDK and the Bridge Server have Replay enabled. If WebView2/Electron getCapabilities() does not include records, 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

await GuanceSdk.ShutdownAsync();
guance_sdk_flush(rum);
guance_sdk_shutdown(rum);

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.

Feedback

Is this page helpful?