SDK 初始化¶

Windows SDK 的 C# 和 Native C/C++ 初始化参数使用相同的数据语义。C# 通过 GuanceConfig 创建客户端；Native 通过 guance_sdk_config_v2 创建不透明 Handle。

Application 配置¶

.NET / C#Native C/C++

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; // 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) {
    // 初始化失败。
}

Native 结构必须先调用 guance_sdk_config_v2_init()，确保未显式设置的字段使用当前版本默认值。旧 guance_sdk_config 与 guance_sdk_init() 保留 ABI 兼容性，但采样字段仍使用旧 0.0～1.0 单位。

基础配置¶

语义	.NET / C#	Native C/C++	默认值	必填
公网 DataWay 地址	`DatawayUrl`	`dataway_url`	空	条件必填
本地环境部署地址	`DatakitUrl`	`datakit_url`	空	条件必填
Client Token	`ClientToken`	`client_token`	空	使用 DataWay 时必填
RUM 应用 ID	`RumAppId`	`rum_app_id`	空	是
服务名	`ServiceName`	`service_name`	`df_rum_windows` / `df_rum_windows_native`	是
环境	`Env`	`env`	`prod`	是
应用版本	`Version`	`application_version`	`1.0.0`	是
调试诊断	Debug 构建自动输出（无配置项）	`debug`	— / `0`	否；仅在本地输出 SDK 诊断，不通过 Logging Intake 上报

C# 的 Env 支持 prod、gray、pre、common 和 local。同一个配置至少设置一种上报地址。

文件缓存与数据传输¶

语义	.NET / C#	Native C/C++	默认值
磁盘缓存总上限	`Cache.MaxDiskBytes`	`max_cache_bytes`	`128 MiB`
缓存文件数上限	`Cache.MaxFiles`	`max_cache_files`	`1024`
缓存批次最长保留时间	`Cache.MaxAge`	`max_cache_age_seconds`	`7` 天
单批数据条数	`Cache.MaxBatchItems`	`max_batch_items`	`50`
单批未压缩字节数	`Cache.MaxBatchBytes`	`max_batch_bytes`	`512 KiB`
HTTP 超时	`HttpTimeout`	`http_timeout_ms`	`10` 秒
缓存位置	`CacheDirectory`	`cache_path`	SDK 默认目录
代理	自定义 `HttpMessageHandlerFactory`	`proxy_url`	空
周期 Flush	`FlushInterval`	`flush_interval_ms`	.NET 与 Native 均默认 `15` 秒
Intake 压缩	`CompressIntakeRequests`	`compress_intake_requests`	.NET 默认 `true`；Native 默认 `1`（开启）
回收目标水位	`Cache.LowWatermarkRatio`	—	`0.9`
RUM 缓存软配额	`Cache.RumShare`	—	`0.25`
Log 缓存软配额	`Cache.LogShare`	—	`0.15`
Replay 缓存软配额	`Cache.SessionReplayShare`	—	`0.60`
聚合上传字节速率	`Upload.MaxBytesPerSecond`	`max_upload_bytes_per_second`	`256 KiB/s`；`0` 不限速
上传突发字节数	`Upload.BurstBytes`	`upload_burst_bytes`	`2 MiB`
聚合上传请求速率	`Upload.MaxRequestsPerSecond`	`max_upload_requests_per_second`	`2` 次/秒；`0` 不限速
每轮上传批次数	`Upload.MaxBatchesPerCycle`	`max_upload_batches_per_cycle`	`4`
并发上传请求数	`Upload.MaxConcurrentRequests`	—	`1`；当前仅支持 `1`
RUM 上传权重	`Upload.RumWeight`	—	`4`
Log 上传权重	`Upload.LogWeight`	—	`2`
Replay 上传权重	`Upload.SessionReplayWeight`	—	`1`

