Skip to content

Log Configuration

The Windows SDK uses a dedicated persistent queue for Logs and reports them to the Logging Intake. C# and Native C/C++ share the same sampling, level filtering, RUM correlation, and queue semantics. Only business logs explicitly written by the application through the Log API enter this ingestion 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,
        SampleRate = 1.0,
        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() does not enqueue.
EnableLinkRumData false Whether to correlate with the current RUM Session, View, and Action.
SampleRate 1.0 Independent Log sampling rate, range 0.0 to 1.0.
LevelFilters null Allowed standard Log levels; null means no level filtering.
GlobalContext Empty dictionary Global attributes appended to every Log.
DiscardStrategy DiscardNew Whether to discard new or oldest data when the queue is full. 
guance_log_property global_context[] = {
    {"component", "native-ui"}
};

guance_log_config logging;
guance_log_config_init(&logging);
logging.enable_custom_log = 1;
logging.enable_link_rum_data = 1;
logging.sample_rate = 1.0;
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(rum, &logging)) {
    // Configuration is invalid, Log not enabled.
}

Native C/C++ Parameters

All versioned structures must be initialized with guance_log_config_init() first.

Field Default Description
enable_custom_log 0 Whether to accept custom logs.
enable_link_rum_data 0 Whether to correlate with the current RUM context.
sample_rate 1.0 Independent Log sampling rate, range 0.0 to 1.0.
level_filter_mask 0 Bitmask for standard levels; 0 accepts both standard levels and custom statuses.
global_context NULL Array of guance_log_property. Strings are copied synchronously on configuration.
global_context_count 0 Number of global properties, maximum 1024.
discard_strategy GUANCE_LOG_DISCARD_NEW Whether to discard new or oldest data when the queue is full.

Logs, RUM, and Session Replay share the SDK's disk cache limit. The cache capacity, file count, and batch size are configured uniformly via SDK Initialization.

Logger Log Output

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

Each Log entry retains a maximum of 30 KiB UTF-8 data; excess content is truncated at a character boundary. Properties must not include Tokens, authentication headers, Cookies, or sensitive user information.

RUM Correlation

When RUM correlation is enabled for Logs, the SDK writes the current session_id, view_id, and action_id into the Log. Correlation uses only the active context at the time the Log is written; it does not retroactively modify already enqueued data.

Queue and Diagnostics

Logs 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?