跳转至

自定义标签使用

C# 与 Native C/C++ 都支持用户信息、SDK 全局上下文和 RUM 全局上下文。Log 还可以配置独立的全局属性。

SDK 运行时添加

匿名用户标识

C# 与 Native C/C++ 在初始化时都会为未登录用户生成以 ft.rd_ 开头的匿名 userid。标识按 RUM 应用 ID 隔离，并保存在 SDK 缓存目录的 identity 子目录中；同一 RUM 应用 ID 和缓存目录会在进程重启后继续使用同一标识，C++ 宿主与 Electron Bridge 也复用该语义。

未调用用户 API 时，RUM 数据使用匿名 userid；开启 RUM 关联的 Log 也会携带该标识。调用 SetUser() 或 guance_sdk_set_user() 后，后续数据改用显式用户 ID；调用清除 API 后，后续数据恢复使用原匿名标识。删除对应缓存目录会重置该标识。

如果身份文件不可写或加锁失败，SDK 会为当前进程使用临时匿名标识，并通过 C# DiagnosticListener 或 Native 诊断输出报告持久化失败；遥测采集不会因此中断。

设置用户

GuanceSdk.SetUser(
    id: "user-123",
    name: "Alice",
    email: "alice@example.com",
    extra: new Dictionary<string, object?>
    {
        ["plan"] = "enterprise"
    });

guance_sdk_set_user(
    rum,
    "user-123",
    "Alice",
    "alice@example.com");

清除用户：

GuanceSdk.ClearUser();

guance_sdk_clear_user(rum);

用户切换只影响后续数据，不修改已经入队的数据。

SDK 全局上下文

适用于 RUM 以及开启关联的 Log：

GuanceSdk.AddGlobalContext("region", "cn-east-1");
GuanceSdk.AddGlobalContext("tenant", "tenant-a");

guance_sdk_add_global_context(rum, "region", "cn-east-1");
guance_sdk_add_global_context(rum, "tenant", "tenant-a");

RUM 全局上下文

只追加到 RUM 数据：

GuanceSdk.AddRumGlobalContext("ui.framework", "wpf");

guance_rum_add_rum_context(rum, "ui.framework", "win32");

Log 全局上下文

Log 专用标签在初始化 Log 时配置：

Logging = new LogConfig
{
    EnableCustomLog = true,
    GlobalContext = new Dictionary<string, object?>
    {
        ["logger_name"] = "desktop-client"
    }
}

guance_log_property context[] = {
    {"logger_name", "native-client"}
};
logging.global_context = context;
logging.global_context_count = 1;

完整参数请参考 Log 配置。

事件级属性

C# 的手动 RUM 和 Log API 接受事件级字典。Native Log 接受 guance_log_property；Native RUM v1 的手动事件 API 不提供任意事件级属性结构。

GuanceSdk.AddAction(
    "Save",
    "click",
    TimeSpan.FromMilliseconds(25),
    new Dictionary<string, object?>
    {
        ["result"] = "success"
    });

命名与保留字段

  • 使用小写、稳定、可聚合的字段名，例如 feature.name。
  • 不要写入 Token、Cookie、密码或直接身份信息。
  • app_id、service、env、version、sdk_name、session_id、view_id、action_id 和平台字段由 SDK 管理。
  • 自定义上下文不能覆盖 SDK 保留字段。
  • Native 上下文 API 会同步复制字符串；不要传入空 Key。

文档评价

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