Skip to content

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

GuanceSdk.Init(new GuanceConfig
{
    DatawayUrl = "https://openway.guance.com",
    ClientToken = "<client-token>",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "prod",
    Version = "1.0.0"
});
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)

GuanceSdk.Init(new GuanceConfig
{
    DatakitUrl = "http://127.0.0.1:9529",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "local",
    Version = "1.0.0"
});
guance_sdk_config_v2 config; // Supported since vcpkg 0.1.0-alpha.9
guance_sdk_config_v2_init(&config);
config.datakit_url = "http://127.0.0.1:9529";
config.rum_app_id = "<rum-app-id>";
config.service_name = "native-client";
config.env = "local";
guance_sdk_handle rum = guance_sdk_init_v2(&config);

Configuration Lifecycle

  • C# GuanceConfig is held by the SDK for the lifetime of the GuanceClient; do not call GuanceSdk.Init() repeatedly to switch configurations.
  • Native copies the strings in guance_sdk_config_v2 during initialization. After guance_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

await GuanceSdk.FlushAsync();
await GuanceSdk.ShutdownAsync();
guance_sdk_flush(rum);
guance_sdk_shutdown(rum);
rum = nullptr;

After shutdown, do not continue using the client or Native handle. A normal shutdown processes the RUM and Log queues.

Feedback

Is this page helpful?