Skip to content

RUM Configuration

The Windows SDK collects the same View, Action, Resource, Error, and Long Task in C# and Native C/C++. C# provides automatic UI framework collection; Native uses an explicit C ABI and adapters for HWND and WinHTTP.

RUM Initialization Configuration

Sampling Configuration

Semantics .NET / C# Native C/C++ Default Range and Description
Regular Session sampling SessionSamplingRate (since NuGet 0.1.0-alpha.8) session_sampling_rate (since vcpkg 0.1.0-alpha.9) 100 0–100
Error Session additional sampling SessionOnErrorSamplingRate (since NuGet 0.1.0-alpha.8) session_on_error_sampling_rate (since vcpkg 0.1.0-alpha.9) 0 0–100
Regular Session sampling (legacy) SampleRate (deprecated) Legacy structure sample_rate (deprecated) 1 0–1; use SessionSamplingRate / session_sampling_rate instead.
Error Session additional sampling (legacy) SessionErrorSampleRate (deprecated) Legacy structure session_error_sample_rate (deprecated) 0 0–1; use SessionOnErrorSamplingRate / session_on_error_sampling_rate instead.

The new fields use float percentages and support decimal values such as 0.1 (representing 0.1%). The sampling decision remains consistent within the same Session. It is recommended to use 100 first to verify the integration, then adjust based on data volume.

If the same .NET configuration object sets both new and legacy fields, the new fields take precedence, including an explicit 0; an invalid new field does not fall back to the legacy field. Native uses the ABI-safe guance_sdk_config_v2 and guance_sdk_init_v2().

Collection Boundaries

Capability .NET / C# Native C/C++
View WPF and WinForms automatic; WinUI 3 requires explicit Window association Call View C ABI within the window lifecycle
Action Automatic collection for common UI controls and app launch Automatic collection for app launch; call Action C ABI for business operations
Resource Automatic collection via HttpClient WinHTTP adapter or manual Resource C ABI
Error Automatic collection for unhandled exceptions, with manual Error support Native crash recovery or manual Error
Long Task UI thread probing or manual reporting HWND Watchdog or manual reporting

Enabling Collection

GuanceSdk.EnableAutomaticInstrumentation(new AutomaticInstrumentationOptions
{
    EnableWpf = true,
    EnableWinForms = true,
    EnableWinUI = true,
    EnableWebView = true,
    EnableHttpClient = true,
    EnableUnhandledException = true,
    EnableUiThreadBlock = true,
    EnableAppLaunch = true,
    UiThreadBlockThreshold = TimeSpan.FromMilliseconds(500),
    UiThreadProbeInterval = TimeSpan.FromMilliseconds(250),
    UiThreadLongTaskCooldown = TimeSpan.FromSeconds(5)
});

Automatic Collection Parameters

Parameter Default Description
EnableWpf true Automatically collects WPF Window and common controls.
EnableWinForms true Automatically collects WinForms Form and common controls.
EnableWinUI true Enables WinUI 3 control collection; Window still requires explicit association.
EnableWebView true Automatically discovers supported WebView2 controls.
EnableHttpClient true Collects Resource through .NET HTTP diagnostic events.
EnableUnhandledException true Collects unhandled exceptions from the application domain and UI framework.
EnableUiThreadBlock true Monitors UI thread blocking.
EnableAppLaunch true Collects the application launch phase.
UiThreadBlockThreshold 500 ms Long Task threshold.
UiThreadProbeInterval 250 ms UI thread probe interval.
UiThreadLongTaskCooldown 5 s Cooldown for merging consecutive blocking reports.

Repeated calls do not re-register the same set of collectors, but the application should still call this only once during startup.

After the Native SDK is initialized, cold start and hot start are collected automatically by default, generating Actions with action_type=launch_cold and action_type=launch_hot respectively. guance_sdk_config_v2_init() initializes enable_app_launch_tracking to 1; to disable automatic launch Actions, set it to 0 before calling guance_sdk_init_v2():

guance_sdk_config_v2 config;
guance_sdk_config_v2_init(&config);
config.enable_app_launch_tracking = 0;
Field Default Description
enable_app_launch_tracking 1 Automatically collects cold start and hot start Actions; set to 0 to disable.

Automatic collection observes the top-level window of the current process and the first composed frame. A cold start Action includes three phases: before application code runs, application initialization, and the first frame. A hot start Action is generated when the application returns to the foreground from the background. The application can still use guance_rum_add_launch_action() to report launch phases measured by the host; after a cold start is reported manually, the SDK does not generate a duplicate automatic cold start Action.

After the top-level window is created, you can enable the UI Watchdog and crash recovery:

