Log 配置¶

Windows SDK 的 Log 使用独立持久化队列并上报到 Logging Intake。C# 与 Native C/C++ 共用采样、等级过滤、RUM 关联和队列语义；C# 额外支持采集 System.Diagnostics.Trace 输出。

初始化 Log¶

.NET / C#Native C/C++

RumSdk.Init(new RumConfig
{
    DatawayUrl = "https://openway.guance.com",
    ClientToken = "<client-token>",
    RumAppId = "<rum-app-id>",
    Logging = new RumLogConfig
    {
        EnableCustomLog = true,
        EnableLinkRumData = true,
        EnableTraceCapture = true,
        SampleRate = 1.0,
        LevelFilters = new[]
        {
            RumLogStatus.Info,
            RumLogStatus.Warning,
            RumLogStatus.Error,
            RumLogStatus.Critical
        },
        GlobalContext = new Dictionary<string, object?>
        {
            ["component"] = "desktop-ui"
        }
    }
});

guance_rum_log_property global_context[] = {
    {"component", "native-ui"}
};

guance_rum_log_config logging;
guance_rum_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_RUM_LOG_INFO |
    GUANCE_RUM_LOG_WARNING |
    GUANCE_RUM_LOG_ERROR |
    GUANCE_RUM_LOG_CRITICAL;
logging.global_context = global_context;
logging.global_context_count = 1;

if (!guance_rum_configure_logging(rum, &logging)) {
    // 配置无效，Log 未启用。
}

C# 参数¶

参数	默认值	说明
`EnableCustomLog`	`false`	是否接受自定义 Log。未开启时 `AddLog()` 不入队。
`EnableLinkRumData`	`false`	是否关联当前 RUM Session、View 和 Action。
`EnableTraceCapture`	`false`	是否自动转发 `System.Diagnostics.Trace` 和 `TraceSource` 输出；要求同时开启 `EnableCustomLog`。
`SampleRate`	`1.0`	Log 独立采样率，范围 `0.0`～`1.0`。
`LevelFilters`	`null`	允许采集的标准 Log 等级；`null` 表示不按等级过滤。
`GlobalContext`	空字典	追加到每条 Log 的全局属性。
`MaxQueueItems`	`5000`	Log 队列条目上限，最小值 `1000`。
`MaxQueueBytes`	`32 MiB`	Log 队列字节上限，必须大于 `0`。
`DiscardStrategy`	`DiscardNew`	队列满时丢弃新数据或最旧数据。

Native C/C++ 参数¶

所有版本化结构都必须先调用 guance_rum_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_rum_log_property` 数组。配置时同步复制字符串。
`global_context_count`	`0`	全局属性数量，最大 `1024`。
`max_queue_items`	`5000`	Log 队列条目上限，必须大于 `0`。
`max_queue_bytes`	`32 MiB`	Log 队列字节上限，必须大于 `0`。
`discard_strategy`	`GUANCE_RUM_LOG_DISCARD_NEW`	队列满时丢弃新数据或最旧数据。

写入日志¶

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

.NET / C#Native C/C++

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

RumSdk.AddLogs(new[]
{
    new RumLogEntry("first", RumLogStatus.Info),
    new RumLogEntry("second", "audit")
});

guance_rum_log_property properties[] = {
    {"operation", "save"}
};

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

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

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

自动采集 Trace 输出¶

C# 设置 EnableTraceCapture = true 后，SDK 在初始化时自动安装 RumTraceListener：

Trace.WriteLine("application started");
Trace.TraceWarning("cache is nearly full");
Trace.TraceError("save failed");

也可以在初始化后调用 RumSdk.EnableAutomaticLogCapture() 和 RumSdk.DisableAutomaticLogCapture()。Native C/C++ 当前不自动拦截控制台、ETW 或第三方日志框架，需要调用 Log C ABI。

RUM 关联¶

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

队列与诊断¶

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

.NET / C#Native C/C++

var diagnostics = RumSdk.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_rum_log_diagnostics diagnostics;
guance_rum_log_diagnostics_init(&diagnostics);
if (guance_rum_get_log_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++ 参数¶

写入日志¶

自动采集 Trace 输出¶

RUM 关联¶

队列与诊断¶

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