.Net Core日志記錄的核心機制
一、前言
回顧:日志記錄之日志配置揭秘
在上一篇中,我們已經瞭解瞭內置系統的默認配置和自定義配置的方式,在學習瞭配置的基礎上,我們進一步的對日志在程序中是如何使用的深入瞭解學習。所以在這一篇中,主要是對日志記錄的核心機制進行學習說明。
二、說明
在上一篇中,我們留下瞭兩個問題
日志記錄的輸出可以在哪裡查看?而又由什麼實現決定的呢?
如何管理輸出不同的日志呢?都有哪些方式呢?
第一個問題:在官方的實現有: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 接口
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 ,在構造函數中,如下:
public class LoggerFactory : ILoggerFactory { private static readonly LoggerRuleSelector RuleSelector = new LoggerRuleSelector(); private readonly Dictionary<string, Logger> _loggers = new Dictionary<string, Logger>(StringComparer.Ordinal); private readonly List<ProviderRegistration> _providerRegistrations = new List<ProviderRegistration>(); private readonly object _sync = new object(); private volatile bool _disposed; private IDisposable _changeTokenRegistration; private LoggerFilterOptions _filterOptions; private LoggerExternalScopeProvider _scopeProvider; public LoggerFactory() : this(Enumerable.Empty<ILoggerProvider>()) { } public LoggerFactory(IEnumerable<ILoggerProvider> providers) : this(providers, new StaticFilterOptionsMonitor(new LoggerFilterOptions())) { } public LoggerFactory(IEnumerable<ILoggerProvider> providers, LoggerFilterOptions filterOptions) : this(providers, new StaticFilterOptionsMonitor(filterOptions)) { } public LoggerFactory(IEnumerable<ILoggerProvider> providers, IOptionsMonitor<LoggerFilterOptions> 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集合:
private struct ProviderRegistration { public ILoggerProvider Provider; public bool ShouldDispose; }
其中的 ShouldDispose 字段標識在在
LoggerFactory
生命周期結束之後,該ILoggerProvider
是否需要釋放。雖然在系統中LoggerFactory
為單例模式,但是其提供瞭一個靜態方法生成一個可釋放的DisposingLoggerFactory
。
在LoggerFactory
實現默認的接口方法CreateLogger()
,AddProvider()
查看源碼如下:
CreateLogger
創建ILogger
實例,CreateLogger()
源碼如下:
public class LoggerFactory : ILoggerFactory { private readonly Dictionary<string, Logger> _loggers = new Dictionary<string, Logger>(StringComparer.Ordinal); private readonly List<ProviderRegistration> _providerRegistrations = new List<ProviderRegistration>(); 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<string, Logger> _loggers
,判斷字典中是否存在對應的Logger
屬性對象,如果不存在,會調用CreateLoggers
方法根據之前註冊的的所有ILoggerProvider
所創建出來 ProviderRegistration 集合來實現創建Logger
屬性集合(根據日志類別生成瞭對應實際的日志寫入類FileLogger
、ConsoleLogger
等),並通過字典集合的方式保存categoryName
和對應的Logger
。
創建 Logger 需要的
LoggerInformation[]
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
方法:
private (MessageLogger[] MessageLoggers, ScopeLogger[] ScopeLoggers) ApplyFilters(LoggerInformation[] loggers) { var messageLoggers = new List<MessageLogger>(); var scopeLoggers = _filterOptions.CaptureScopes ? new List<ScopeLogger>() : 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[]
。
過濾器的規則:
選擇當前記錄器類型的規則,如果沒有,請選擇未指定記錄器類型的規則
選擇最長匹配類別的規則
如果沒有與類別匹配的內容,則采用所有沒有類別的規則
如果隻有一條規則,則使用它的級別和過濾器
如果有多個規則,請選擇使用最後一條。
如果沒有適用的規則,請使用全局最低級別
通過MessageLogger[]
添加消息日志集合
internal readonly struct MessageLogger { public MessageLogger(ILogger logger, string category, string providerTypeFullName, LogLevel? minLevel, Func<string, string, LogLevel, bool> 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<string, string, LogLevel, bool> 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>(TState state) { if (ExternalScopeProvider != null) { return ExternalScopeProvider.Push(state); } return Logger.BeginScope<TState>(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
public static IServiceCollection AddLogging(this IServiceCollection services, Action<ILoggingBuilder> configure) { if (services == null) { throw new ArgumentNullException(nameof(services)); } services.AddOptions(); services.TryAdd(ServiceDescriptor.Singleton<ILoggerFactory, LoggerFactory>()); services.TryAdd(ServiceDescriptor.Singleton(typeof(ILogger<>), typeof(Logger<>))); services.TryAddEnumerable(ServiceDescriptor.Singleton<IConfigureOptions<LoggerFilterOptions>>( new DefaultLoggerLevelConfigureOptions(LogLevel.Information))); configure(new LoggingBuilder(services)); return services; }
實現將把
ILoggerFactory
對象以依賴註入的方式托管到集合容器中,為程序調用提供使用。
3.2日志記錄提供器
3.2.1 ILoggerProvider 接口
創建ILogger
實例的類型,根據日志類別名稱創建一個新的ILogger
實例
public interface ILoggerProvider : IDisposable { ILogger CreateLogger(string categoryName); }
這個是具體的日志寫入類,在工廠記錄器中我們已經提到瞭這個,在LoggerInformation[]
中會根據日志類別註冊對應的ILoggerProvider
,在系統中我們就可以通過ILogger
同時向多個途經寫入日志信息。(這也是對上一篇中留下的問題進行再次說明)
ILoogerProvider
繼承瞭IDisposable
接口,如果某個具體的ILoggerProvider
對象需要釋放資源,就可以將相關的操作實現在Dispose
方法中。
默認的實現方式為多個,官方實現的由ConsoleLoggerProvider
、DebugLoggerProvider
、EventSourceLoggerProvider
、EventLogLoggerProvider
、TraceSourceLoggerProvider
以ConsoleLoggerProvider
為列
[ProviderAlias("Console")] public class ConsoleLoggerProvider : ILoggerProvider, ISupportExternalScope { private readonly IOptionsMonitor<ConsoleLoggerOptions> _options; private readonly ConcurrentDictionary<string, ConsoleLogger> _loggers; private readonly ConsoleLoggerProcessor _messageQueue; private IDisposable _optionsReloadToken; private IExternalScopeProvider _scopeProvider = NullExternalScopeProvider.Instance; public ConsoleLoggerProvider(IOptionsMonitor<ConsoleLoggerOptions> options) { _options = options; _loggers = new ConcurrentDictionary<string, ConsoleLogger>(); 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
。
3.3 日志記錄器
3.3.1 ILogger 接口
表示用於執行日志記錄的類型,是系統中寫入日志的統一入口。
public interface ILogger { void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception exception, Func<TState, Exception, string> formatter); bool IsEnabled(LogLevel logLevel); IDisposable BeginScope<TState>(TState state); }
定義瞭三個方法,Log<TState>()
用於寫入日志,IsEnabled()
用於檢查判斷日志級別是否開啟,BeginScope()
用於指日志作用域。
3.3.2 Logger 實現
ILogger
執行記錄接口類的具體實現Logger
如下:
internal class Logger : ILogger { public LoggerInformation[] Loggers { get; set; } public MessageLogger[] MessageLoggers { get; set; } public ScopeLogger[] ScopeLoggers { get; set; } public void Log<TState>(LogLevel logLevel, EventId eventId, TState state, Exception exception, Func<TState, Exception, string> formatter) { var loggers = MessageLoggers; if (loggers == null) { return; } List<Exception> 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<TState, Exception, string> formatter, ref List<Exception> exceptions, in TState state) { try { logger.Log(logLevel, eventId, state, exception, formatter); } catch (Exception ex) { if (exceptions == null) { exceptions = new List<Exception>(); } exceptions.Add(ex); } } } public bool IsEnabled(LogLevel logLevel) { var loggers = MessageLoggers; if (loggers == null) { return false; } List<Exception> 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<Exception> exceptions) { try { if (logger.IsEnabled(logLevel)) { return true; } } catch (Exception ex) { if (exceptions == null) { exceptions = new List<Exception>(); } exceptions.Add(ex); } return false; } } }
源碼中MessageLogger[]
在上文已經提到瞭,其中保存瞭在配置中啟用的那些對應的ILogger
。
需要註意的是,由於配置文件更改後,會調用
ApplyFilters()
方法,並為MessageLogger[]
賦新值,所以在遍歷之前,需要保存當前值,再進行處理。否則會出現修改異常。
在系統中統一寫入日志的入口,通過日志等級作為參數調用其IsEnabled
方法來確定當前日志是否執行對應具體日志的實現類,當符合條件執行具體日志輸出到對應的寫入途徑中會調用對應的Log
方法(需要提供一個EventId
來標識當前日志事件)
ILogger
默認的實現方式為多個,官方實現的由ConsoleLogger
、DebugLogger
、EventSourceLogger
、EventLogLogger
、TraceSourceLogger
具體日志實現類代表不同的日志寫入途徑。
四、總結
- 在
ILoggerFactory
和ILoggerProvider
中都會通過方法創建ILogger對象,但兩者是不相同的。在工廠默認實現LoggerFactory
類型中它創建的ILogger對象是由註冊到LoggerFactory
對象上的所有ILoggerProvider對象提供一組 ILogger對象組合而成。而日志提供器ILoggerProvider
創建的ILogger是日志實現輸出到對應的渠道目標,寫入日志。 - 日志記錄器
ILogger
中的Log()方法會記錄執行日志,在日志記錄器工廠ILoggerFactory
和日志記錄提供器ILoggerProvider
中兩種不同的ILogger
實現對應的Log()
方法實現的意思也是不同的。在ILoggerFactory
產生的是ILogger
類型(也就是我們最終使用的Logger
),其Log()方法是依次調用Logger
中包含的LoggerInformation[]
數組中的ILogger
。而ILoggerProvider
產生的為各類不同的XxxLogger(也就是上面說的Logger
中的LoggerInformation
數組包含的如ConsoleLogger、DebugLogger
),其Log()方法是把日志寫到具體的目標上去。 - 由上文可以發現,在asp.net core提供的日志記錄的組件,通過工廠的一種方式,將日志記錄器和日志記錄提供器都放入到工廠這樣的容器中,滿足定義多個不同的記錄方式。在後續我們可以通過自定義
ILoggerProvider
集成到Logger
中,實現自己需要的日志記錄輸出方式。 - 如果有不對的或不理解的地方,希望大傢可以多多指正,提出問題,一起討論,不斷學習,共同進步。
- 官方源碼 和 參考資料
到此這篇關於.Net Core日志記錄核心機制的文章就介紹到這瞭。希望對大傢的學習有所幫助,也希望大傢多多支持WalkonNet。
推薦閱讀:
- .Net Core日志記錄之自定義日志組件
- .net core日志系統相關總結
- .Net Core使用Logger實現log寫入本地文件系統
- ASP.NET Core的日志系統介紹
- ASP.NET Core實現文件上傳和下載