基於.NetCore3.1系列 —— 日誌記錄之日誌核心要素揭祕

艾三元發表於2020-08-05

一、前言

回顧:日誌記錄之日誌配置揭祕
上一篇中,我們已經瞭解了內建系統的預設配置和自定義配置的方式,在學習了配置的基礎上,我們進一步的對日誌在程式中是如何使用的深入瞭解學習。所以在這一篇中,主要是對日誌記錄的核心機制進行學習說明。

logging

二、說明

在上一篇中,我們留下了兩個問題

  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 介面

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屬性集合(根據日誌類別生成了對應實際的日誌寫入類FileLoggerConsoleLogger等),並通過字典集合的方式儲存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[]

過濾器的規則:

  1. 選擇當前記錄器型別的規則,如果沒有,請選擇未指定記錄器型別的規則
  2. 選擇最長匹配類別的規則
  3. 如果沒有與類別匹配的內容,則採用所有沒有類別的規則
  4. 如果只有一條規則,則使用它的級別和過濾器
  5. 如果有多個規則,請選擇使用最後一條。
  6. 如果沒有適用的規則,請使用全域性最低階別

通過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 來源

在上一篇中我們在對日誌配置進行說明的時候,應用程式在啟動初始化的時候會通過注入的方式CreateDefaultBuilderConfigureLoggingAddLogging

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物件以依賴注入的方式託管到集合容器中,為程式呼叫提供使用。

logging

3.2日誌記錄提供器

3.2.1 ILoggerProvider 介面

建立ILogger例項的型別,根據日誌類別名稱建立一個新的ILogger例項

public interface ILoggerProvider : IDisposable
{
    ILogger CreateLogger(string categoryName);
}

這個是具體的日誌寫入類,在工廠記錄器中我們已經提到了這個,在LoggerInformation[]中會根據日誌類別註冊對應的ILoggerProvider,在系統中我們就可以通過ILogger同時向多個途經寫入日誌資訊。(這也是對上一篇中留下的問題進行再次說明)

ILoogerProvider繼承了IDisposable介面,如果某個具體的ILoggerProvider物件需要釋放資源,就可以將相關的操作實現在Dispose方法中。

預設的實現方式為多個,官方實現的由ConsoleLoggerProviderDebugLoggerProviderEventSourceLoggerProviderEventLogLoggerProvider 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
LogerProvider

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預設的實現方式為多個,官方實現的由ConsoleLoggerDebugLoggerEventSourceLoggerEventLogLoggerTraceSourceLogger 具體日誌實現類代表不同的日誌寫入途徑。

logger

四、總結

  1. ILoggerFactoryILoggerProvider中都會通過方法建立ILogger物件,但兩者是不相同的。在工廠預設實現LoggerFactory型別中它建立的ILogger物件是由註冊到LoggerFactory物件上的所有ILoggerProvider物件提供一組 ILogger物件組合而成。而日誌提供器ILoggerProvider建立的ILogger是日誌實現輸出到對應的渠道目標,寫入日誌。

  2. 日誌記錄器ILogger中的Log()方法會記錄執行日誌,在日誌記錄器工廠ILoggerFactory和日誌記錄提供器ILoggerProvider中兩種不同的ILogger實現對應的Log()方法實現的意思也是不同的。在ILoggerFactory產生的是ILogger型別(也就是我們最終使用的Logger),其Log()方法是依次呼叫Logger中包含的LoggerInformation[]陣列中的ILogger。而ILoggerProvider產生的為各類不同的XxxLogger(也就是上面說的Logger中的LoggerInformation陣列包含的如ConsoleLogger、DebugLogger),其Log()方法是把日誌寫到具體的目標上去。

  3. 由上文可以發現,在asp.net core提供的日誌記錄的元件,通過工廠的一種方式,將日誌記錄器和日誌記錄提供器都放入到工廠這樣的容器中,滿足定義多個不同的記錄方式。在後續我們可以通過自定義ILoggerProvider整合到Logger中,實現自己需要的日誌記錄輸出方式。

  4. 如果有不對的或不理解的地方,希望大家可以多多指正,提出問題,一起討論,不斷學習,共同進步。

  5. 官方原始碼參考資料

相關文章