日志组件是NewLife系列组件最早最基础，同时也是流血流泪最多的一个模块，它的底蕴定能感动每一个用户！

没有日志的应用系统是不完整的。系统遇到啥问题，翻日志看看当时上下文，实在分析不出问题，修改代码再打几个日志……这是每一个程序员的日常写照。

不少同学喜欢调试程序，但是听过“薛定谔的猫”这个故事的人不多。有时候程序跑起来没问题，调试就有问题；有时候跑起来有问题，调试就没有问题。就像是薛定谔的猫，测不准原理，调试观察本身干涉了程序运行。这个时候就需要看日志。

单片机嵌入式设备、安卓移动应用、Linux嵌入式应用，虽然都可以在线调试，但也会有许多不方便的地方。如果能够配合使用日志，将会事半功倍。

Nuget包：NewLife.Core

源码地址：

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

Get Started

新建控制台项目 ConsoleApp1 ，放到 D:\Test，其它目录也可以

从Nuget引用 NewLife.Core ，安装最新版本。

打开Program.cs的Main函数，写入一下代码

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

点击XTrace左边图标，可选“using NewLife.Log;”自动添加命名空间引用。

点击上方绿色启动三角符号，或者按下F5，启动应用程序。

可以看到打开一个控制台窗口，并输入一行日志

13:15:06.270  1 N - Hello NewLife!

这就是我们前面代码输出的内容：XTrace.WriteLine("Hello NewLife!");

这也是最简单最常见的日志用法：XTrace.WriteLine

XTrace是静态跟踪类，WriteLine等日志输出方法，本质上是调用实现了ILog接口的XTrace.Log。

日志接口ILog

ILog是日志输出标准接口

/// <summary>写日志</summary>
/// <param name="level">日志级别</param>
/// <param name="format">格式化字符串</param>
/// <param name="args">格式化参数</param>
void Write(LogLevel level, String format, params Object?[] args);/// <summary>调试日志</summary>
/// <param name="format">格式化字符串</param>
/// <param name="args">格式化参数</param>
void Debug(String format, params Object?[] args);/// <summary>信息日志</summary>
/// <param name="format">格式化字符串</param>
/// <param name="args">格式化参数</param>
void Info(String format, params Object?[] args);/// <summary>警告日志</summary>
/// <param name="format">格式化字符串</param>
/// <param name="args">格式化参数</param>
void Warn(String format, params Object?[] args);/// <summary>错误日志</summary>
/// <param name="format">格式化字符串</param>
/// <param name="args">格式化参数</param>
void Error(String format, params Object?[] args);/// <summary>严重错误日志</summary>
/// <param name="format">格式化字符串</param>
/// <param name="args">格式化参数</param>
void Fatal(String format, params Object?[] args);/// <summary>是否启用日志</summary>
Boolean Enable { get; set; }/// <summary>日志等级，只输出大于等于该级别的日志，默认Info</summary>
LogLevel Level { get; set; }

Write核心方法，很少使用，一般都使用 Info/Debug/Warn/Error/Fatal 等接口，最终都是调用Write，只是日志等级不同。

日志对象可以独立控制是否启用，以及日志等级Level。

已有日志等级：

/// <summary>日志等级</summary>
public enum LogLevel : System.Byte
{/// <summary>打开所有日志记录</summary>All = 0,/// <summary>最低调试。细粒度信息事件对调试应用程序非常有帮助</summary>Debug,/// <summary>普通消息。在粗粒度级别上突出强调应用程序的运行过程</summary>Info,/// <summary>警告</summary>Warn,/// <summary>错误</summary>Error,/// <summary>严重错误</summary>Fatal,/// <summary>关闭所有日志记录</summary>Off = 0xFF
}

文件日志

文本文件日志是最重要的日志，也是XTrace.Log的默认实现。

文本文件日志是把日志逐行输出到文本文件中，每天一个文件。

如果想要独立存储某个模块的日志，可以实例化一个专属的TextFileLog对象。推荐使用Create创建。

/// <summary>每个目录的日志实例应该只有一个，所以采用静态创建</summary>
/// <param name="path">日志目录或日志文件路径</param>
/// <param name="fileFormat"></param>
/// <returns></returns>
public static TextFileLog Create(String path, String fileFormat = null);/// <summary>每个目录的日志实例应该只有一个，所以采用静态创建</summary>
/// <param name="path">日志目录或日志文件路径</param>
/// <returns></returns>
public static TextFileLog CreateFile(String path);

文件日志内部有队列、延迟关闭等复杂逻辑，强烈建议使用单例，Create可确保单例实现。

文本文件日志主要特性：

• 每天一个文件，例如 2021_06_25.log

• 每个文件最大10M，（可在core.config中配置LogFileMaxBytes），超过后产生新的日志文件，例如 2021_06_25_2.log

• 日志目录为Log子目录，（可配置LogPath）

• 日志目录中最多只保存最新100个日志文件，（可配置LogFileBackups）

• 日志等级，可配置LogLevel，默认Info，大于等于该等级才输出日志到文件

• 日志文件格式，可配置LogFileFormat，默认 {0:yyyy_MM_dd}.log，也可以按照日志等级区分目录，例如 {1}/{0:yyyy_MM_dd}.log