guance_sdk_native_monitoring_config monitoring;
guance_sdk_native_monitoring_config_init(&monitoring);
monitoring.enable_ui_hang_monitoring = 1;
monitoring.main_window_handle = reinterpret_cast<uintptr_t>(main_window);
monitoring.enable_native_crash_reporting = 1;
monitoring.enable_minidump = 0;

if (!guance_sdk_enable_native_monitoring(rum, &monitoring)) {
    // Invalid HWND or configuration.
}

Native Monitoring Parameters

guance_sdk_native_monitoring_config is a versioned structure; its initialization function must be called first.

Field Default Description
enable_ui_hang_monitoring 0 Whether to enable the HWND UI Watchdog.
enable_native_crash_reporting 0 Whether to enable SEH and next-launch crash recovery.
main_window_handle 0 A valid top-level HWND owned by the current process.
ui_probe_interval_ms 250 UI probe interval.
long_task_threshold_ms 500 Long Task threshold.
hang_threshold_ms 5000 Application Not Responding threshold.
hang_report_cooldown_ms 5000 Cooldown for consecutive hang reports.
crash_cache_path SDK default directory Local directory for crash envelopes and optional dumps.
enable_minidump 0 Whether to retain a local minidump; dumps are not uploaded to RUM.
max_crash_files 3 Maximum number of crash files.
max_crash_file_bytes 32 MiB Maximum total bytes for crash files.

C++ applications should include guance_sdk.hpp so that the host-side adapter installs and restores the std::terminate handler correctly. A crashed process does not perform network or queue writes; the next initialization converts the bounded crash envelope into a RUM Error.

Network Resource

With EnableHttpClient = true, URL, method, status code, total duration, request/response sizes, and HTTP protocol are recorded automatically. To provide an explicit Handler:

using var http = new HttpClient(
    GuanceSdk.CreateHttpMessageHandler(new HttpClientHandler()));

C++ WinHTTP uses a scoped adapter:

guance::rum::WinHttpResource resource(
    rum,
    request,
    "https://api.example.com/items",
    "GET");
resource.send();
resource.receive();

For other network libraries, call guance_rum_start_resource() and guance_rum_stop_resource_ext(). For Trace Header and RUM correlation, refer to Trace Configuration.

DNS, TCP, TLS, and TTFB should be recorded only when real network phase timings are available; do not estimate missing phases.

RUM Manual Instrumentation

When automatic collection cannot express business semantics, you can manually report Action, View, Error, Long Task, and Resource. .NET / C# uses GuanceSdk, and Native C/C++ uses the C ABI in guance_rum.h; both integrations produce the same Windows RUM data types.

Avoid Duplicate Collection

Manual APIs and automatic collection write to the same Session. Do not manually report data that has already been collected automatically by windows, controls, HttpClient, WinHTTP, or WebView2.

Action

Actions That End Automatically

Used to collect user operations and associate the Resource, Error, and Long Task generated during the operation:

var action = GuanceSdk.StartAction("SaveOrder", "click");
if (!action.IsAccepted)
{
    // This call was ignored by high-frequency protection.
}

In normal mode, you do not need to call StopAction; disposing the returned RumActionScope does not end the Action.

const char* action_id = guance_rum_start_action(rum, "SaveOrder", "click");
if (action_id[0] == '\0') {
    // This call was ignored by high-frequency protection.
}

Normal mode behaves the same as the Android SDK: only one active Action is kept at any time; consecutive StartAction calls within 100 ms are ignored, and a subsequent call after 100 ms ends the previous Action and starts a new one. An Action ends when the View switches and lasts at most about 5 seconds.

Actions That Wait for Business Completion

Enable needWait mode when a business operation must cover asynchronous logic. Only this mode needs to be paired with StopAction:

using (GuanceSdk.StartAction("SaveOrder", "custom", needWait: true))
{
    await SaveOrderAsync();
}

You can also save the ActionId and call GuanceSdk.StopAction(actionId) when the business operation ends.

const char* action_id = guance_rum_start_action_ext(
    rum,
    "SaveOrder",
    "custom",
    1);

save_order();

if (action_id[0] != '\0') {
    guance_rum_stop_action(rum, action_id);
}

A needWait Action is not replaced by a new Action until explicitly ended, but it is still subject to the approximately 5-second maximum duration and View switch limits. If an empty ID is returned when starting an Action, the call was not accepted; do not call StopAction.

Actions With Known Duration

GuanceSdk.AddAction(
    name: "ExportReport",
    type: "custom",
    duration: TimeSpan.FromMilliseconds(320),
    properties: new Dictionary<string, object?>
    {
        ["format"] = "csv"
    });
