Skip to content

SDK Initialization

The C# and Native C/C++ initialization parameters of the Windows SDK share the same data semantics. C# creates a client via GuanceConfig; Native creates an opaque handle via guance_sdk_config.

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 config;
guance_sdk_config_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.version = "1.0.0";

guance_sdk_handle rum = guance_sdk_init(&config);
if (rum == nullptr) {
    // Initialization failed.
}

The Native struct must call guance_sdk_config_init() first so that fields not explicitly set use the defaults for the current version.

Basic Configuration

Description .NET / C# Native C/C++ Default Required
Public DataWay address DatawayUrl dataway_url Empty Conditionally required
Local environment 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 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 Logging Intake

C# Env supports prod, gray, pre, common, and local. Each configuration must set at least one reporting address.

File Cache and Data Transmission

Description .NET / C# Native C/C++ Default
Total disk cache limit Cache.MaxDiskBytes max_cache_bytes 128 MiB
Maximum number of cache files Cache.MaxFiles max_cache_files 1024
Maximum cache batch retention time 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 true by default for .NET; 1 (enabled) by default for Native

The total disk cache limit is shared by RUM, Log, and Session Replay. The three data types use independent batches and upload counters, but queue item or byte limits are no longer configured separately. C# can control the reclamation watermark and soft quotas through Cache.LowWatermarkRatio and three *Share parameters, and configure the aggregated upload rate through Upload. Native uses the corresponding max_upload_* fields. HttpResourceTimingProvider can provide real network phase timings.

Native must obtain the default values for flush_interval_ms and compress_intake_requests through guance_sdk_config_init(). Periodic flush packages RUM and Log batches that have not reached the item or byte limit and schedules them for upload. If flush_interval_ms is less than or equal to 0, it falls back to 15000 milliseconds. Both .NET and Native use zlib-wrapped Deflate compression for RUM and Log Intake request bodies 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 limits in the table are always calculated based on the pre-compression size.

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 config;
guance_sdk_config_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(&config);

Configuration Lifecycle

  • C# GuanceConfig is held by the SDK for the lifetime of GuanceClient. Do not call GuanceSdk.Init() repeatedly to switch configurations.
  • Native copies the guance_sdk_config strings during initialization. After guance_sdk_init() returns, the original strings can be freed.
  • Native callback configurations such as Trace/resource filtering retain function pointers and user_data. Refer to the corresponding configuration pages for their specific lifetimes.
  • 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 uses a Debug build or a debugger is attached, the SDK outputs its queue, transmission, and automatic collection diagnostics to the Console and debug output of the current process. Optimized Release runs do not output them automatically. Diagnostic information is for local troubleshooting only and is never written or reported as custom Logs.

Register a diagnostic listener at initialization:

DiagnosticListener = item =>
    Console.WriteLine($"{item.Level} {item.Source}: {item.Message}")

DiagnosticListener is independent of the build configuration. Even in a Release build, you can receive diagnostic events through the listener and write them into your application's logging system yourself.

Read a snapshot:

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 output 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;

Do not continue to use the client or the Native Handle after shutdown. A normal shutdown processes the RUM and Log queues.

Feedback

Is this page helpful?