SDK Initialization¶
The C# and Native C/C++ initialization parameters of the Windows SDK use the same data semantics. C# creates a client through GuanceConfig; Native creates an opaque handle through guance_sdk_config_v2.
Application Configuration¶
guance_sdk_config_v2 config; // Supported since vcpkg 0.1.0-alpha.9
guance_sdk_config_v2_init(&config);
config.dataway_url = "https://openway.guance.com";
config.client_token = "<client-token>";
config.rum_app_id = "<rum-app-id>";
config.service_name = "native-client";
config.env = "prod";
config.application_version = "1.0.0";
guance_sdk_handle rum = guance_sdk_init_v2(&config);
if (rum == nullptr) {
// Initialization failed.
}
The Native structure must first call guance_sdk_config_v2_init() so that fields not explicitly set use the current version defaults. The legacy guance_sdk_config and guance_sdk_init() retain ABI compatibility, but the sampling fields still use the old 0.0–1.0 unit.
Basic Configuration¶
| Semantics | .NET / C# | Native C/C++ | Default | Required |
|---|---|---|---|---|
| Public DataWay address | DatawayUrl |
dataway_url |
Empty | Conditionally required |
| Local deployment address | DatakitUrl |
datakit_url |
Empty | Conditionally required |
| Client Token | ClientToken |
client_token |
Empty | Required when using DataWay |
| RUM Application ID | RumAppId |
rum_app_id |
Empty | Yes |
| Service name | ServiceName |
service_name |
df_rum_windows / df_rum_windows_native |
Yes |
| Environment | Env |
env |
prod |
Yes |
| Application version | Version |
application_version |
1.0.0 |
Yes |
| Debug diagnostics | Output automatically in Debug builds (no configuration item) | debug |
— / 0 |
No; outputs SDK diagnostics locally only, not reported through the Logging Intake |
C# Env supports prod, gray, pre, common, and local. Each configuration must set at least one report endpoint.
File Cache and Data Transfer¶
| Semantics | .NET / C# | Native C/C++ | Default |
|---|---|---|---|
| Total disk cache limit | Cache.MaxDiskBytes |
max_cache_bytes |
128 MiB |
| Maximum cache file count | Cache.MaxFiles |
max_cache_files |
1024 |
| Maximum retention time for cached batches | Cache.MaxAge |
max_cache_age_seconds |
7 days |
| Items per batch | Cache.MaxBatchItems |
max_batch_items |
50 |
| Uncompressed bytes per batch | Cache.MaxBatchBytes |
max_batch_bytes |
512 KiB |
| HTTP timeout | HttpTimeout |
http_timeout_ms |
10 seconds |
| Cache location | CacheDirectory |
cache_path |
SDK default directory |
| Proxy | Custom HttpMessageHandlerFactory |
proxy_url |
Empty |
| Periodic flush | FlushInterval |
flush_interval_ms |
15 seconds by default for both .NET and Native |
| Intake compression | CompressIntakeRequests |
compress_intake_requests |
.NET defaults to true; Native defaults to 1 (enabled) |
| Reclaim target watermark | Cache.LowWatermarkRatio |
— | 0.9 |
| RUM cache soft quota | Cache.RumShare |
— | 0.25 |
| Log cache soft quota | Cache.LogShare |
— | 0.15 |
| Replay cache soft quota | Cache.SessionReplayShare |
— | 0.60 |
| Aggregate upload byte rate | Upload.MaxBytesPerSecond |
max_upload_bytes_per_second |
256 KiB/s; 0 means no limit |
| Upload burst bytes | Upload.BurstBytes |
upload_burst_bytes |
2 MiB |
| Aggregate upload request rate | Upload.MaxRequestsPerSecond |
max_upload_requests_per_second |
2 requests/s; 0 means no limit |
| Upload batches per cycle | Upload.MaxBatchesPerCycle |
max_upload_batches_per_cycle |
4 |
| Concurrent upload requests | Upload.MaxConcurrentRequests |
— | 1; currently only 1 is supported |
| RUM upload weight | Upload.RumWeight |
— | 4 |
| Log upload weight | Upload.LogWeight |
— | 2 |
| Replay upload weight | Upload.SessionReplayWeight |
— | 1 |
The total disk cache limit is shared by RUM, Log, and Session Replay. These three data types use independent batch and upload counters, but queue entry or byte limits are no longer configured separately. Soft quotas allow borrowing idle space from other data types; when reclaiming, data that exceeds its soft quota is handled first. Upload rate limits are calculated aggregately across data types.
Native must use guance_sdk_config_v2_init() to obtain the default values for flush_interval_ms and compress_intake_requests. Periodic flush packages and schedules uploads for RUM and Log batches that have not reached the item or byte limit; if flush_interval_ms is less than or equal to 0, it falls back to 15000 milliseconds. .NET and Native compress the RUM and Log Intake request body with zlib-wrapped Deflate by default and set Content-Encoding: deflate. Set CompressIntakeRequests = false in C# or compress_intake_requests = 0 in Native to disable compression; the batch byte limit in the table is always calculated based on the uncompressed size.
Extended Configuration¶
| .NET / C# parameter | Default | Description |
|---|---|---|
HttpMessageHandlerFactory |
null |
Custom upload HTTP handler; can be used to configure a proxy. |
HttpResourceTimingProvider |
null |
Provides real network phase timings; see RUM Configuration. |
DiagnosticListener |
null |
Receives local diagnostic events; independent of the build configuration. |
DataModifier |
null |
Modifies individual fields; see Privacy Configuration. |
LineDataModifier |
null |
Modifies an entire record; see Privacy Configuration. |
Trace |
new TraceConfig() |
Trace Configuration. |
Logging |
new LogConfig() |
Log Configuration. |
Privacy |
new RumPrivacyConfig() |
Privacy Configuration. |
SessionReplay |
new RumSessionReplayConfig() |
Session Replay Configuration. |
Cache |
new CacheOptions() |
File cache parameters; see the table above. |
Upload |
new UploadOptions() |
Upload scheduling parameters; see the table above. |
Local Deployment (DataKit)¶
Configuration Lifecycle¶
- C#
GuanceConfigis held by the SDK for the lifetime of theGuanceClient; do not callGuanceSdk.Init()repeatedly to switch configurations. - Native copies the strings in
guance_sdk_config_v2during initialization. Afterguance_sdk_init_v2()returns, the original strings can be released. - Callback configurations such as Native Trace/resource filtering retain function pointers and
user_data; refer to the corresponding configuration page for the specific lifecycle. - Both C# and Native should create only one active client per application process to avoid duplicate collection.
Diagnostics¶
The C# SDK does not provide a runtime Debug switch. When the application is built as Debug or a debugger is attached, the SDK outputs its queue, transport, and automatic collection diagnostics to the current process's Console and debug output; optimized Release runs do not output them automatically. Diagnostic information is for local troubleshooting only and is not written or reported as custom Logs.
Register a diagnostic listener during initialization:
```csharp
DiagnosticListener = item =>
Console.WriteLine($"{item.Level} {item.Source}: {item.Message}")
```
DiagnosticListener is independent of the build configuration; even in Release builds, you can receive diagnostic events through the listener and write them to your application's logging system.
Read a snapshot:
```csharp
var snapshot = GuanceSdk.GetDiagnosticsSnapshot();
Console.WriteLine(
$"queued={snapshot.RumEventsEnqueued}, " +
$"uploaded={snapshot.RumUploadSuccessCount}, " +
$"retries={snapshot.RumUploadRetryCount}");
```
guance_sdk_diagnostics diagnostics{};
if (guance_sdk_get_diagnostics(rum, &diagnostics)) {
printf("queued=%lld uploaded=%lld retries=%lld status=%lld error=%lld\n",
static_cast<long long>(diagnostics.rum_events_enqueued),
static_cast<long long>(diagnostics.rum_upload_success_count),
static_cast<long long>(diagnostics.rum_upload_retry_count),
static_cast<long long>(diagnostics.last_rum_upload_status_code),
static_cast<long long>(diagnostics.last_rum_upload_error_code));
}
Diagnostic information must not include the Client Token, authentication headers, or user-sensitive data.
Runtime Capabilities¶
After shutdown, do not continue using the client or Native handle. A normal shutdown processes the RUM and Log queues.