Windows Application Integration¶
The Windows SDK provides unified RUM, Log, and HTTP Trace correlation capabilities for .NET/C# and Native C/C++. Applications select an integration method based on the runtime, and data enters the console with the same application ID, service, and environment dimensions.
Reading Guide¶
- First-time integration: first choose an integration method; for manual integration, see Quick Start.
- Full integration: continue reading this document.
- Parameter details: see SDK Initialization, RUM Configuration, Log Configuration, and Trace Configuration.
- Advanced capabilities: see the dedicated pages under the "Advanced Scenarios" group.
- Troubleshooting: see Troubleshooting.
Prerequisites¶
Supported Scope¶
| Item | Supported scope |
|---|---|
| Operating system | Windows 10+ |
| .NET target frameworks | net6.0 / net8.0 |
| Native standards | C11 ABI, C++17 adapter |
| NuGet Native RIDs | win-x64 / win-x86 / win-arm64 |
| vcpkg Native | Dynamic x64-windows, non-UWP |
| Distribution | NuGet / vcpkg |
| Data reporting | Public DataWay, local environment deployment (DataKit) |
| RUM | View, Action, Resource, Error, Long Task |
| Log | Custom/batch Log, independent queue, RUM correlation; C# supports collection via System.Diagnostics.Trace |
| Trace | HTTP Header propagation and RUM Resource correlation; does not upload standalone APM spans |
| Session Replay | Disabled by default; requires installation of a matching optional component and explicit enablement; supports WPF, WinForms, WinUI 3, WebView2, Electron, and Native; currently an experimental capability |
Feature Boundaries
Session Replay can be explicitly enabled and verified, but it remains an experimental capability and is not part of a stable compatibility commitment. Avalonia, .NET MAUI, and UWP do not have dedicated automatic collection adapters; frameworks that can reuse the Native C ABI must manage window and control lifecycles themselves.
Application Integration¶
Choose an SDK and Runtime¶
| SDK and runtime | Applicable applications | Installation method | UI boundary |
|---|---|---|---|
| .NET / C# | WPF, WinForms, WinUI 3 | Guance.Windows NuGet |
Automatic collection by the framework; WinUI 3 requires explicit Window association |
| Native C/C++ | Win32, desktop frameworks based on HWND |
CMake, header files, import libraries, guance_windows_native.dll |
Explicit C ABI calls for window and control lifecycles |
| WebView2 | Edge WebView2 in a .NET host | Included with the .NET SDK | Automatic discovery or explicit control association |
| Electron | Electron Renderer + Windows Native Bridge | Browser SDK + guance-windows-native[electron-bridge] |
The Browser SDK only collects and serializes; the trusted Main Process and native side manage sessions, queues, and uploads |
Create an Application¶
Log in to the Guance console, go to RUM, and click Create Application:
- Enter the application name and application ID.
- Select Custom as the application type.
- Save the application ID for use in
RumAppIdorrum_app_id.
C#, C++, WebView2, and Electron in the same Windows product can use the same application ID, and you can then distinguish data by service, version, and runtime tags.
Choose an Integration Method¶
On the application configuration page, select Agent Auto-Integration or Manual Integration, and then complete Integration Configuration. For an existing application, go directly to the configuration page to continue integration.
| Integration method | Use cases | Entry point |
|---|---|---|
| Agent Auto-Integration | Want a coding assistant to analyze the project and complete SDK integration | Copy the prompt generated by the console and hand it to the coding assistant for execution in the application code repository |
| Manual Integration | Want to install the SDK and configure parameters yourself | Confirm the data reporting method, then complete configuration according to this document and Quick Start |
Agent Auto-Integration¶
- On the current application's configuration page, select Agent Auto-Integration.
- Copy the complete prompt from Integration Configuration, and ensure that it uses the current application's integration information.
- Open the coding assistant in the application code repository, paste the prompt, and let the Agent analyze the project and complete the SDK configuration according to the integration guide.
- Build and run the application, trigger operations such as page views, and confirm in the current application's Explorer that data is received.
If the page indicates that the Personal API Key or temporary authorization code is not ready, follow the prompts to complete it, and then copy the prompt again.
Manual Integration¶
On the application configuration page, select Manual Integration, and confirm the data reporting method:
- Public DataWay: Obtain the reporting URL and Client Token from the current application's integration configuration; you do not need to deploy DataKit yourself.
- Local deployment: Use a deployed DataKit to receive data, and make sure that the application can access its reporting URL.
Complete SDK installation, initialization, and verification by following Installation and Quick Start below. If an SDK configuration already exists, review and reuse it first to avoid duplicate initialization.
Installation¶
When using Session Replay, add Guance.Windows.SessionReplay at the same version. For installation and migration requirements, see Optional Component Installation.
Samples:
We recommend installing guance-windows-native through the SDK vcpkg registry. For the registry, manifest, and CMake configuration, follow Quick Start. After installation, link the public CMake target:
find_package(GuanceWindowsNative CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE Guance::WindowsNative)
If you need to debug the SDK source code, you can also build it directly:
git clone https://github.com/GuanceCloud/datakit-windows-desktop.git
cd datakit-windows-desktop
cmake -S src/Guance.Windows.Native -B build/native -A x64
cmake --build build/native --config Release
Public header files:
guance_rum.h: C11 ABI, usable from both C and C++;guance_sdk.hpp: C++ scoped Resource andstd::terminateadapter;guance_rum_winhttp.hpp: synchronous and asynchronous WinHTTP Resource/Trace adapters.
The architecture of the application, import libraries, and DLLs must match. The current vcpkg port provides only dynamic x64-windows; the x86, x64, and ARM64 Native DLLs in the NuGet package are for the .NET wrapper layer and do not include C/C++ headers or import libraries. Session Replay is installed through the replay feature of the same port.
Install the Main Process Adapter and Renderer Browser SDK:
In Electron full mode, the npm Adapter downloads the base runtime and manages the Bridge EXE. When using Replay, you also need to explicitly install the Replay supplementary archive of the same version and architecture, and package it with the base runtime outside the ASAR.
In hybrid mode initialized by C++, the host starts a named-pipe Bridge Server, and the Electron Adapter connects to an existing SDK Handle; the Replay component is provided by the host's vcpkg replay feature. For complete installation, packaging, and capability boundaries, see Electron Monitoring.
Source Code: Windows SDK source code
Initialization¶
Reporting Methods¶
| Runtime | URL | Credentials |
|---|---|---|
| .NET / C# | GuanceConfig.DatawayUrl |
GuanceConfig.ClientToken |
| Native C/C++ | guance_sdk_config.dataway_url |
guance_sdk_config.client_token |
| Runtime | URL | Credentials |
|---|---|---|
| .NET / C# | GuanceConfig.DatakitUrl |
No Client Token required |
| Native C/C++ | guance_sdk_config.datakit_url |
No Client Token required |
Before using local environment deployment, install DataKit and enable the RUM collector.
Initialization Order¶
guance_sdk_handle rum = guance_sdk_init(&config);
guance_rum_start_view(rum, "MainWindow");
// Execute after the message loop ends.
guance_rum_stop_view(rum);
guance_sdk_shutdown(rum);
If you need Log or Trace, after guance_sdk_init() succeeds, call guance_log_configure() and guance_trace_configure() respectively.
The SDK uses an on-disk queue to buffer RUM and Log data. Complete the shutdown process on normal exit to avoid operations that have not been persisted when the process terminates.
Detailed Configuration¶
- Base URL, identity, queue, and lifecycle: SDK Initialization
- View, Action, Resource, Error, Long Task: RUM Configuration
- Custom logs and automatic Trace output: Log Configuration
- HTTP Trace Header and RUM correlation: Trace Configuration
Advanced Scenarios¶
- WPF, WinForms, WinUI 3, and Native UI: Desktop UI Frameworks
- WebView2 page monitoring: WebView2 Monitoring
- Electron Renderer and Native Bridge: Electron Monitoring
- Privacy, permissions, and data masking: Privacy and Permissions
FAQ¶
For issues with initialization, data reporting, desktop UI, WebView2, Electron, Log, Trace, and Session Replay, see Troubleshooting.