Log 配置¶

Windows SDK 的 Log 使用独立持久化队列并上报到 Logging Intake。C# 与 Native C/C++ 共用采样、等级过滤、RUM 关联和队列语义。只有应用显式调用 Log API 写入的业务日志会进入该上报链路。

Log 初始化配置¶

.NET / C#Native C/C++

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# 参数¶

参数	默认值	说明
`EnableCustomLog`	`false`	是否接受自定义 Log。未开启时 `AddLog()` 不入队。
`EnableLinkRumData`	`false`	是否关联当前 RUM Session、View 和 Action。
`SampleRate`	`1.0`	Log 独立采样率，范围 `0.0`～`1.0`。
`LevelFilters`	`null`	允许采集的标准 Log 等级；`null` 表示不按等级过滤。
`GlobalContext`	空字典	追加到每条 Log 的全局属性。
`DiscardStrategy`	`DiscardNew`	队列满时丢弃新数据或最旧数据。

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)) {
    // 配置无效，Log 未启用。
}

Native C/C++ 参数¶

所有版本化结构都必须先调用 guance_log_config_init()。

字段	默认值	说明
`enable_custom_log`	`0`	是否接受自定义 Log。
`enable_link_rum_data`	`0`	是否关联当前 RUM 上下文。
`sample_rate`	`1.0`	Log 独立采样率，范围 `0.0`～`1.0`。
`level_filter_mask`	`0`	标准等级位掩码；`0` 接受标准等级和自定义状态。
`global_context`	`NULL`	`guance_log_property` 数组。配置时同步复制字符串。
`global_context_count`	`0`	全局属性数量，最大 `1024`。
`discard_strategy`	`GUANCE_LOG_DISCARD_NEW`	队列满时丢弃新数据或最旧数据。

Log、RUM 和 Session Replay 共用 SDK 磁盘缓存上限，缓存容量、文件数量和批次大小统一通过 SDK 初始化配置。

Logger 日志打印¶

支持的标准状态为 debug、info、warning、error、critical 和 ok。

.NET / C#Native C/C++

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

单条 Log 内容最多保留 30 KiB UTF-8 数据，超出部分在字符边界截断。属性不得包含 Token、认证 Header、Cookie 或用户敏感信息。

RUM 关联¶

开启 Log 的 RUM 关联后，SDK 会把当前 session_id、view_id 和 action_id 写入 Log。关联只使用写入 Log 时的活动上下文，不会回溯修改已入队数据。

队列与诊断¶

Log 与 RUM 使用独立队列和上传计数。Flush 和正常关闭会同时处理两类队列。

.NET / C#Native C/C++

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

Log 配置¶

Log 初始化配置¶

C# 参数¶

Native C/C++ 参数¶

Logger 日志打印¶

RUM 关联¶

队列与诊断¶

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

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