Windows Application Data Collection¶
The Windows documentation covers three data capabilities: RUM, Log, and HTTP Trace. .NET/C#, Native C/C++, WebView2, and the Electron native Bridge share the same Windows SDK product identity. In the Electron Renderer, Browser RUM is only responsible for collection and serialization; trusted fields and Session are managed uniformly by the Main Process adapter layer and the Windows Native Core, and queueing and uploading are handled by the Native Core.
Data Types¶
| Data Domain | Purpose | Reporting Behavior |
|---|---|---|
| RUM | Records Session, View, Action, Resource, Error, and Long Task | Written to the RUM queue and reported to the RUM Intake |
| Log | Records application logs and can associate the current RUM context | Written to a separate Log queue and reported to the Logging Intake |
| HTTP Trace | Injects Trace Headers into outbound requests and can associate the corresponding RUM Resource | Does not independently report APM Spans |
Global Attributes¶
| Field | Type | Description |
|---|---|---|
app_id |
string | The application ID created in the console. |
service |
string | GuanceConfig.ServiceName for .NET, guance_sdk_config.service_name for Native, or Electron native configuration. |
env |
string | prod, gray, pre, common, or local. |
version |
string | Application version. |
sdk_name |
string | Fixed to df_windows_rum_sdk for Windows .NET, Native Core, WebView2, and the Electron native Bridge. |
sdk_version |
string | The version of the current host Windows SDK assembly or Native Core; WebView2 and Electron data inherit this identity. |
sdk_pkg_info |
string | A JSON string automatically generated by the SDK that records the applicable Browser SDK and Electron Adapter package versions. For details, see the description below. |
application_uuid |
string | The current application installation instance identifier. |
session_id |
string | The current user Session identifier. |
session_type |
string | Fixed to user in the Windows SDK. |
session_has_replay |
boolean | Whether the current Session has produced uploadable Replay data. |
session_sample_rate |
number | The current sampling rate for regular Sessions. |
session_on_error_sample_rate |
number | The additional sampling rate for Error Sessions. |
view_id |
string | The current active View identifier. |
action_id |
string | The current active Action identifier; written when present. |
userid |
string | An anonymous user identifier persisted by RUM application ID, or the user ID set via the user API. |
user_name, user_email |
string | Written after the user API is called. |
is_signin |
string | T when a user is set, otherwise F. |
os, os_version |
string | Windows name and version. |
os_version_major |
string | Windows major version. |
device, model |
string | Windows device and model information; written when available. |
arch |
string | The architecture of the device running the process. |
screen_size |
string | The primary monitor size, recorded when available. |
locale |
string | The current locale. |
network_type |
string | wifi, ethernet, mobile, none, or unknown. |
Custom context only adds fields that do not already exist and cannot override SDK reserved fields.
SDK Component Versions¶
sdk_pkg_info is supported starting from NuGet / Native SDK 0.1.0-alpha.11. Electron integration also requires @cloudcare/electron-native-adapter 0.1.0-alpha.6 or later. Full Mode and Mixed Mode follow the same rules, and no manual configuration of this field is required.
web: The Browser SDK version provided by the current Browser RUM or Browser Log event.electron: The installed@cloudcare/electron-native-adapternpm package version.
The following uses Browser SDK 3.3.6 and Electron Adapter 0.1.0-alpha.6 as examples; the table shows the content of the JSON string:
| Data Source | sdk_pkg_info Example |
|---|---|
| Browser RUM in .NET WebView2 | {"web":"3.3.6"} |
| Electron host RUM / Log after Adapter connection | {"electron":"0.1.0-alpha.6"} |
| Electron Browser RUM / Log, Full Mode or Mixed Mode | {"electron":"0.1.0-alpha.6","web":"3.3.6"} |
| .NET / Native data without a Browser version and without an Electron Adapter connected | Field not written |
When a Browser event lacks a version, web is omitted; when the Electron Adapter is connected, electron is retained. The field does not contain agent, native, or replay. sdk_name and sdk_version continue to identify the host Windows SDK, and Browser and Adapter versions are recorded only as component information.
The field is generated by the host SDK based on the actual component versions and does not directly use the sdk_pkg_info passed in from the page. The Browser RUM Bridge in WebView2 can also be used when Replay is not enabled or the optional Replay component is not installed.
Attributes of Other Data Types¶
A Session is a user visit process aggregated by the console from events under the same session_id. No separate Session API call is required.
| Type | Description | Typical Sources |
|---|---|---|
| View | The visible period and performance of a window or business page | Window/Form lifecycle, explicit WinUI 3 associations, Native window events, WebView2 navigation |
| Action | User operations and their duration | Clicks, menus, selections, switches, input, keyboard shortcuts, or manual Actions |
| Resource | Network requests, status, and duration | HttpClient, WinHTTP, WebView2 Fetch/XHR/Resource, or manual Resources |
| Error | Application and page errors | Unhandled .NET exceptions, Native crash recovery, WebView2 JavaScript Errors, or manual Errors |
| Long Task | Long UI main thread blocking | Windows UI thread detection or manual Long Tasks |
View¶
| Field | Type | Description |
|---|---|---|
view_id |
string | The unique identifier of the View. |
view_name |
string | The window, page, or business View name. |
view_referrer |
string | The previous View name. |
time_spent |
integer | The View duration, in nanoseconds. |
is_active |
boolean | Whether the View is still active when reported. |
view_action_count |
integer | The number of Actions generated in the View. |
view_resource_count |
integer | The number of Resources generated in the View. |
view_error_count |
integer | The number of Errors generated in the View. |
view_long_task_count |
integer | The number of Long Tasks generated in the View. |
view_update_time |
integer | The Unix nanosecond timestamp of this View update. |
Action¶
| Field | Type | Description |
|---|---|---|
action_id |
string | The unique identifier of the Action. |
action_name |
string | The control, command, or business action name. |
action_type |
string | For example, click, key, launch_cold, or launch_hot. |
duration |
integer | The Action duration, in nanoseconds. |
action_resource_count |
integer | The number of Resources within the Action scope. |
action_error_count |
integer | The number of Errors within the Action scope. |
action_long_task_count |
integer | The number of Long Tasks within the Action scope. |
app_pre_application_init_time |
integer | In launch Actions, the time spent before application code runs. |
app_application_init_time |
integer | In launch Actions, the time spent in the application initialization phase. |
app_first_frame_init_time |
integer | In launch Actions, the time spent in the first frame phase. |
Resource¶
| Field | Type | Description |
|---|---|---|
resource_id |
string | The unique identifier of the Resource. |
resource_url |
string | The request URL after privacy policy processing. |
resource_url_host |
string | The request host name. |
resource_url_path |
string | The request path. |
resource_url_path_group |
string | The normalized path group. |
resource_method |
string | The HTTP method. |
resource_status |
integer | The HTTP status code; no valid status is written when no response is received. |
resource_status_group |
string | The status code group, for example, 2xx. |
resource_type |
string | http, native, or an application-provided resource type. |
duration |
integer | The total Resource duration, in nanoseconds. |
resource_size |
integer | The response body size in bytes; written when available. |
resource_request_size |
integer | The request body size in bytes; written when available. |
resource_dns, resource_tcp, resource_ssl, resource_ttfb |
integer | Network phase timings written when reliably available, in nanoseconds. |
resource_http_protocol |
string | The HTTP protocol version. |
trace_id, span_id |
string | Written when Trace-to-RUM correlation is enabled. |
request_header, response_header |
string | Header snapshots written only when allowed by privacy configuration. |
network_instrumentation, network_library |
string | The automatic collection entry and the identified network library. |
Phase timings are also marked with source and precision via resource_timing_source, resource_timing_precision, resource_timing_duration, resource_timing_phase, and resource_ttfb_estimated. When no reliable phase data is available, the SDK records only the total duration.
Error¶
| Field | Type | Description |
|---|---|---|
error_type |
string | Automatic collection uses the standard types in the table below; manual Errors use the type passed in by the application. |
error_source |
string | logger for crashes and application exceptions, network for network errors, and webview for WebView2 page errors. |
error_situation |
string | run indicates during runtime; Native crashes recovered at the next startup are startup. |
error_message |
string | The error summary; crashes include diagnostic information such as the exception type, exception code, or address. |
error_stack |
string | The full exception or call stack; at least the instruction address is recorded when a full Native call stack cannot be obtained. |
Automatic Collection Types¶
| Scenario | error_type |
error_source |
Description |
|---|---|---|---|
| An unhandled .NET exception terminates the process | windows_crash |
logger |
error_message contains the full exception type and message, and error_stack contains Exception.ToString(). |
Unhandled SEH or C++ std::terminate |
native_crash |
logger |
Crash information is safely persisted to disk and recovered at the next startup; the exception code, address, or std::terminate information is written to error_message. |
| The Native UI Watchdog detects an unresponsive application | anr_error |
logger |
Reported after the application becomes responsive again; the duration is written to error_message. |
HttpClient request exception, or an automatic Resource returns HTTP 4xx/5xx |
network_error |
network |
The Error is associated with the corresponding Resource and carries its URL, method, and status information. |
| WebView2 JavaScript Error | JavaScript Error.name, or JavaScriptError when missing |
webview |
error_message and error_stack come from the page exception. |
| WebView2 unhandled Promise rejection | The name of the rejection, or UnhandledPromiseRejection when missing |
webview |
error_message and error_stack come from the rejection reason. |
| WebView2 navigation failure | WebView2NavigationError |
webview |
error_message contains the navigation failure status. |
| WebView2 process failure | WebView2ProcessFailed |
webview |
error_message contains the process failure type or reason. |
Unobserved Task exceptions and UI thread exceptions that WinForms catches and allows the application to continue running are not crashes; error_type uses the corresponding .NET exception type and error_source is logger. Exception classification and diagnostic details are consistently reflected in error_type, error_message, and error_stack.
Long Task¶
| Field | Type | Description |
|---|---|---|
duration |
integer | The Long Task duration, in nanoseconds. |
long_task_stack |
string | The call stack recorded when available. |
long_task_source |
string | The automatic or manual collection source. |
long_task_delay |
integer | The blocking delay detected by the UI thread. |
long_task_threshold |
integer | The effective Long Task threshold. |
long_task_cooldown |
integer | The cooldown period for consecutive blocking reports. |
long_task_suppressed_count |
integer | The number of duplicate reports merged during the cooldown period. |
RUM Capability Matrix¶
| Integration Method | View | Action | Resource | Error | Long Task |
|---|---|---|---|---|---|
| WPF | Automatic | Automatic | HttpClient |
Unhandled exceptions | UI thread monitoring |
| WinForms | Automatic | Automatic | HttpClient |
Unhandled exceptions | UI thread monitoring |
| WinUI 3 | Automatic after window association | Automatic | HttpClient |
Unhandled exceptions | UI thread monitoring |
| Native C/C++ | Explicit integration via window events | Explicit integration via messages or commands | WinHTTP adapter or manual API | Crash recovery or manual API | HWND Watchdog or manual API |
| WebView2 | Page navigation | Page interaction | Fetch/XHR/Resource | JavaScript Error | Renderer Long Tasks not collected |
| Electron Native Bridge | Browser RUM | Browser RUM | Browser RUM | Browser RUM + Main Process events | Browser RUM; unresponsive Renderer reported by the Main Process |
The Native SDK does not install process-level Detour Hooks. The application must explicitly pass in HWND, WinHTTP Handles, or business lifecycle events. For integration methods, see Desktop UI Frameworks and RUM Manual Instrumentation.
Log Capability Matrix¶
| Integration Method | Custom Log | Batch Log | Automatic Log Sources | RUM Correlation |
|---|---|---|---|---|
| .NET / C# | GuanceSdk.AddLog() |
GuanceSdk.AddLogs() |
Can collect System.Diagnostics.Trace |
Configurable |
| Native C/C++ | guance_log_add() |
guance_log_add_batch() |
Console, ETW, or third-party log libraries are not currently intercepted | Configurable |
| WebView2 | Written by the Windows host | Written by the Windows host | Page Console is not automatically bridged | Uses the host's current RUM context |
| Electron Native Bridge | Browser Logs API | Converted by the Browser Logs Adapter | Console, page errors, or custom scopes configured by Browser Logs | Uses the Native Session, View, and Action context |
Log uses an independent queue. When RUM correlation is enabled, session_id, view_id, and action_id at the time the log is written are reported with the Log; logs already queued are not modified by subsequent context changes.
The core fields of a Log are message and status. service, env, version, SDK, application, device, and user fields are also included; after RUM correlation is enabled, session_id, view_id, action_id, and their corresponding names are included. GlobalContext, user extended attributes, and event-level Properties are written as custom tags but cannot override SDK reserved fields.
Trace Capability Matrix¶
| Integration Method | Automatic Boundaries | Manual Context | RUM Resource Correlation | Standalone Span Reporting |
|---|---|---|---|---|
| .NET / C# | HttpClient diagnostic subscription or RumHttpMessageHandler |
ContextProvider |
Configurable | Not supported |
| Native C/C++ | guance_rum_winhttp.hpp |
guance_trace_create_context() or callback |
Configurable | Not supported |
| WebView2 | Page requests are handled on the WebView2/Browser side | Managed by the page SDK | Page Resources bridged | Windows SDK does not upload |
| Electron Native Bridge | Browser RUM SDK | Browser RUM SDK | Resources written to the Native RUM queue via Bridge | Not supported |
HTTP Trace generates or passes through request Headers and can write trace_id and span_id to the corresponding RUM Resource. For complete APM Spans, the application still needs to use a separate APM Tracer. For the specific format and target filtering, see Trace Configuration.
Data Correlation¶
- The five types of RUM data share the current
session_id. - Action, Resource, Error, and Long Task are associated with the current
view_id. - Resources, Errors, and Long Tasks generated within a scoped Action are associated with the corresponding
action_id. - When a new View starts, the previous active View ends.
- User information updates affect only subsequent data and do not modify historical data.
- Whether Log and HTTP Trace are correlated with RUM is controlled by their respective
EnableLinkRumDataorenable_link_rum_data.
Resource Timing¶
Automatic HttpClient Resources record total duration by default and mark timing precision. DNS, TCP, TLS, and TTFB phases can be supplemented via HttpResourceTimingProvider or RumResourceTiming.FromPhases().
The Native WinHTTP adapter records request start, end, status, byte counts, and Trace correlation information. When the application has no reliable phase timings, these fields should not be estimated or fabricated.
Data Privacy¶
For how Resource URL query parameters, HTTP Headers, Trace targets, and Log attributes are handled, see Privacy and Permissions. User, custom context, and manual event attributes must be business-redacted by the application before being written.