constexpr int64_t duration_ns = 320LL * 1000 * 1000;
guance_rum_add_action(rum, "ExportReport", "custom", duration_ns);

AddAction directly reports a standalone Action that has already ended with a known duration. It is not subject to the 100 ms high-frequency protection or the 5-second limit, and it does not associate subsequent Resource, Error, or Long Task events.

View

GuanceSdk.StartView(
    "OrderDetail",
    new Dictionary<string, object?>
    {
        ["order_type"] = "subscription"
    });

// Execute when the page ends.
GuanceSdk.StopView();
guance_rum_start_view(rum, "OrderDetail");

// Execute when the page or window ends.
guance_rum_stop_view(rum);

Starting a new View automatically ends the current active View. View names should describe a stable page and must not contain order numbers, user IDs, object addresses, or search terms.

Error

try
{
    await LoadOrdersAsync();
}
catch (Exception exception)
{
    GuanceSdk.AddError(
        exception,
        new Dictionary<string, object?>
        {
            ["operation"] = "load_orders"
        });
}

For errors that are not Exception objects, use GuanceSdk.AddError(stack, message, errorType, source). When automatic unhandled exception collection is enabled, if the same exception is thrown again after a manual report and eventually terminates the process, an additional windows_crash is generated; avoid duplicate reporting according to your business semantics.

guance_rum_add_error(
    rum,
    "OrderRepository::load_orders",
    "Order request failed",
    "NetworkError",
    "custom");

Automatic collection for .NET fatal exceptions uses error_type=windows_crash; Native SEH and C++ std::terminate use error_type=native_crash; the error_source for crashes is logger. Native crash monitoring restores crash Error events at the next launch; do not call manual Error APIs in a crash handler. For the complete type and field reference, see Application Data Collection.

Long Task

GuanceSdk.AddLongTask(
    duration: TimeSpan.FromMilliseconds(850),
    stack: "ReportRenderer.Render");
constexpr int64_t duration_ns = 850LL * 1000 * 1000;
guance_rum_add_long_task(rum, duration_ns, "ReportRenderer::render");

When UI thread blocking monitoring is enabled, do not manually report the same blocking again.

Resource

var resourceId = GuanceSdk.StartResource(
    "https://api.example.com/orders",
    "GET");

GuanceSdk.StopResource(
    resourceId,
    statusCode: 200,
    timing: RumResourceTiming.FromTotalElapsed(
        TimeSpan.FromMilliseconds(120),
        source: "manual"),
    responseSize: 2048,
    requestSize: 0,
    resourceType: "http");

If the application has already measured DNS, TCP, TLS, and TTFB, use RumResourceTiming.FromPhases() to write phase timings; when no reliable data is available, write only the total duration.

C++ applications can use ResourceScope to ensure the Resource is still completed on an exception or early return:

#include "guance_sdk.hpp"

guance::rum::ResourceScope resource(
    rum,
    "https://api.example.com/orders",
    "GET",
    "http");

const auto response = send_request();
resource.complete(
    response.status_code,
    response.body_size,
    response.request_size);

Pure C applications can pair guance_rum_start_resource() with guance_rum_stop_resource(). Use guance_rum_stop_resource_ext() when you need to write trace_id, span_id, request size, or HTTP protocol.

Even when a request fails, you must still complete the Resource and set the status code to 0. After enabling automatic Resource collection via HttpClient or WinHTTP, do not call the manual API for the same request again.

Flush

Manual events first enter a local queue. To immediately attempt reporting after a critical flow:

await GuanceSdk.FlushAsync();
guance_sdk_flush(rum);

On normal application exit, you should still call ShutdownAsync() or guance_sdk_shutdown(). For HTTP Trace propagation and application logs, refer to Trace Configuration and Log Configuration respectively.

Session Replay

Starting with NuGet 0.1.0-alpha.9 and vcpkg 0.1.0-alpha.10, the Replay implementation is provided by optional components. First add a component of the same version following Optional Component Installation, then enable the configurations below; existing configuration, control, and privacy APIs are preserved. For additional Electron runtime installation, see Electron Monitoring.

When Replay is disabled, the component is not loaded and no Replay upload channel is created. When the configuration is enabled but the component is missing, the version does not match, or loading fails, the SDK disables Replay and outputs component diagnostics, while normal RUM, Log, and Trace continue to work. Installing the component alone does not start recording. C# can read IsSessionReplayAvailable from the client returned by initialization, and Native can call guance_rum_is_session_replay_available(rum) to determine whether the component is available; availability does not mean the current Session has been sampled or recording has started.

Replay Parameters