磁盘缓存总上限由 RUM、Log 和 Session Replay 共享；三类数据使用独立批次和上传计数，但不再分别配置队列条目或字节上限。软配额允许借用其他数据类型的空闲空间，回收时优先处理超出软配额的数据。上传速率限制在各类数据间聚合计算。

Native 必须通过 guance_sdk_config_v2_init() 取得 flush_interval_ms 和 compress_intake_requests 的默认值。周期 Flush 会把未达到条数或字节上限的 RUM、Log 批次封装并调度上传；flush_interval_ms 小于或等于 0 时回退为 15000 毫秒。.NET 与 Native 默认使用 zlib 包装的 Deflate 压缩 RUM 和 Log Intake 请求体，并设置 Content-Encoding: deflate。C# 设置 CompressIntakeRequests = false、Native 设置 compress_intake_requests = 0 可关闭压缩；表中的批次字节上限始终按压缩前大小计算。

扩展配置¶

.NET / C# 参数	默认值	说明
`HttpMessageHandlerFactory`	`null`	自定义上传 HTTP Handler，可用于设置代理。
`HttpResourceTimingProvider`	`null`	提供真实网络阶段耗时，参见 RUM 配置。
`DiagnosticListener`	`null`	接收本地诊断事件，与构建配置无关。
`DataModifier`	`null`	修改单个字段，参见隐私配置。
`LineDataModifier`	`null`	修改整条数据，参见隐私配置。
`Trace`	`new TraceConfig()`	Trace 配置。
`Logging`	`new LogConfig()`	Log 配置。
`Privacy`	`new RumPrivacyConfig()`	隐私配置。
`SessionReplay`	`new RumSessionReplayConfig()`	Session Replay 配置。
`Cache`	`new CacheOptions()`	文件缓存参数，见上表。
`Upload`	`new UploadOptions()`	上传调度参数，见上表。

本地环境部署（Datakit）¶

.NET / C#Native C/C++

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

配置生命周期¶

C# GuanceConfig 在 GuanceClient 生命周期内由 SDK 持有，不要重复调用 GuanceSdk.Init() 切换配置。
Native 初始化期间会复制 guance_sdk_config_v2 字符串。guance_sdk_init_v2() 返回后可以释放原始字符串。
Native Trace/资源过滤等回调配置会保留函数指针和 user_data，具体生命周期以对应配置页面为准。
C# 与 Native 都应在应用进程中只创建一个活动客户端，避免重复采集。

诊断¶

.NET / C#Native C/C++

C# SDK 不提供运行时 Debug 开关。应用使用 Debug 构建或已附加调试器时，SDK 会将自身的队列、传输和自动采集诊断输出到当前进程的 Console 和调试输出；优化的 Release 运行不会自动输出。诊断信息仅用于本地排查，不会作为自定义 Log 写入或上报。

初始化时注册诊断监听：

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

DiagnosticListener 与构建配置相互独立；即使在 Release 构建中，也可通过监听器接收诊断事件并自行写入应用的日志系统。

读取快照：

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

诊断信息不应输出 Client Token、认证 Header 或用户敏感数据。

运行时能力¶

.NET / C#Native C/C++

await GuanceSdk.FlushAsync();
await GuanceSdk.ShutdownAsync();

guance_sdk_flush(rum);
guance_sdk_shutdown(rum);
rum = nullptr;

关闭后不得继续使用客户端或 Native Handle。正常关闭会处理 RUM 与 Log 队列。

SDK 初始化¶

Application 配置¶

基础配置¶

文件缓存与数据传输¶

扩展配置¶

本地环境部署（Datakit）¶

配置生命周期¶

诊断¶

运行时能力¶

相关文档¶

文档内容是否对您有帮助？

SDK 初始化¶

Application 配置¶

基础配置¶

文件缓存与数据传输¶

扩展配置¶

本地环境部署（Datakit）¶

配置生命周期¶

诊断¶

运行时能力¶

相关文档¶

文档内容是否对您有帮助？ ×

文档内容是否对您有帮助？