Custom Tags Usage¶

Both C# and Native C/C++ support user information, SDK global context, and RUM global context. Log can also be configured with independent global attributes.

Adding at Runtime¶

Anonymous User Identifier¶

Both C# and Native C/C++ generate an anonymous userid prefixed with ft.rd_ for unauthenticated users during initialization. The identifier is isolated by RUM application ID and persisted in the identity subdirectory of the SDK cache directory; the same RUM application ID and cache directory will reuse the same identifier across process restarts, and the C++ host and Electron Bridge also share this semantics.

When the user API is not called, RUM data uses the anonymous userid; Logs with RUM correlation enabled also carry this identifier. After calling SetUser() or guance_sdk_set_user(), subsequent data uses the explicit user ID; after calling the clear API, subsequent data reverts to the original anonymous identifier. Deleting the corresponding cache directory resets the identifier.

If the identity file is not writable or locking fails, the SDK uses a temporary anonymous identifier for the current process and reports the persistence failure through C# DiagnosticListener or Native diagnostic output; telemetry collection is not interrupted.

Setting the User¶

.NET / C#Native C/C++

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

Clearing the user:

.NET / C#Native C/C++

GuanceSdk.ClearUser();

guance_sdk_clear_user(rum);

User switching only affects subsequent data and does not modify data already enqueued.

SDK Global Context¶

Applies to RUM and correlated Logs:

.NET / C#Native C/C++

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 Global Context¶

Added only to RUM data:

.NET / C#Native C/C++

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

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

Log Global Context¶

Log-specific tags are configured during Log initialization:

.NET / C#Native C/C++

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;

For the full parameter list, see Log Configuration.

Event-Level Attributes¶

The manual RUM and Log APIs in C# accept an event-level dictionary. Native Log accepts guance_log_property; the Native RUM v1 manual event API does not provide an arbitrary event-level attribute structure.

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

Naming and Reserved Fields¶

Use lowercase, stable, and aggregatable field names, for example, feature.name.
Do not write Tokens, Cookies, passwords, or direct personally identifiable information.
app_id, service, env, version, sdk_name, session_id, view_id, action_id, and platform fields are managed by the SDK.
Custom context must not override SDK reserved fields.
The Native context API synchronously copies strings; do not pass empty keys.