• 日志写入使用队列实现，避免影响应用层性能

• 如果连续5秒没有日志写入，则自动关闭日志文件句柄，此时用户可以根据需要移动或删除日志文件

这里的10M和100个，最大日志占用1G，可以有效的避免异常信息写爆磁盘！（说多都是泪……）

来看看上面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
#字段: 时间 线程ID 线程池Y/网页W/普通N/定时T 线程名/任务ID 消息内容
#Fields: Time ThreadID Kind Name Message
13:42:42.463  1 N - NewLife.Core v8.10.2021.0604 Build 2021-06-07 09:05:06 .NETCoreApp,Version=v5.0
13:42:42.465  1 N - X组件核心库 ©2002-2021 NewLife
13:42:42.466  1 N - ConsoleApp1 v1.0.0 Build 2000-01-01 .NETCoreApp,Version=v5.0
13:42:42.466  1 N - ConsoleApp1
13:42:42.466  1 N - Hello NewLife!

可以看到，日志文件非常完善，还有一个很完整的日志头。

文本日志文件格式，参考了多款微软产品，头部井号#隔开的行是注释行，用于说明情况。

通过日志头，可以了解到一下信息：

• 软件名ConsoleApp1，取自进程名

• 进程Id，是否64位进程

• 应用程序域，这个现在没有太多意义了

• 执行文件名，全路径

• 基准目录，全路径。这个非常重要，很多人的控制台程序正常，改为系统服务以后异常，很大可能性就是因为这个基准目录变成了操作系统目录。

• 临时目录，X组件有时候需要使用临时目录

• 命令行参数

• 应用类型，.NETCore里面基本上都是Console了，有点难以区分WinForm和Web

• .NET版本，CLR版本

• 操作系统、CPU等

• GC设置

• 线程池设置值。

• 日志字段格式介绍

字段格式：

• 时间，时分秒和毫秒。这里的毫秒特别重要，可以精确知道各个操作执行耗时情况

• 线程Id，如果每个日志所属线程不加以区分，在多线程环境下就会一团糟

• 线程类型，线程池Y、网页W、普通N、定时T

• 线程名/任务Id

• 日志内容

由此可见，日志组件特别适用于分析多线程问题。

设计如此详尽的日志头，主要为了能够准确记录程序的执行上下文环境，特别对于客户端应用来说尤为重要！

控制台日志

前面例程中，Main函数开头有一行 XTrace.UseConsole() ，意思是使用控制台日志。如果没有这一行，XTrace.WriteLine默认只会写入文本文件日志。加上后，同时写文件和控制台。

控制台日志ConsoleLog没有日志头，其它跟文本文件日志一样，输出时间、线程信息和日志内容。

控制台日志多了个彩色显示，不同线程以不同颜色区分，便于快速区分同一个线程的日志。受制于控制台颜色样本不足，某些情况下不同线程可能使用相同的颜色。内置10种颜色，线程Id对颜色个数取余。

除了WinForm和早期ASP.Net，否则一般都使用 XTrace.UseControle() 把日志同步输出到控制台。对应用性能有严格要求时，可以注意这一行关闭控制台日志。

切记！！！控制台日志不宜过多，否则会严重影响应用性能，因为控制台数据内部带有锁需要排队。

控件日志

对于WinForm应用来说，希望能够把日志输出到某个富文本框之中。控件日志TextControlLog为此而生！

XTrace中有扩展方法 UseWinFormControl ：

/// <summary>在WinForm控件上输出日志，主要考虑非UI线程操作</summary>
/// <remarks>不是常用功能，为了避免干扰常用功能，保持UseWinForm开头</remarks>
/// <param name="control">要绑定日志输出的WinForm控件</param>
/// <param name="useFileLog">是否同时使用文件日志，默认使用</param>
/// <param name="maxLines">最大行数</param>
public static void UseWinFormControl(this Control control, Boolean useFileLog = true, Int32 maxLines = 1000)

在码神工具 NewLife.XCoder 的网络调试工具中，FrmMain_Load 有以下代码：

txtReceive.UseWinFormControl();

这里的txtReceive是富文本框RichTextBox，负责数据接收区，同时用于显示日志。

因此，UseWinFormControl 用于把日志重定向到富文本框，第二参数useFileLog指定继续写文件日志。

网络日志

NewLife.Core 组件也支持Android和iOS开发（基于Xamarin），由于设备上的日志很不好实时查看，因而设计了网络日志。NetworkLog通过UDP协议把日志发送到局域网某个目标地址。

配置文件core.config中指定NetworkLog配置项，例如 udp://10.0.0.3:514 ，也可以使用广播地址 udp://255.255.255.255:514 。然后在开发机 10.0.0.3 上开一个码神工具，网络工具监听UDP514端口即可接收日志。

嵌入式Linux应用开发也可以使用同样办法。

网络日志降低了我们对移动应用和嵌入式应用的调试依赖。

星尘日志中心

网络日志还有一个隐藏技能，core.config 的 NetworkLog 填写http地址时，支持星尘日志中心。例如 http://star.newlifex.com:6600/log。

网络日志内部使用队列缓冲数据，按批发送到星尘服务端，服务端分表分库存储。