日志組件是NewLife系列組件最早最基礎(chǔ)，同時(shí)也是流血流淚最多的一個(gè)模塊，它的底蘊(yùn)定能感動(dòng)每一個(gè)用戶(hù)！

沒(méi)有日志的應(yīng)用系統(tǒng)是不完整的。系統(tǒng)遇到啥問(wèn)題，翻日志看看當(dāng)時(shí)上下文，實(shí)在分析不出問(wèn)題，修改代碼再打幾個(gè)日志……這是每一個(gè)程序員的日常寫(xiě)照。

不少同學(xué)喜歡調(diào)試程序，但是聽(tīng)過(guò)“薛定諤的貓”這個(gè)故事的人不多。有時(shí)候程序跑起來(lái)沒(méi)問(wèn)題，調(diào)試就有問(wèn)題；有時(shí)候跑起來(lái)有問(wèn)題，調(diào)試就沒(méi)有問(wèn)題。就像是薛定諤的貓，測(cè)不準(zhǔn)原理，調(diào)試觀察本身干涉了程序運(yùn)行。這個(gè)時(shí)候就需要看日志。

單片機(jī)嵌入式設(shè)備、安卓移動(dòng)應(yīng)用、Linux嵌入式應(yīng)用，雖然都可以在線(xiàn)調(diào)試，但也會(huì)有許多不方便的地方。如果能夠配合使用日志，將會(huì)事半功倍。

Nuget包：NewLife.Core

源碼地址：

https://github.com/NewLifeX/X/tree/master/NewLife.Core/Log

Get Started

新建控制臺(tái)項(xiàng)目 ConsoleApp1 ，放到 D:\Test，其它目錄也可以

從Nuget引用 NewLife.Core ，安裝最新版本。

打開(kāi)Program.cs的Main函數(shù)，寫(xiě)入一下代碼

XTrace.UseConsole();
XTrace.WriteLine("Hello NewLife!");

點(diǎn)擊XTrace左邊圖標(biāo)，可選“using NewLife.Log;”自動(dòng)添加命名空間引用。

點(diǎn)擊上方綠色啟動(dòng)三角符號(hào)，或者按下F5，啟動(dòng)應(yīng)用程序。

可以看到打開(kāi)一個(gè)控制臺(tái)窗口，并輸入一行日志

13:15:06.270  1 N - Hello NewLife!

這就是我們前面代碼輸出的內(nèi)容：XTrace.WriteLine("Hello NewLife!");

這也是最簡(jiǎn)單最常見(jiàn)的日志用法：XTrace.WriteLine

XTrace是靜態(tài)跟蹤類(lèi)，WriteLine等日志輸出方法，本質(zhì)上是調(diào)用實(shí)現(xiàn)了ILog接口的XTrace.Log。

日志接口ILog

ILog是日志輸出標(biāo)準(zhǔn)接口

/// <summary>寫(xiě)日志</summary>/// <param name="level">日志級(jí)別</param>/// <param name="format">格式化字符串</param>/// <param name="args">格式化參數(shù)</param>void Write(LogLevel level, String format, params Object?[] args);
/// <summary>調(diào)試日志</summary>/// <param name="format">格式化字符串</param>/// <param name="args">格式化參數(shù)</param>void Debug(String format, params Object?[] args);
/// <summary>信息日志</summary>/// <param name="format">格式化字符串</param>/// <param name="args">格式化參數(shù)</param>void Info(String format, params Object?[] args);
/// <summary>警告日志</summary>/// <param name="format">格式化字符串</param>/// <param name="args">格式化參數(shù)</param>void Warn(String format, params Object?[] args);
/// <summary>錯(cuò)誤日志</summary>/// <param name="format">格式化字符串</param>/// <param name="args">格式化參數(shù)</param>void Error(String format, params Object?[] args);
/// <summary>嚴(yán)重錯(cuò)誤日志</summary>/// <param name="format">格式化字符串</param>/// <param name="args">格式化參數(shù)</param>void Fatal(String format, params Object?[] args);
/// <summary>是否啟用日志</summary>Boolean Enable { get; set; }
/// <summary>日志等級(jí)，只輸出大于等于該級(jí)別的日志，默認(rèn)Info</summary>LogLevel Level { get; set; }