.NET / C# (SessionReplay) Native (sdk_config_v2) Default Description
Enabled session_replay_enabled false / 0 Whether to enable recording.
SamplingRate (since NuGet 0.1.0-alpha.8) session_replay_sampling_rate (since vcpkg 0.1.0-alpha.9) 100 Replay sampling percentage for regular Sessions, 0–100, decimals supported.
OnErrorSamplingRate (since NuGet 0.1.0-alpha.8) session_replay_on_error_sampling_rate (since vcpkg 0.1.0-alpha.9) 0 Additional sampling percentage for Error Sessions, 0–100, decimals supported.
TextAndInputPrivacy — MaskAll Text and input privacy policy.
TouchPrivacy — Show Pointer and touch privacy policy.
ImagePrivacy — MaskAll Image privacy policy.
SegmentRecordLimit session_replay_segment_record_limit 500 Maximum number of records per Replay segment.
SegmentBytesLimit session_replay_segment_bytes_limit 1 MiB Maximum uncompressed bytes per segment.
FlushInterval — 5 s Flush interval for active segments.
MaxNodeCount — 2000 Maximum number of nodes per snapshot.
MaxTreeDepth — 64 Maximum UI tree depth.
MaxTextLength — 256 Maximum text length per node.
MaxAttributeValueLength — 512 Maximum length per attribute value.
CaptureImages — true When set to false, overrides the image policy and hides all images.
MaxImageBytes — 512 KiB Maximum encoded bytes per image.
MaxImageDimension — 1024 Maximum encoded image width and height.
LargeImagePrivacyThreshold — 100 Image area threshold for MaskLargeOnly.
CustomRenderedTypeNameMarkers — Built-in custom rendered type markers Identifies opaque or custom-rendered content by type name fragments.
SensitiveTextPatterns — Email, bank card number, and phone number patterns A set of regular expressions that identifies sensitive text.
SampleRate (deprecated) Legacy structure session_replay_sample_rate (deprecated) 1 Compatible with the legacy 0–1 unit; use the corresponding new sampling field instead.
OnErrorSampleRate (deprecated) Legacy structure session_replay_on_error_sample_rate (deprecated) 0 Compatible with the legacy 0–1 unit; use the corresponding new sampling field instead.
Experimental Capability

Windows Session Replay is disabled by default. It can be explicitly enabled and validated, but it is an experimental capability. Integrators must evaluate playback compatibility, privacy, performance, and data volume on their own and should not treat the current behavior as a stable compatibility commitment.

Explicitly enable Replay and set sampling and default privacy policies during initialization:

GuanceSdk.Init(new GuanceConfig
{
    // DatawayUrl / ClientToken / RumAppId ...
    SessionReplay = new RumSessionReplayConfig
    {
        Enabled = true,
        SamplingRate = 100, // Supported since NuGet 0.1.0-alpha.8
        OnErrorSamplingRate = 0, // Supported since NuGet 0.1.0-alpha.8
        TextAndInputPrivacy = SessionReplayTextAndInputPrivacy.MaskAll,
        TouchPrivacy = SessionReplayTouchPrivacy.Show,
        ImagePrivacy = SessionReplayImagePrivacy.MaskAll
    }
});

SamplingRate and OnErrorSamplingRate (supported since NuGet 0.1.0-alpha.8) are both float percentages ranging from 0 to 100. After initialization, you can manually control recording:

GuanceSdk.StartSessionReplayRecording();
GuanceSdk.StopSessionReplayRecording();

A manual start cannot bypass Enabled = false; you must enable it first in the initialization configuration. For element-level privacy APIs, refer to Windows Session Replay Privacy Override.

guance_sdk_config_v2 config;
guance_sdk_config_v2_init(&config);
config.session_replay_enabled = 1;
config.session_replay_sampling_rate = 100.0f; // Supported since vcpkg 0.1.0-alpha.9
config.session_replay_on_error_sampling_rate = 0.0f; // Supported since vcpkg 0.1.0-alpha.9

guance_sdk_handle rum = guance_sdk_init_v2(&config);
if (guance_rum_is_session_replay_available(rum)) {
    guance_rum_register_replay_window(
        rum,
        reinterpret_cast<uintptr_t>(main_window));
    guance_rum_start_session_replay(rum);
}

Native Replay uses a separate persistent queue and the v1/write/rum/replay upload channel. guance_rum_start_session_replay() and guance_rum_stop_session_replay() can manually control recording, but a start call likewise does not override the disabled initialization configuration.

Page records from WebView2 and Electron enter the same native Session, segments, queue, and upload channel through the native Bridge. Refer to WebView2 Monitoring and Electron Monitoring respectively.

Feedback

Is this page helpful?