配置選項

所有配置都在程式啟動時透過 LOG.Configure(...) 一次性設定。此呼叫不可重入 — 第二次呼叫拋 InvalidOperationException。若完全省略,首次寫 log 會自動以預設值初始化。

using OzaLog;

LOG.Configure(o =>
{
    o.KeepDays = -7;
    o.SetFileSizeInMB(50);
    o.OutputFormat = LogOutputFormat.Json;
    o.ConfigureQuote(q => q.Enable = true);
});

1. LogOptions — 主 logger

1.1 檔案輸出

1.2 輸出格式 (v3.1+)

1.3 非同步管線行為

1.4 全域意外攔截(opt-in)

不會攔截 WPF DispatcherUnhandledException、WinForms ThreadException、ASP.NET Core middleware 例外 — 函式庫層級無法存取這些 framework 物件。宿主應用需自行 hook。

1.5 LogTypeDirectories — 各級別子目錄

o.TypeDirectories.DirectoryPath = "LogFiles";   // 級別專屬路徑為 null 時的預設
o.TypeDirectories.ErrorPath     = "ErrorLogs";  // Error 級別走獨立資料夾
o.TypeDirectories.FatalPath     = "FatalLogs";
// 另有 TracePath / DebugPath / InfoPath / WarnPath / CustomPath

級別專屬路徑為 null 時,fallback 為 DirectoryPath。

1.6 AsyncLogOptions — dispatcher 調校

透過 o.ConfigureAsync(a => { ... }) 設定。

2. QuoteOptions — 報價 pipeline (v3.1+)

透過 o.ConfigureQuote(q => { ... }) 設定。預設 Enable = false — 報價 pipeline 必須明確 opt-in。

LOG.Configure(o =>
{
    o.ConfigureQuote(q =>
    {
        q.Enable = true;
        q.OutputFormat = QuoteOutputFormat.Json;
        q.QuotePath = "Quotes";
        q.MaxOpenStreams = 500;
        q.MaxQueueSize = 50_000;
        q.MaxBatchSize = 500;
        q.FlushIntervalMs = 100;
        q.OnDropped = droppedCount => MyMetrics.RecordDrops(droppedCount);
    });
});

報價 pipeline 沿用主 logger 的 KeepDays 與 MaxFileSize 進行保留與檔案分割。報價檔案會被同一個 LogRetentionCleaner 清理。

3. 透過 LOG.GetCurrentOptions() 讀回

Configure 後可透過唯讀視圖檢視執行中設定:

var current = LOG.GetCurrentOptions();

// 主 logger
Console.WriteLine(current.OutputFormat);                  // Json
Console.WriteLine(current.TimeFormat);                    // "HH:mm:ss.fff"
Console.WriteLine(current.ShowThreadId);                  // true
Console.WriteLine(current.ShowThreadName);                // false
Console.WriteLine(current.HighPrecisionTimestamp);        // false
Console.WriteLine(current.MaxOpenFileStreams);            // 100
Console.WriteLine(current.AsyncOptions.MaxQueueSize);     // 10000

// 報價 pipeline
Console.WriteLine(current.QuoteOptions.Enable);           // true
Console.WriteLine(current.QuoteOptions.OutputFormat);     // Json
Console.WriteLine(current.QuoteOptions.QuotePath);        // "Quotes"
Console.WriteLine(current.QuoteOptions.MaxOpenStreams);   // 500

所有讀回的值都包在 ReadOnlyLogOptions / ReadOnlyQuoteOptions 內 — 消費者無法透過此視圖修改執行中設定。

4. 預設值總表(未呼叫 LOG.Configure(...) 時)

→ 一頁式 API 摘要見 API 參考。