Write核心方法，很少使用，一般都使用 Info/Debug/Warn/Error/Fatal 等接口，最終都是調(diào)用Write，只是日志等級(jí)不同。

日志對(duì)象可以獨(dú)立控制是否啟用，以及日志等級(jí)Level。

已有日志等級(jí)：

/// <summary>日志等級(jí)</summary>public enum LogLevel : System.Byte{    /// <summary>打開(kāi)所有日志記錄</summary>    All = 0,
    /// <summary>最低調(diào)試。細(xì)粒度信息事件對(duì)調(diào)試應(yīng)用程序非常有幫助</summary>    Debug,
    /// <summary>普通消息。在粗粒度級(jí)別上突出強(qiáng)調(diào)應(yīng)用程序的運(yùn)行過(guò)程</summary>    Info,
    /// <summary>警告</summary>    Warn,
    /// <summary>錯(cuò)誤</summary>    Error,
    /// <summary>嚴(yán)重錯(cuò)誤</summary>    Fatal,
    /// <summary>關(guān)閉所有日志記錄</summary>    Off = 0xFF}

文件日志

文本文件日志是最重要的日志，也是XTrace.Log的默認(rèn)實(shí)現(xiàn)。

文本文件日志是把日志逐行輸出到文本文件中，每天一個(gè)文件。

如果想要獨(dú)立存儲(chǔ)某個(gè)模塊的日志，可以實(shí)例化一個(gè)專(zhuān)屬的TextFileLog對(duì)象。推薦使用Create創(chuàng)建。

/// <summary>每個(gè)目錄的日志實(shí)例應(yīng)該只有一個(gè)，所以采用靜態(tài)創(chuàng)建</summary>/// <param name="path">日志目錄或日志文件路徑</param>/// <param name="fileFormat"></param>/// <returns></returns>public static TextFileLog Create(String path, String fileFormat = null);
/// <summary>每個(gè)目錄的日志實(shí)例應(yīng)該只有一個(gè)，所以采用靜態(tài)創(chuàng)建</summary>/// <param name="path">日志目錄或日志文件路徑</param>/// <returns></returns>public static TextFileLog CreateFile(String path);

文件日志內(nèi)部有隊(duì)列、延遲關(guān)閉等復(fù)雜邏輯，強(qiáng)烈建議使用單例，Create可確保單例實(shí)現(xiàn)。

文本文件日志主要特性：

每天一個(gè)文件，例如 2021_06_25.log
每個(gè)文件最大10M，（可在core.config中配置LogFileMaxBytes），超過(guò)后產(chǎn)生新的日志文件，例如 2021_06_25_2.log

日志目錄為L(zhǎng)og子目錄，（可配置LogPath）
日志目錄中最多只保存最新100個(gè)日志文件，（可配置LogFileBackups）

日志等級(jí)，可配置LogLevel，默認(rèn)Info，大于等于該等級(jí)才輸出日志到文件
日志文件格式，可配置LogFileFormat，默認(rèn) {0:yyyy_MM_dd}.log，也可以按照日志等級(jí)區(qū)分目錄，例如 {1}/{0:yyyy_MM_dd}.log

日志寫(xiě)入使用隊(duì)列實(shí)現(xiàn)，避免影響應(yīng)用層性能
如果連續(xù)5秒沒(méi)有日志寫(xiě)入，則自動(dòng)關(guān)閉日志文件句柄，此時(shí)用戶(hù)可以根據(jù)需要移動(dòng)或刪除日志文件

這里的10M和100個(gè)，最大日志占用1G，可以有效的避免異常信息寫(xiě)爆磁盤(pán)！（說(shuō)多都是淚……）

