基於.NetCore3.1系列 —— 日誌記錄之日誌核心要素揭祕
阿新 • • 發佈：2020-08-06
# 一、前言
回顧：[日誌記錄之日誌配置揭祕](https://www.cnblogs.com/i3yuan/p/13411793.html)
在[上一篇](https://www.cnblogs.com/i3yuan/p/13411793.html)中，我們已經瞭解了內建系統的預設配置和自定義配置的方式，在學習了配置的基礎上，我們進一步的對日誌在程式中是如何使用的深入瞭解學習。所以在這一篇中，主要是對日誌記錄的核心機制進行學習說明。
# 二、說明
在上一篇中，我們留下了兩個問題
> 1. 日誌記錄的輸出可以在哪裡檢視？而又由什麼實現決定的呢？
> 2. 如何管理輸出不同的日誌呢？都有哪些方式呢？
第一個問題：在官方的實現有：Console 、Debug 、EventSource 、EventLog 、TraceSource 、Azure App Service，還有一些第三方實現，當然了我們自己也是可以實現的。 是由`ILoggerProvider `介面來決定實現的。
第二個問題：由 log Level、EventId、Logger Provider、Log filtering、Log category、Log scopes 合作解決。
由上面的問題可以發現，我們可以實現多種不同的輸出目標方式來實現寫日誌記錄，但是又如何控制在寫日誌這個操作不變的情況下，實現不同的輸入目標，這個時候我們就會想到，可以通過抽象的方式，**將寫日誌這個操作動作抽象出來，而輸出目標依賴這個動作實現具體的操作。所以當我們呼叫寫日誌操作方法的時候，由此依次呼叫對應的具體實現方法，把日誌寫到具體的目標上。**
這個過程具體是怎麼實現的呢？我們接著往下看。
# 三、開始
其實在學習之前，我們應該都已經瞭解.net core框架有一個重要的特徵就是依賴注入，通過在應用啟動時候，將各種定義好的實現型別放入到一個集合容器中，通過在執行時，將從集合容器中取出放入對應的型別中。
日誌記錄的的實現方式也離不開這個。下面讓我們一起來看看。
## 3.1 日誌記錄器工廠
### 3.1.1 ILoggerFactory 介面
```c#
public interface ILoggerFactory : IDisposable
{
ILogger CreateLogger(string categoryName);
void AddProvider(ILoggerProvider provider);
}
```
`ILoggerFactory`是日誌記錄器的工廠介面類，用於配置日誌記錄系統並建立Logger例項的類，預設實現兩個介面方法為，通過`CreateLogger()`方法來建立`ILogger`例項，（其中引數`categoryName`是一個日誌類別，用於呼叫`Logger`所在類的全名，類別指明日誌訊息是誰寫入的，一般我們將日誌所屬的的元件、服務或者訊息型別名稱作為日誌類別。） 而`AddProvider()`新增日誌記錄提供程式，向日志系統註冊新增一個`ILoggerProvider`。工廠介面類的預設實現類為`LoggerFactory `, 我們繼續往下看：
### 3.1.2 LoggerFactory 實現
**ILoggerFactory** 的預設實現是 **LoggerFactory** ,在建構函式中，如下：
```c#
public class LoggerFactory : ILoggerFactory
{
private static readonly LoggerRuleSelector RuleSelector = new LoggerRuleSelector();
private readonly Dictionary _loggers = new Dictionary(StringComparer.Ordinal);
private readonly List _providerRegistrations = new List();
private readonly object _sync = new object();
private volatile bool _disposed;
private IDisposable _changeTokenRegistration;
private LoggerFilterOptions _filterOptions;
private LoggerExternalScopeProvider _scopeProvider;
public LoggerFactory() : this(Enumerable.Empty())
{
}
public LoggerFactory(IEnumerable providers) : this(providers, new StaticFilterOptionsMonitor(new LoggerFilterOptions()))
{
}
public LoggerFactory(IEnumerable providers, LoggerFilterOptions filterOptions) : this(providers, new StaticFilterOptionsMonitor(filterOptions))
{
}
public LoggerFactory(IEnumerable providers, IOptionsMonitor filterOption)
{
foreach (var provider in providers)
{
AddProviderRegistration(provider, dispose: false);
}
_changeTokenRegistration = filterOption.OnChange(RefreshFilters);
RefreshFilters(filterOption.CurrentValue);
}
private void AddProviderRegistration(ILoggerProvider provider, bool dispose)
{
_providerRegistrations.Add(new ProviderRegistration
{
Provider = provider,
ShouldDispose = dispose
});
if (provider is ISupportExternalScope supportsExternalScope)
{
if (_scopeProvider == null)
{
_scopeProvider = new LoggerExternalScopeProvider();
}
supportsExternalScope.SetScopeProvider(_scopeProvider);
}
}
}
```
從`LoggerFactory` 中 的建構函式中可以發現，通過注入的方式獲取到`ILoggerProvider`（這個在下文中會說明），並呼叫`AddProviderRegistration`方法添加註冊程式，將`ILoggerProvider`儲存到`ProviderRegistration`集合中。
> **AddProviderRegistration** 方法：
>
> 這是一個日誌程式提供器，將`ILoggerProvider`儲存到`ProviderRegistration`集合中。當日志提供器實現 **ISupportExternalScope** 介面將單例 **LoggerExternalScopeProvider** 儲存到 provider._scopeProvider 中。
> **ProviderRegistration**集合:
>
> ```c#
> private struct ProviderRegistration
> {
> public ILoggerProvider Provider;
> public bool ShouldDispose;
> }
> ```
>
> 其中的 **ShouldDispose** 欄位標識在在`LoggerFactory`生命週期結束之後，該`ILoggerProvider`是否需要釋放。雖然在系統中`LoggerFactory`為單例模式，但是其提供了一個靜態方法生成一個可釋放的`DisposingLoggerFactory`。
在`LoggerFactory` 實現預設的介面方法`CreateLogger()`,`AddProvider()`
檢視原始碼如下：
#### CreateLogger
建立`ILogger`例項，`CreateLogger()` 原始碼如下：
```c#
public class LoggerFactory : ILoggerFactory
{
private readonly Dictionary _loggers = new Dictionary(StringComparer.Ordinal);
private readonly List _providerRegistrations = new List();
private struct ProviderRegistration
{
public ILoggerProvider Provider;
public bool ShouldDispose;
}
public ILogger CreateLogger(string categoryName)
{
if (CheckDisposed())
{
throw new ObjectDisposedException(nameof(LoggerFactory));
}
lock (_sync)
{
if (!_loggers.TryGetValue(categoryName, out var logger))
{
logger = new Logger
{
Loggers = CreateLoggers(categoryName),
};
(logger.MessageLoggers, logger.ScopeLoggers) = ApplyFilters(logger.Loggers);
_loggers[categoryName] = logger;
}
return logger;
}
}
private LoggerInformation[] CreateLoggers(string categoryName)
{
var loggers = new LoggerInformation[_providerRegistrations.Count];
for (var i = 0; i < _providerRegistrations.Count; i++)
{
loggers[i] = new LoggerInformation(_providerRegistrations[i].Provider, categoryName);
}
return loggers;
}
}
```
從原始碼可以看出，`CreateLogger`方法中，會檢測資源是否被釋放，在方法中，根據內部定義的字典集合`Dictionary _loggers`,判斷字典中是否存在對應的`Logger`屬性物件，如果不存在，會呼叫`CreateLoggers`方法根據之前註冊的的所有`ILoggerProvider `所創建出來 **ProviderRegistration** 集合來實現建立`Logger`屬性集合（根據日誌類別生成了對應實際的日誌寫入類`FileLogger`、`ConsoleLogger`等），並通過字典集合的方式儲存`categoryName`和對應的`Logger`。
> 建立 **Logger** 需要的 `LoggerInformation[]`
>
> ```c#
> internal readonly struct LoggerInformation
> {
> public LoggerInformation(ILoggerProvider provider, string category) : this()
> {
> ProviderType = provider.GetType();
> Logger = provider.CreateLogger(category);
> Category = category;
> ExternalScope = provider is ISupportExternalScope;
> }
>
> public ILogger Logger { get; }
>
> public string Category { get; }
>
> public Type ProviderType { get; }
>
> public bool ExternalScope { get; }
> }
>
> ```
>
> 根據註冊的**ILoggerProvider**，建立`ILogger` 其中的欄位說明：
>
> Logger ：具體日誌類別寫入途徑實現類
>
> Category ： 日誌類別名稱
>
> ProviderType ： 日誌提供器Type
>
> ExternalScope ：是否支援 ExternalScope
>
>
繼續看`CreateLogger`方法，在建立`Logger`之後，還呼叫了`ApplyFilters`方法：
```c#
private (MessageLogger[] MessageLoggers, ScopeLogger[] ScopeLoggers) ApplyFilters(LoggerInformation[] loggers)
{
var messageLoggers = new List();
var scopeLoggers = _filterOptions.CaptureScopes ? new List() : null;
foreach (var loggerInformation in loggers)
{
RuleSelector.Select(_filterOptions,
loggerInformation.ProviderType,
loggerInformation.Category,
out var minLevel,
out var filter);
if (minLevel != null && minLevel > LogLevel.Critical)
{
continue;
}
messageLoggers.Add(new MessageLogger(loggerInformation.Logger, loggerInformation.Category, loggerInformation.ProviderType.FullName, minLevel, filter));
if (!loggerInformation.ExternalScope)
{
scopeLoggers?.Add(new ScopeLogger(logger: loggerInformation.Logger, externalScopeProvider: null));
}
}
if (_scopeProvider != null)
{
scopeLoggers?.Add(new ScopeLogger(logger: null, externalScopeProvider: _scopeProvider));
}
return (messageLoggers.ToArray(), scopeLoggers?.ToArray());
}
```
由原始碼可以看出，
**MessageLogger[]** 集合取值：
在獲取`LoggerInformation[]`後進行傳參，進行遍歷，根據`RuleSelector`過濾器，從配置檔案中讀取對應的日誌級別，過濾器會返回獲取最低級別和對應的一條過濾規則，如果配置檔案中沒有對應的配置，預設取全域性最低級別（MinLevel）,如果讀取到的日誌級別大於`LogLevel.Critical`,則將其加入`MessageLogger[]`。
>過濾器的規則：
>
>1. 選擇當前記錄器型別的規則，如果沒有，請選擇未指定記錄器型別的規則
>2. 選擇最長匹配類別的規則
>3. 如果沒有與類別匹配的內容，則採用所有沒有類別的規則
>4. 如果只有一條規則，則使用它的級別和過濾器
>5. 如果有多個規則，請選擇使用最後一條。
>6. 如果沒有適用的規則，請使用全域性最低級別
通過`MessageLogger[]`新增訊息日誌集合
```c#
internal readonly struct MessageLogger
{
public MessageLogger(ILogger logger, string category, string providerTypeFullName, LogLevel? minLevel, Func filter)
{
Logger = logger;
Category = category;
ProviderTypeFullName = providerTypeFullName;
MinLevel = minLevel;
Filter = filter;
}
public ILogger Logger { get; }
public string Category { get; }
private string ProviderTypeFullName { get; }
public LogLevel? MinLevel { get; }
public Func Filter { get; }
public bool IsEnabled(LogLevel level)
{
if (MinLevel != null && level < MinLevel)
{
return false;
}
if (Filter != null)
{
return Filter(ProviderTypeFullName, Category, level);
}
return true;
}
}
internal readonly struct ScopeLogger
{
public ScopeLogger(ILogger logger, IExternalScopeProvider externalScopeProvider)
{
Logger = logger;
ExternalScopeProvider = externalScopeProvider;
}
public ILogger Logger { get; }
public IExternalScopeProvider ExternalScopeProvider { get; }
public IDisposable CreateScope(TState state)
{
if (ExternalScopeProvider != null)
{
return ExternalScopeProvider.Push(state);
}
return Logger.BeginScope(state);
}
}
```
在`MessageLogger[]`中帶有**MinLevel**屬性和**Filter**委託兩種過濾配置，而這兩種配置的來源，在上一章中可以看到，分別是從配置檔案（AddConfiguration）和直接使用委託（AddFilter）來進行配置的。
再由上面的`IsEnabled`方法可以看出，會先使用 `MinLevel` 過濾，再使用 `Filter` 進行過濾。所以這兩者存在優先順序。
**ScopeLogger[ ]** 取值 :
如果 `ILoggerProvider`實現了`ISupportExternalScope`介面，那麼使用`LoggerExternalScopeProvider`作為`Scope`功能的實現。反之，使用`ILogger`作為其`Scope`功能的實現。
> `LoggerExternalScopeProvider` ：
>
> - 通過 `Scope` 組成了一個單向連結串列，每次 `beginscope` 向連結串列末端增加一個新的元素，`Dispose`的時候，刪除連結串列最末端的元素。我們知道`LoggerExternalScopeProvider` 在系統中是單例模式，多個請求進來，加入執行緒池處理。通過使用`AsyncLoca`來實現不同執行緒間資料獨立。
> - 有兩個地方開啟了日誌作用域：
> - 1、通過`socket`監聽到請求後，將`KestrelConnection`加入執行緒池，執行緒池排程執行`IThreadPoolWorkItem.Execute()`方法。在這裡開啟了一次
> - 2、在構建請求上下文物件的時候(`HostingApplication.CreateContext()`)，開啟了一次
由上原始碼可以得出：在工廠記錄器類中，通過系統**依賴注入**的方式解析所有註冊的`ILoggerProvider`，然後呼叫其中的`CreateLogger`方法實現建立一個`Logger`例項物件，而這個`Logger`例項物件會根據根據註冊的`ILoggerProvider`建立需要的` LoggerInformation[]`，並將此物件作為引數進行`ApplyFilters`過濾器篩選,得到對應的最低等級或過濾規則，最後通過呼叫`Log`方法日誌記錄的時候，會遍歷`MessageLogger[]`集合，根據`logger`日誌類別對應實際不同的日誌寫入類，呼叫`ILoggerProvider`具體實現類 (可以看下文說明) 中的`Log`方法。
> AddProviderRegistration→CreateLoggers→LoggerInformation[]→ApplyFilters→MessageLogger[]→Log→ILoggerProvider ( 執行具體類中的Log方法 )
> `ILoggerFactory` **來源**：
>
> 在上一篇中我們在對日誌配置進行說明的時候，應用程式在啟動初始化的時候會通過注入的方式`CreateDefaultBuilder`→`ConfigureLogging`→`AddLogging`
>
> ```c#
> public static IServiceCollection AddLogging(this IServiceCollection services, Action configure)
> {
> if (services == null)
> {
> throw new ArgumentNullException(nameof(services));
> }
>
> services.AddOptions();
> services.TryAdd(ServiceDescriptor.Singleton());
> services.TryAdd(ServiceDescriptor.Singleton(typeof(ILogger<>), typeof(Logger<>)));
>
> services.TryAddEnumerable(ServiceDescriptor.Singleton>(
> new DefaultLoggerLevelConfigureOptions(LogLevel.Information)));
>
> configure(new LoggingBuilder(services));
> return services;
> }
> ```
>
> 實現將把`ILoggerFactory`物件以依賴注入的方式託管到集合容器中，為程式呼叫提供使用。
## 3.2日誌記錄提供器
### 3.2.1 ILoggerProvider 介面
建立`ILogger`例項的型別，根據日誌類別名稱建立一個新的`ILogger`例項
```c#
public interface ILoggerProvider : IDisposable
{
ILogger CreateLogger(string categoryName);
}
```
這個是具體的日誌寫入類，在工廠記錄器中我們已經提到了這個，在`LoggerInformation[]`中會根據日誌類別註冊對應的`ILoggerProvider`，在系統中我們就可以通過`ILogger`同時向多個途經寫入日誌資訊。（這也是對上一篇中留下的問題進行再次說明）
> `ILoogerProvider`繼承了`IDisposable`介面，如果某個具體的`ILoggerProvider`物件需要釋放資源，就可以將相關的操作實現在`Dispose`方法中。
預設的實現方式為多個，官方實現的由`ConsoleLoggerProvider` 、`DebugLoggerProvider` 、`EventSourceLoggerProvider`、`EventLogLoggerProvider `、`TraceSourceLoggerProvider`
以`ConsoleLoggerProvider`為列
```c#
[ProviderAlias("Console")]
public class ConsoleLoggerProvider : ILoggerProvider, ISupportExternalScope
{
private readonly IOptionsMonitor _options;
private readonly ConcurrentDictionary _loggers;
private readonly ConsoleLoggerProcessor _messageQueue;
private IDisposable _optionsReloadToken;
private IExternalScopeProvider _scopeProvider = NullExternalScopeProvider.Instance;
public ConsoleLoggerProvider(IOptionsMonitor options)
{
_options = options;
_loggers = new ConcurrentDictionary();
ReloadLoggerOptions(options.CurrentValue);
_optionsReloadToken = _options.OnChange(ReloadLoggerOptions);
_messageQueue = new ConsoleLoggerProcessor();
if (RuntimeInformation.IsOSPlatform(OSPlatform.Windows))
{
_messageQueue.Console = new WindowsLogConsole();
_messageQueue.ErrorConsole = new WindowsLogConsole(stdErr: true);
}
else
{
_messageQueue.Console = new AnsiLogConsole(new AnsiSystemConsole());
_messageQueue.ErrorConsole = new AnsiLogConsole(new AnsiSystemConsole(stdErr: true));
}
}
private void ReloadLoggerOptions(ConsoleLoggerOptions options)
{
foreach (var logger in _loggers)
{
logger.Value.Options = options;
}
}
public ILogger CreateLogger(string name)
{
return _loggers.GetOrAdd(name, loggerName => new ConsoleLogger(name, _messageQueue)
{
Options = _options.CurrentValue,
ScopeProvider = _scopeProvider
});
}
public void Dispose()
{
_optionsReloadToken?.Dispose();
_messageQueue.Dispose();
}
public void SetScopeProvider(IExternalScopeProvider scopeProvider)
{
_scopeProvider = scopeProvider;
foreach (var logger in _loggers)
{
logger.Value.ScopeProvider = _scopeProvider;
}
}
}
```
在`ConsoleLoggerProvider`型別定義中，標註了`ProviderAliasAttribute`特性，並設定別名為`Console`,所以在配置過濾規則的時候，可以直接使用這個名稱。`ILogger`的建立實現了具體日誌類`ConsoleLogger`。
(LogLevel logLevel, EventId eventId, TState state, Exception exception, Func formatter);
bool IsEnabled(LogLevel logLevel);
IDisposable BeginScope(TState state);
}
```
定義了三個方法，`Log()` 用於寫入日誌，`IsEnabled()`用於檢查判斷日誌級別是否開啟，`BeginScope()` 用於指日誌作用域。
### 3.3.2 Logger 實現
`ILogger`執行記錄介面類的具體實現`Logger`如下：
```c#
internal class Logger : ILogger
{
public LoggerInformation[] Loggers { get; set; }
public MessageLogger[] MessageLoggers { get; set; }
public ScopeLogger[] ScopeLoggers { get; set; }
public void Log(LogLevel logLevel, EventId eventId, TState state, Exception exception, Func formatter)
{
var loggers = MessageLoggers;
if (loggers == null)
{
return;
}
List exceptions = null;
for (var i = 0; i < loggers.Length; i++)
{
ref readonly var loggerInfo = ref loggers[i];
if (!loggerInfo.IsEnabled(logLevel))
{
continue;
}
LoggerLog(logLevel, eventId, loggerInfo.Logger, exception, formatter, ref exceptions, state);
}
if (exceptions != null && exceptions.Count > 0)
{
ThrowLoggingError(exceptions);
}
static void LoggerLog(LogLevel logLevel, EventId eventId, ILogger logger, Exception exception, Func formatter, ref List exceptions, in TState state)
{
try
{
logger.Log(logLevel, eventId, state, exception, formatter);
}
catch (Exception ex)
{
if (exceptions == null)
{
exceptions = new List();
}
exceptions.Add(ex);
}
}
}
public bool IsEnabled(LogLevel logLevel)
{
var loggers = MessageLoggers;
if (loggers == null)
{
return false;
}
List exceptions = null;
var i = 0;
for (; i < loggers.Length; i++)
{
ref readonly var loggerInfo = ref loggers[i];
if (!loggerInfo.IsEnabled(logLevel))
{
continue;
}
if (LoggerIsEnabled(logLevel, loggerInfo.Logger, ref exceptions))
{
break;
}
}
if (exceptions != null && exceptions.Count > 0)
{
ThrowLoggingError(exceptions);
}
return i < loggers.Length ? true : false;
static bool LoggerIsEnabled(LogLevel logLevel, ILogger logger, ref List exceptions)
{
try
{
if (logger.IsEnabled(logLevel))
{
return true;
}
}
catch (Exception ex)
{
if (exceptions == null)
{
exceptions = new List();
}
exceptions.Add(ex);
}
return false;
}
}
}
```
原始碼中`MessageLogger[]`在上文已經提到了，其中儲存了在配置中啟用的那些對應的`ILogger`。
> 需要注意的是，由於配置檔案更改後，會呼叫`ApplyFilters()`方法，併為`MessageLogger[]`賦新值，所以在遍歷之前，需要儲存當前值，再進行處理。否則會出現修改異常。
在系統中統一寫入日誌的入口，通過日誌等級作為引數呼叫其`IsEnabled`方法來確定當前日誌是否執行對應具體日誌的實現類，當符合條件執行具體日誌輸出到對應的寫入途徑中會呼叫對應的`Log`方法（需要提供一個`EventId`來標識當前日誌事件）
> `ILogger`預設的實現方式為多個，官方實現的由`ConsoleLogger` 、`DebugLogger` 、`EventSourceLogger`、`EventLogLogger`、`TraceSourceLogger` 具體日誌實現類代表不同的日誌寫入途徑。
# 二、說明
在上一篇中，我們留下了兩個問題
> 1. 日誌記錄的輸出可以在哪裡檢視？而又由什麼實現決定的呢？
> 2. 如何管理輸出不同的日誌呢？都有哪些方式呢？
第一個問題：在官方的實現有：Console 、Debug 、EventSource 、EventLog 、TraceSource 、Azure App Service，還有一些第三方實現，當然了我們自己也是可以實現的。 是由`ILoggerProvider `介面來決定實現的。
第二個問題：由 log Level、EventId、Logger Provider、Log filtering、Log category、Log scopes 合作解決。
由上面的問題可以發現，我們可以實現多種不同的輸出目標方式來實現寫日誌記錄，但是又如何控制在寫日誌這個操作不變的情況下，實現不同的輸入目標，這個時候我們就會想到，可以通過抽象的方式，**將寫日誌這個操作動作抽象出來，而輸出目標依賴這個動作實現具體的操作。所以當我們呼叫寫日誌操作方法的時候，由此依次呼叫對應的具體實現方法，把日誌寫到具體的目標上。**
這個過程具體是怎麼實現的呢？我們接著往下看。
# 三、開始
其實在學習之前，我們應該都已經瞭解.net core框架有一個重要的特徵就是依賴注入，通過在應用啟動時候，將各種定義好的實現型別放入到一個集合容器中，通過在執行時，將從集合容器中取出放入對應的型別中。
日誌記錄的的實現方式也離不開這個。下面讓我們一起來看看。
## 3.1 日誌記錄器工廠
### 3.1.1 ILoggerFactory 介面
```c#
public interface ILoggerFactory : IDisposable
{
ILogger CreateLogger(string categoryName);
void AddProvider(ILoggerProvider provider);
}
```
`ILoggerFactory`是日誌記錄器的工廠介面類，用於配置日誌記錄系統並建立Logger例項的類，預設實現兩個介面方法為，通過`CreateLogger()`方法來建立`ILogger`例項，（其中引數`categoryName`是一個日誌類別，用於呼叫`Logger`所在類的全名，類別指明日誌訊息是誰寫入的，一般我們將日誌所屬的的元件、服務或者訊息型別名稱作為日誌類別。） 而`AddProvider()`新增日誌記錄提供程式，向日志系統註冊新增一個`ILoggerProvider`。工廠介面類的預設實現類為`LoggerFactory `, 我們繼續往下看：
### 3.1.2 LoggerFactory 實現
**ILoggerFactory** 的預設實現是 **LoggerFactory** ,在建構函式中，如下：
```c#
public class LoggerFactory : ILoggerFactory
{
private static readonly LoggerRuleSelector RuleSelector = new LoggerRuleSelector();
private readonly Dictionary