Guance.Windows 0.1.0-alpha.9

Guance Windows SDK

Introduction

Guance Windows SDK provides real user monitoring, logging, HTTP trace correlation, and experimental Session Replay for Windows desktop applications. It supports managed .NET applications, native C/C++ applications, WebView2, and Electron integrations.

Compatibility

Application architecture, native import library, and DLL architecture must match. Session Replay is disabled by default and remains experimental.

Optional Session Replay installation

Keep the existing GuanceConfig.SessionReplay settings and recording calls. To enable recording, install the matching optional component as well as the base SDK:

The base SDK continues to work if Replay is configured but its component is absent; the existing diagnostics channel reports the missing component. The optional component must match the base SDK version and architecture. Installing it does not enable Replay unless the application enables Replay in its existing configuration. Electron can also use --replay-archive <path> with a matching .sha256 sidecar for an offline installation.

Installation

Choose the package for the application technology stack. Pin a version validated by your application and follow the Windows SDK Quick Start for registry and initialization steps.

Electron integration modes

Both Electron modes install the npm adapter. Full Mode downloads and starts its Native runtime; Mixed Mode connects to an SDK handle owned by the C/C++ application.

Keep the RUM application ID and intake credentials in the trusted Main/Native layer, not in the Renderer. See the Electron examples below for current initialization, preload, packaging, and lifecycle details.

Sampling configuration

New sampling properties use float percentages in the inclusive range 0 through 100; decimals such as 0.1 mean 0.1%. The former SampleRate properties remain available for source compatibility, are deprecated, and continue to use fractions from 0 through 1.

When both forms are assigned on one configuration object, the percentage property wins, including an explicit 0. Invalid percentage values (NaN, infinity, or values outside 0 through 100) are rejected instead of falling back to the legacy value. Internal sampling and wire fields remain fractions; the SDK performs the percentage conversion once.

var config = new GuanceConfig
{
    RumAppId = "your-rum-application-id",
    SessionSamplingRate = 20.5f,
    SessionOnErrorSamplingRate = 100f,
    Logging = new LogConfig { SamplingRate = 50f },
    Trace = new TraceConfig { SamplingRate = 10f },
    SessionReplay = new RumSessionReplayConfig
    {
        SamplingRate = 5f,
        OnErrorSamplingRate = 100f,
    },
};

Native applications use the ABI-safe v2 structures and entry points. The original structures and functions retain their 0-through-1 fields and ABI.

guance_sdk_config_v2 config;
guance_sdk_config_v2_init(&config);
config.rum_app_id = "your-rum-application-id";
config.datakit_url = "http://127.0.0.1:9529";
config.session_sampling_rate = 20.5f;

guance_sdk_handle sdk = guance_sdk_init_v2(&config);

guance_log_config_v2 logging;
guance_log_config_v2_init(&logging);
logging.enable_custom_log = 1;
logging.sampling_rate = 50.0f;
guance_log_configure_v2(sdk, &logging);

Electron Full Mode accepts the percentage settings sessionSamplingRate, logSamplingRate, traceSamplingRate, and sessionReplaySamplingRate. The npm adapter's corresponding *SampleRate settings remain supported with their previous fractional units. Legacy sample-app environment and JSON aliases keep their historical percentage-and-clamping behavior during migration.

Official documentation

• Quick Start: choose a package and complete the first verified upload.
• Windows Application Integration: supported capabilities and integration entry points.
• RUM Configuration: sampling, collection boundaries, and Session Replay.
• Troubleshooting: configuration validation, loading, reporting, and lifecycle issues.

Examples

• .NET WPF
• .NET WinForms
• .NET WinUI 3
• Native C console
• Electron sample
• Electron Full Mode acceptance fixture
• Electron Mixed Mode acceptance fixture

License

Licensed under the Apache License 2.0.