來(lái)看看上面Demo的日志文件

#Software: ConsoleApp1#ProcessID: 38144 x64#AppDomain: ConsoleApp1#FileName: D:\Test\ConsoleApp1\ConsoleApp1\bin\Debug\net5.0\ConsoleApp1.exe#BaseDirectory: D:\Test\ConsoleApp1\ConsoleApp1\bin\Debug\net5.0\#TempPath: C:\Users\Stone\AppData\Local\Temp\#CommandLine: D:\Test\ConsoleApp1\ConsoleApp1\bin\Debug\net5.0\ConsoleApp1.dll#ApplicationType: Console#CLR: 5.0.7, .NET 5.0.7#OS: Microsoft Windows NT 10.0.19042.0, X6/Stone#CPU: 8#GC: IsServerGC=False, LatencyMode=Interactive#ThreadPool: Min=32/32, Max=32767/1000, Available=32766/1000#Date: 2021-06-25#字段: 時(shí)間 線(xiàn)程ID 線(xiàn)程池Y/網(wǎng)頁(yè)W/普通N/定時(shí)T 線(xiàn)程名/任務(wù)ID 消息內(nèi)容#Fields: Time ThreadID Kind Name Message13:42:42.463  1 N - NewLife.Core v8.10.2021.0604 Build 2021-06-07 09:05:06 .NETCoreApp,Version=v5.013:42:42.465  1 N - X組件核心庫(kù) ?2002-2021 NewLife13:42:42.466  1 N - ConsoleApp1 v1.0.0 Build 2000-01-01 .NETCoreApp,Version=v5.013:42:42.466  1 N - ConsoleApp1 13:42:42.466  1 N - Hello NewLife!

可以看到，日志文件非常完善，還有一個(gè)很完整的日志頭。

文本日志文件格式，參考了多款微軟產(chǎn)品，頭部井號(hào)#隔開(kāi)的行是注釋行，用于說(shuō)明情況。

通過(guò)日志頭，可以了解到一下信息：

軟件名ConsoleApp1，取自進(jìn)程名
進(jìn)程Id，是否64位進(jìn)程

應(yīng)用程序域，這個(gè)現(xiàn)在沒(méi)有太多意義了
執(zhí)行文件名，全路徑

基準(zhǔn)目錄，全路徑。這個(gè)非常重要，很多人的控制臺(tái)程序正常，改為系統(tǒng)服務(wù)以后異常，很大可能性就是因?yàn)檫@個(gè)基準(zhǔn)目錄變成了操作系統(tǒng)目錄。
臨時(shí)目錄，X組件有時(shí)候需要使用臨時(shí)目錄

命令行參數(shù)
應(yīng)用類(lèi)型，.NETCore里面基本上都是Console了，有點(diǎn)難以區(qū)分WinForm和Web

.NET版本，CLR版本
操作系統(tǒng)、CPU等

GC設(shè)置
線(xiàn)程池設(shè)置值。

日志字段格式介紹

字段格式：

時(shí)間，時(shí)分秒和毫秒。這里的毫秒特別重要，可以精確知道各個(gè)操作執(zhí)行耗時(shí)情況
線(xiàn)程Id，如果每個(gè)日志所屬線(xiàn)程不加以區(qū)分，在多線(xiàn)程環(huán)境下就會(huì)一團(tuán)糟

線(xiàn)程類(lèi)型，線(xiàn)程池Y、網(wǎng)頁(yè)W、普通N、定時(shí)T
線(xiàn)程名/任務(wù)Id

日志內(nèi)容

由此可見(jiàn)，日志組件特別適用于分析多線(xiàn)程問(wèn)題。

設(shè)計(jì)如此詳盡的日志頭，主要為了能夠準(zhǔn)確記錄程序的執(zhí)行上下文環(huán)境，特別對(duì)于客戶(hù)端應(yīng)用來(lái)說(shuō)尤為重要！

