Skip to content

Log Configuration

The Windows SDK Log uses a dedicated persistent queue and is uploaded to the Logging Intake. C# and Native C/C++ share the same sampling, level filtering, RUM linking, and queue semantics. Only application logs written through explicit Log API calls enter this upload pipeline.

Log Initialization Configuration

GuanceSdk.Init(new GuanceConfig
{
    DatawayUrl = "https://openway.guance.com",
    ClientToken = "<client-token>",
    RumAppId = "<rum-app-id>",
    Logging = new LogConfig
    {
        EnableCustomLog = true,
        EnableLinkRumData = true,
        SamplingRate = 100, // Supported since NuGet 0.1.0-alpha.8
        LevelFilters = new[]
        {
            LogStatus.Info,
            LogStatus.Warning,
            LogStatus.Error,
            LogStatus.Critical
        },
        GlobalContext = new Dictionary<string, object?>
        {
            ["component"] = "desktop-ui"
        }
    }
});

C# Parameters

Parameter Default Description
EnableCustomLog false Whether to accept custom Logs. When disabled, AddLog() is not enqueued.
EnableLinkRumData false Whether to link to the current RUM Session, View, and Action.
SamplingRate (since NuGet 0.1.0-alpha.8) 100 Independent Log sampling percentage, range 0–100, supports decimals.
SampleRate (deprecated) 1 Keeps the 0–1 scale; use SamplingRate instead.
LevelFilters null Standard Log levels allowed for collection; null means no level filtering.
GlobalContext Empty dictionary Global attributes appended to every Log.
DiscardStrategy DiscardNew When the queue is full, discard new data or the oldest data.
guance_log_property global_context[] = {
    {"component", "native-ui"}
};

guance_log_config_v2 logging;
guance_log_config_v2_init(&logging);
logging.enable_custom_log = 1;
logging.enable_link_rum_data = 1;
logging.sampling_rate = 100.0f; // Supported since vcpkg 0.1.0-alpha.9
logging.level_filter_mask =
    GUANCE_LOG_INFO |
    GUANCE_LOG_WARNING |
    GUANCE_LOG_ERROR |
    GUANCE_LOG_CRITICAL;
logging.global_context = global_context;
logging.global_context_count = 1;

if (!guance_log_configure_v2(rum, &logging)) {
    // Configuration is invalid; Log is not enabled.
}

Native C/C++ Parameters

All versioned structs must call guance_log_config_v2_init() first.

Field Default Description
enable_custom_log 0 Whether to accept custom Logs.
enable_link_rum_data 0 Whether to link to the current RUM context.
sampling_rate (since vcpkg 0.1.0-alpha.9) 100 Independent Log sampling percentage, range 0–100, supports decimals.
Legacy struct sample_rate (deprecated) 1 Keeps the 0–1 scale; use sampling_rate in the v2 configuration instead.
level_filter_mask 0 Standard level bitmask; 0 accepts standard levels and custom statuses.
global_context NULL Array of guance_log_property. Strings are copied synchronously during configuration.
global_context_count 0 Number of global properties, maximum 1024.
discard_strategy GUANCE_LOG_DISCARD_NEW When the queue is full, discard new data or the oldest data.

Log, RUM, and Session Replay share the SDK disk cache limit. Cache capacity, file count, and batch size are all configured through SDK Initialization.

If the same .NET configuration sets both SamplingRate and SampleRate, SamplingRate takes precedence.

Logging with Logger

The supported standard statuses are debug, info, warning, error, critical, and ok.

GuanceSdk.AddLog(
    "saved settings",
    LogStatus.Info,
    new Dictionary<string, object?>
    {
        ["operation"] = "save"
    });

GuanceSdk.AddLogs(new[]
{
    new LogEntry("first", LogStatus.Info),
    new LogEntry("second", "audit")
});
guance_log_property properties[] = {
    {"operation", "save"}
};

guance_log_add(
    rum,
    "saved settings",
    "info",
    properties,
    1);

guance_log_entry entries[] = {
    {"first", "info", nullptr, 0},
    {"second", "audit", nullptr, 0}
};
const int accepted = guance_log_add_batch(rum, entries, 2);

A single Log entry retains at most 30 KiB of UTF-8 data; any excess is truncated at a character boundary. Attributes must not contain tokens, authentication headers, cookies, or user-sensitive information.

RUM Linking

After RUM linking is enabled for Log, the SDK writes the current session_id, view_id, and action_id to the Log. Linking uses only the active context at the time the Log is written and does not retroactively modify already-enqueued data.

Queue and Diagnostics

Log and RUM use separate queues and upload counters. Flush and normal shutdown process both queues.

var diagnostics = GuanceSdk.GetLogDiagnosticsSnapshot();
Console.WriteLine(
    $"enqueued={diagnostics.LogsEnqueued}, " +
    $"droppedByConfig={diagnostics.LogsDroppedByConfiguration}, " +
    $"droppedBySampling={diagnostics.LogsDroppedBySampling}, " +
    $"droppedByLevel={diagnostics.LogsDroppedByLevel}, " +
    $"droppedByCapacity={diagnostics.LogsDroppedByCapacity}, " +
    $"uploaded={diagnostics.UploadSuccessCount}, " +
    $"lastError={diagnostics.LastUploadError}");
guance_log_diagnostics diagnostics;
guance_log_diagnostics_init(&diagnostics);
if (guance_log_get_diagnostics(rum, &diagnostics)) {
    printf("enqueued=%lld dropped=%lld uploaded=%lld\n",
        static_cast<long long>(diagnostics.logs_enqueued),
        static_cast<long long>(diagnostics.logs_dropped),
        static_cast<long long>(diagnostics.upload_success_count));
}

Feedback

Is this page helpful?