SDK Initialization¶

The Windows SDK's C# and Native C/C++ initialization parameters 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 to ensure that fields not explicitly set use the current version's defaults.

Basic Configuration¶

C#'s Env supports prod, gray, pre, common, and local. At least one upload address must be set for the same configuration.

File Cache & Data Transfer¶

The disk cache total limit is shared by RUM, Log, and Session Replay; the three data types use independent batches and upload counts, but no longer have separate queue entry or byte limits. C# can also control reclamation thresholds and soft quotas via Cache.LowWatermarkRatio and three *Share parameters, and configure aggregated upload rate via Upload; Native uses the corresponding max_upload_* fields. HttpResourceTimingProvider can be used to provide real network phase timings.

Native must obtain the default values of flush_interval_ms and compress_intake_requests through guance_sdk_config_init(). Periodic flush packages and schedules uploads of RUM and Log batches that have not yet reached item or byte limits. 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, setting Content-Encoding: deflate. C# can set CompressIntakeRequests = false, Native can set compress_intake_requests = 0 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.
• During Native initialization, the guance_sdk_config strings are copied. The original strings can be freed after guance_sdk_init() returns.
• Native Trace/resource filtering and other callback configurations retain function pointers and user_data; the specific lifecycle is determined by the corresponding configuration page.
• Both C# and Native should only create one active client per application process to avoid duplicate collection.

Diagnostics¶

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

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));
}

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

After shutdown, the client or Native Handle must not be used anymore. A normal shutdown processes the RUM and Log queues.

Related Documentation¶

• RUM Configuration
• Log Configuration
• Trace Configuration
• Troubleshooting