控制臺(tái)日志

前面例程中，Main函數(shù)開(kāi)頭有一行 XTrace.UseConsole() ，意思是使用控制臺(tái)日志。如果沒(méi)有這一行，XTrace.WriteLine默認(rèn)只會(huì)寫(xiě)入文本文件日志。加上后，同時(shí)寫(xiě)文件和控制臺(tái)。

控制臺(tái)日志ConsoleLog沒(méi)有日志頭，其它跟文本文件日志一樣，輸出時(shí)間、線(xiàn)程信息和日志內(nèi)容。

控制臺(tái)日志多了個(gè)彩色顯示，不同線(xiàn)程以不同顏色區(qū)分，便于快速區(qū)分同一個(gè)線(xiàn)程的日志。受制于控制臺(tái)顏色樣本不足，某些情況下不同線(xiàn)程可能使用相同的顏色。內(nèi)置10種顏色，線(xiàn)程Id對(duì)顏色個(gè)數(shù)取余。

除了WinForm和早期ASP.Net，否則一般都使用 XTrace.UseControle() 把日志同步輸出到控制臺(tái)。對(duì)應(yīng)用性能有嚴(yán)格要求時(shí)，可以注意這一行關(guān)閉控制臺(tái)日志。

切記！！！控制臺(tái)日志不宜過(guò)多，否則會(huì)嚴(yán)重影響應(yīng)用性能，因?yàn)榭刂婆_(tái)數(shù)據(jù)內(nèi)部帶有鎖需要排隊(duì)。

控件日志

對(duì)于WinForm應(yīng)用來(lái)說(shuō)，希望能夠把日志輸出到某個(gè)富文本框之中。控件日志TextControlLog為此而生！

XTrace中有擴(kuò)展方法 UseWinFormControl ：

/// <summary>在WinForm控件上輸出日志，主要考慮非UI線(xiàn)程操作</summary>/// <remarks>不是常用功能，為了避免干擾常用功能，保持UseWinForm開(kāi)頭</remarks>/// <param name="control">要綁定日志輸出的WinForm控件</param>/// <param name="useFileLog">是否同時(shí)使用文件日志，默認(rèn)使用</param>/// <param name="maxLines">最大行數(shù)</param>public static void UseWinFormControl(this Control control, Boolean useFileLog = true, Int32 maxLines = 1000)

在碼神工具 NewLife.XCoder 的網(wǎng)絡(luò)調(diào)試工具中，F(xiàn)rmMain_Load 有以下代碼：

txtReceive.UseWinFormControl();

這里的txtReceive是富文本框RichTextBox，負(fù)責(zé)數(shù)據(jù)接收區(qū)，同時(shí)用于顯示日志。

因此，UseWinFormControl 用于把日志重定向到富文本框，第二參數(shù)useFileLog指定繼續(xù)寫(xiě)文件日志。

網(wǎng)絡(luò)日志

NewLife.Core 組件也支持Android和iOS開(kāi)發(fā)（基于Xamarin），由于設(shè)備上的日志很不好實(shí)時(shí)查看，因而設(shè)計(jì)了網(wǎng)絡(luò)日志。NetworkLog通過(guò)UDP協(xié)議把日志發(fā)送到局域網(wǎng)某個(gè)目標(biāo)地址。

配置文件core.config中指定NetworkLog配置項(xiàng)，例如 udp://10.0.0.3:514 ，也可以使用廣播地址 udp://255.255.255.255:514 。然后在開(kāi)發(fā)機(jī) 10.0.0.3 上開(kāi)一個(gè)碼神工具，網(wǎng)絡(luò)工具監(jiān)聽(tīng)UDP514端口即可接收日志。

嵌入式Linux應(yīng)用開(kāi)發(fā)也可以使用同樣辦法。

網(wǎng)絡(luò)日志降低了我們對(duì)移動(dòng)應(yīng)用和嵌入式應(yīng)用的調(diào)試依賴(lài)。