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:
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:
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:
You can also save the ActionId and call GuanceSdk.StopAction(actionId) when the business operation ends.
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¶
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¶
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.
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¶
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:
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:
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.