跳转至

SDK 初始化

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

最小配置

RumSdk.Init(new RumConfig
{
    DatawayUrl = "https://openway.guance.com",
    ClientToken = "<client-token>",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "prod",
    Version = "1.0.0"
});

guance_rum_config config;
guance_rum_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_rum_handle rum = guance_rum_init(&config);
if (rum == nullptr) {
    // 初始化失败。
}

Native 结构必须先调用 guance_rum_config_init()，确保未显式设置的字段使用当前版本默认值。

基础参数

语义 .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 version 1.0.0 是
调试诊断 Debug debug false / 0 否

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

RUM 队列与传输

语义 .NET / C# Native C/C++ 默认值
队列条目上限 MaxQueueItems max_queue_items 100000
队列字节上限 MaxQueueBytes max_queue_bytes 64 MiB
HTTP 超时 HttpTimeout http_timeout_ms 10 秒
缓存位置 CacheDirectory cache_path SDK 默认目录
代理 自定义 HttpMessageHandlerFactory proxy_url 空
批量条数 BatchSize 固定内部批次 50
周期 Flush FlushInterval 无对应公开配置 .NET 默认 15 秒；Native 由应用显式 Flush 或关闭时处理
Intake 压缩 CompressIntakeRequests 当前无对应公开配置 false

C# 还可以通过 HttpResourceTimingProvider 提供真实网络阶段耗时。Log 使用独立队列参数，请参考 Log 配置。

本地环境部署（Datakit）

RumSdk.Init(new RumConfig
{
    DatakitUrl = "http://127.0.0.1:9529",
    RumAppId = "<rum-app-id>",
    ServiceName = "desktop-client",
    Env = "local",
    Version = "1.0.0"
});

guance_rum_config config;
guance_rum_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_rum_handle rum = guance_rum_init(&config);

配置生命周期

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

诊断

初始化时注册诊断监听：

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

读取快照：

var snapshot = RumSdk.GetDiagnosticsSnapshot();
Console.WriteLine(
    $"queued={snapshot.RumEventsEnqueued}, " +
    $"uploaded={snapshot.RumUploadSuccessCount}, " +
    $"retries={snapshot.RumUploadRetryCount}");

guance_rum_diagnostics diagnostics{};
if (guance_rum_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 或用户敏感数据。

Flush 与关闭

await RumSdk.FlushAsync();
await RumSdk.ShutdownAsync();

guance_rum_flush(rum);
guance_rum_shutdown(rum);
rum = nullptr;

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

相关文档

文档评价

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