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¶
TrueWatchSdk.Init(new TrueWatchConfig
{
DatawayUrl = "https://openway.truewatch.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. |
truewatch_log_property global_context[] = {
{"component", "native-ui"}
};
truewatch_log_config_v2 logging;
truewatch_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 =
TRUEWATCH_LOG_INFO |
TRUEWATCH_LOG_WARNING |
TRUEWATCH_LOG_ERROR |
TRUEWATCH_LOG_CRITICAL;
logging.global_context = global_context;
logging.global_context_count = 1;
if (!truewatch_log_configure_v2(rum, &logging)) {
// Configuration is invalid; Log is not enabled.
}
Native C/C++ Parameters¶
All versioned structs must call truewatch_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 truewatch_log_property. Strings are copied synchronously during configuration. |
global_context_count |
0 |
Number of global properties, maximum 1024. |
discard_strategy |
TRUEWATCH_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.
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 = TrueWatchSdk.GetLogDiagnosticsSnapshot();
Console.WriteLine(
$"enqueued={diagnostics.LogsEnqueued}, " +
$"droppedByConfig={diagnostics.LogsDroppedByConfiguration}, " +
$"droppedBySampling={diagnostics.LogsDroppedBySampling}, " +
$"droppedByLevel={diagnostics.LogsDroppedByLevel}, " +
$"droppedByCapacity={diagnostics.LogsDroppedByCapacity}, " +
$"uploaded={diagnostics.UploadSuccessCount}, " +
$"lastError={diagnostics.LastUploadError}");
truewatch_log_diagnostics diagnostics;
truewatch_log_diagnostics_init(&diagnostics);
if (truewatch_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));
}