LOG Samples

LOG 使用範例

⚠️ 本頁適用於 OzaLog v3.0+ (套件 ID: OzaLog)。 舊版 Ozakboy.NLOG v2.x 已棄用,API 與本頁不完全相容——升級請見升級指南。

引用

using OzaLog;

v2.x 的 using ozakboy.NLOG; 已淘汰。

---

立即使用(無需配置)

LOG.Info_Log("Hello, OzaLog!");

→ 自動寫入 {AppRoot}/logs/yyyyMMdd/InfoLogs/Info_Log.txt → 預設啟用異步寫入,呼叫端不阻塞

---

配置(選用,啟動時呼叫一次)

LOG.Configure(o =>
{
    // 保留天數(必須是負數,代表「保留最近 N 天」)
    o.KeepDays = -7;

    // 單檔最大大小(MB),超過自動分割成 _part2_Log.txt 等
    o.SetFileSizeInMB(50);

    // 異步寫入(預設 true)
    o.EnableAsyncLogging = true;

    // 同步輸出至 Console(預設 false)
    o.EnableConsoleOutput = true;

    // 自訂 log 根目錄(預設 "logs")
    o.LogPath = "logs";

    // 各層級獨立子目錄(可選)
    o.TypeDirectories.ErrorPath = "ErrorLogs";

    // ── v3.0 新增選項 ──────────────────────────────

    // 啟用全域意外攔截(訂閱 AppDomain.UnhandledException)
    o.EnableGlobalExceptionCapture = false;

    // 持久化 FileStream pool 上限(LRU 淘汰)
    o.MaxOpenFileStreams = 100;

    // 持久化 FileStream 落盤間隔(ms)
    o.DiskFlushIntervalMs = 100;

    // queue 滿時 drop oldest 觸發的 callback
    o.OnDropped = () => Interlocked.Increment(ref _dropCount);

    // 異步隊列細部設定
    o.ConfigureAsync(a =>
    {
        a.MaxBatchSize = 1000;
        a.MaxQueueSize = 100_000;
        a.FlushIntervalMs = 100;
    });
});

⚠️ Configure 只能呼叫一次,重複呼叫會丟 InvalidOperationException。 v2.x 的 LOG.SetLogKeepDay(-7) / LOG.SetBigFilesByte(...) API 已併入 Configure,單獨方法不再公開。

---

各 LogLevel 對應方法

LogLevel	方法	預設輸出檔
Trace	LOG.Trace_Log(...)	Trace_Log.txt
Debug	LOG.Debug_Log(...)	Debug_Log.txt
Info	LOG.Info_Log(...)	Info_Log.txt
Warn	LOG.Warn_Log(...)	Warn_Log.txt
Error	LOG.Error_Log(...)	Error_Log.txt
Fatal	LOG.Fatal_Log(...)	Fatal_Log.txt
自訂	LOG.CustomName_Log(name, ...)	{name}_Log.txt

📌 v2.x 的 LOG.CostomName_Log(...) 拼字錯誤已修正為 CustomName_Log。底層 enum LogLevel.CustomName 也同步修正(數值仍為 99,wire-format 相容)。

---

寫入字串

LOG.Info_Log("簡單訊息");
LOG.Info_Log($"含變數: {value}");

// 第二參數 false → 不寫 txt
LOG.Info_Log("不要寫檔", false);

寫入物件(自動序列化為 JSON)

var data = new { Symbol = "BTC", Price = 67890.12, Volume = 1.5 };
LOG.Info_Log(data);
LOG.Info_Log("BTC 報價", data);  // 含說明訊息

自訂分類 log(每個分類獨立檔案)

LOG.CustomName_Log("BTC", "tick: 67890.12");      // → BTC_Log.txt
LOG.CustomName_Log("ETH", $"price: {price}");     // → ETH_Log.txt
LOG.CustomName_Log("API", "external call");      // → API_Log.txt

→ 每個 name 寫到獨立檔案,適合多商品報價串流場景(每個商品一個檔)。

---

立即 flush(不等批次)

LOG.Info_Log("緊急訊息", null, writeTxt: true, immediateFlush: true);

Error_Log 與 Fatal_Log 預設就會立即 flush,不必傳此參數。

---

異常 log

try
{
    PlaceOrder(symbol, price);
}
catch (Exception ex)
{
    LOG.Error_Log(ex);                          // 序列化為 JSON
    LOG.Error_Log("PlaceOrder 失敗", ex);       // 含上下文訊息
}

詳見 ErrorMessageException Samples。

---

檔案輸出結構

{AppRoot}/
└── logs/
    └── 20260509/                  ← yyyyMMdd 日期資料夾
        ├── InfoLogs/
        │   └── Info_Log.txt
        ├── ErrorLogs/
        │   └── Error_Log.txt
        └── (CustomName 直接放在當日根目錄)
            ├── BTC_Log.txt
            └── ETH_Log.txt

---

完整 API 參考

請見 docs/zh-TW/api.md。