动手造轮子：写一个日志框架

时间 2020-01-02

标签动手轮子一个日志框架繁體版

原文原文链接

动手造轮子：写一个日志框架

Intro

日志框架有不少，好比 log4net / nlog / serilog / microsoft.extensions.logging 等，如何在切换日志框架的时候作到不用修改代码，只须要切换不一样的 loggingProvider 就能够了，最低成本的下降切换日志框架的成本，处于这个考虑本身写了一个日志框架，为不一样的日志框架写一个适配，须要用到什么日志框架，配置一下就能够了，业务代码无需变更。git

V0

最初的日志强依赖于 log4net，log4net 是我使用的第一个日志框架，因此很长一段时间都在使用它来作日志记录，可是因为是强依赖，在想换日志框架时就会很难受，大量代码要改动，不符合开放封闭的基本原则，因而就有了第一个版本的日志。github

V1

初版的日志参考了微软的日志框架的实现，大概结构以下：框架

public interface ILogHelperLogFactory
{
    ILogger CreateLogger(string categoryName);
    
    bool AddProvider(ILogHelperProvider provider);
}
public interface ILogHelperLogger
{
    bool IsEnabled(LogHelperLogLevel logLevel);
    void Log(LogHelperLogLevel logLevel, Exception exception, string message);
}
public enum LogHelperLogLevel
{
    /// <summary>
    /// All logging levels
    /// </summary>
    All = 0,

    /// <summary>
    /// A trace logging level
    /// </summary>
    Trace = 1,

    /// <summary>
    /// A debug logging level
    /// </summary>
    Debug = 2,

    /// <summary>
    /// A info logging level
    /// </summary>
    Info = 4,

    /// <summary>
    /// A warn logging level
    /// </summary>
    Warn = 8,

    /// <summary>
    /// An error logging level
    /// </summary>
    Error = 16,

    /// <summary>
    /// A fatal logging level
    /// </summary>
    Fatal = 32,

    /// <summary>
    /// None
    /// </summary>
    None = 64
}
public interface ILogHelperProvider
{
    ILogHelperLogger CreateLogger(string categoryName);
}

为了方便 Logger 的使用，定义了一些扩展方法，使得能够直接使用 logger.Info/logger.Error 等方法，扩展定义以下：ide

public static void Log(this ILogHelperLogger logger, LogHelperLevel loggerLevel, string msg) => logger.Log(loggerLevel, null, msg);

#region Info

    public static void Info(this ILogHelperLogger logger, string msg, params object[] parameters)
{
    if (parameters == null || parameters.Length == 0)
    {
        logger.Log(LogHelperLevel.Info, msg);
    }
    else
    {
        logger.Log(LogHelperLevel.Info, null, msg.FormatWith(parameters));
    }
}

public static void Info(this ILogHelperLogger logger, Exception ex, string msg) => logger.Log(LogHelperLevel.Info, ex, msg);

public static void Info(this ILogHelperLogger logger, Exception ex) => logger.Log(LogHelperLevel.Info, ex, ex?.Message);

#endregion Info
// ...其余的相似，这里就不详细展开了

若是要自定义的日志记录的话，就实现一个 ILogHelperProvider 便可，实现一个 ILogHelperProvider 就要实现一个 ILogHelperLogger ，本来强依赖的 log4net 能够实现一个 Log4NetLogHelperProvider，这样换别的日志框架的时候只须要实现对应的 ILogHelperProvider 便可，可是从功能性上来讲仍是很弱的ui

若是想要某些日志不记录，好比说，Debug 级别的日志不记录，好比说某一个 Logger 下只记录 Error 级别的日志，如今是有些吃力，只能经过 log4net 的配置来限制了，因而就有了第二个版本，增长了 LoggingFilter 能够针对 Provider/Logger/LogLevel/Exception 来设置 filter，过滤不须要记录的日志，这也是参考了微软的日志框架的 Filter，可是实现不太同样，有兴趣的小伙伴能够本身深刻研究一下。this

V2

V2 版，在 ILogFactory 的接口上增长了 AddFilter 的方法，定义以下：debug

/// <summary>   
/// Add logs filter 
/// </summary>  
/// <param name="filterFunc">filterFunc, logProviderType/categoryName/Exception, whether to write log</param>   
bool AddFilter(Func<Type, string, LogHelperLogLevel, Exception, bool> filterFunc);

而后定义了一些扩展方法来方便使用：设计

public static ILogHelperFactory WithMinimumLevel(this ILogHelperFactory logHelperFactory, LogHelperLevel logLevel)
{
    return logHelperFactory.WithFilter(level => level >= logLevel);
}

public static ILogHelperFactory WithFilter(this ILogHelperFactory logHelperFactory, Func<LogHelperLevel, bool> filterFunc)
{
    logHelperFactory.AddFilter((type, categoryName, logLevel, exception) => filterFunc.Invoke(logLevel));
    return logHelperFactory;
}

public static ILogHelperFactory WithFilter(this ILogHelperFactory logHelperFactory, Func<string, LogHelperLevel, bool> filterFunc)
{
    logHelperFactory.AddFilter((type, categoryName, logLevel, exception) => filterFunc.Invoke(categoryName, logLevel));
    return logHelperFactory;
}

public static ILogHelperFactory WithFilter(this ILogHelperFactory logHelperFactory, Func<Type, string, LogHelperLevel, bool> filterFunc)
{
    logHelperFactory.AddFilter((type, categoryName, logLevel, exception) => filterFunc.Invoke(type, categoryName, logLevel));
    return logHelperFactory;
}

public static ILogHelperFactory WithFilter(this ILogHelperFactory logHelperFactory, Func<Type, string, LogHelperLevel, Exception, bool> filterFunc)
{
    logHelperFactory.AddFilter(filterFunc);
    return logHelperFactory;
}

这样就方便了咱们只想定义针对 Logger 的 Filter 以及 Provider 的 Filter，没必要全部参数都用到，logging filter 如今已经实现了，此时已经使用了 Serilog 作日志记录有一段时间，感受 Serilog 里的一些设计很优秀，很优雅，因而想把 Serilog 里的一些设计用在本身的日志框架里，好比说：日志

Serilog 的扩展叫作 Sink，日志输出的地方，Serilog 自定义一个 Sink，很简单只须要实现一个接口，不须要再实现一个 Logger，从这点来讲，我以为 Serilog 比微软的日志框架更加优秀，并且 LogEvent 使得日志更方便的进行批量操做，有须要的能够了解一下 Serilog 的 PeriodBatching https://github.com/serilog/serilog-sinks-periodicbatchingcode
```
/// <summary>
/// A destination for log events.
/// </summary>
public interface ILogEventSink
{
    /// <summary>
    /// Emit the provided log event to the sink.
    /// </summary>
    /// <param name="logEvent">The log event to write.</param>
    void Emit(LogEvent logEvent);
}
```
Serilog 能够自定义一些 Enricher，以此来丰富记录的日志内容，好比日志的请求上下文，日志的环境等，也能够是一些固定的属性信息
MessageTemplate，其实微软的日志框架中也有相似的概念，只不过很不明显，用 Serilog 以前我也不多用，微软的日志框架能够这样用 logger.LogInfo("hello {name}", "world") 这样的写法其实就能够把第一个参数看成是 MessageTemplate 或者它内部的叫法 Format

鉴于这么多好处，因而打算将这些功能引入到个人日志框架中

V3

引入 LoggingEvent

说干就干，首先要引入一个 LogHelperLoggingEvent，对应的 Serilog 的 LogEvent，定义以下：

public class LogHelperLoggingEvent : ICloneable
{
    public string CategoryName { get; set; }

    public DateTimeOffset DateTime { get; set; }

    public string MessageTemplate { get; set; }

    public string Message { get; set; }

    public Exception Exception { get; set; }

    public LogHelperLogLevel LogLevel { get; set; }

    public Dictionary<string, object> Properties { get; set; }

    public LogHelperLoggingEvent Copy => (LogHelperLoggingEvent)Clone();

    public object Clone()
    {
        var newEvent = (LogHelperLoggingEvent)MemberwiseClone();
        if (Properties != null)
        {
            newEvent.Properties = new Dictionary<string, object>();
            foreach (var property in Properties)
            {
                newEvent.Properties[property.Key] = property.Value;
            }
        }
        return newEvent;
    }
}

Event 里定义了一个 Properties 的字典用来丰富日志的内容，另外实现了 ICloneable 接口，方便对对象的拷贝，为了强类型，增长了一个 Copy 的方法，返回一个强类型的对象

改造 LogProvider

为了减小扩展一个 ILogProvider 的复杂性，咱们要对 ILogProvider 作一个简化，只须要像扩展 Serilog 的 Sink 同样记录日志便可，不须要关心是否要建立 Logger

改造后的定义以下：

public interface ILogHelperProvider
{
    Task Log(LogHelperLoggingEvent loggingEvent);
}

(这里返回了一个 Task，可能返回类型是 void 就足够了，看本身的须要)

这样在实现 LogProvider 的时候只须要实现这个接口就能够了，不须要再实现一个 Logger 了

增长 Enricher

Enricher 定义：

public interface ILogHelperLoggingEnricher
{
    void Enrich(LogHelperLoggingEvent loggingEvent);
}

内置了一个 PropertyEnricher，方便添加一些简单的属性

internal class PropertyLoggingEnricher : ILogHelperLoggingEnricher
{
    private readonly string _propertyName;
    private readonly Func<LogHelperLoggingEvent, object> _propertyValueFactory;
    private readonly bool _overwrite;
    private readonly Func<LogHelperLoggingEvent, bool> _logPropertyPredict = null;

    public PropertyLoggingEnricher(string propertyName, object propertyValue, bool overwrite = false) : this(propertyName, (loggingEvent) => propertyValue, overwrite)
    {
    }

    public PropertyLoggingEnricher(string propertyName, Func<LogHelperLoggingEvent, object> propertyValueFactory,
                                   bool overwrite = false) : this(propertyName, propertyValueFactory, null, overwrite)
    {
    }

    public PropertyLoggingEnricher(string propertyName, Func<LogHelperLoggingEvent, object> propertyValueFactory, Func<LogHelperLoggingEvent, bool> logPropertyPredict,
                                   bool overwrite = false)
    {
        _propertyName = propertyName;
        _propertyValueFactory = propertyValueFactory;
        _logPropertyPredict = logPropertyPredict;
        _overwrite = overwrite;
    }

    public void Enrich(LogHelperLoggingEvent loggingEvent)
    {
        if (_logPropertyPredict?.Invoke(loggingEvent) != false)
        {
            loggingEvent.AddProperty(_propertyName, _propertyValueFactory, _overwrite);
        }
    }
}

为 ILogFactory 增长一个 AddEnricher 的方法

/// <summary>
/// add log enricher
/// </summary>
/// <param name="enricher">log enricher</param>
/// <returns></returns>
bool AddEnricher(ILogHelperLoggingEnricher enricher);

这样咱们在记录日志的时候就能够经过这些 Enricher 丰富 LoggingEvent 中的 Properties 了

为了方便 Property 的操做，咱们增长了一些扩展方法：

public static ILogHelperFactory WithEnricher<TEnricher>(this ILogHelperFactory logHelperFactory,
                                                        TEnricher enricher) where TEnricher : ILogHelperLoggingEnricher
{
    logHelperFactory.AddEnricher(enricher);
    return logHelperFactory;
}

public static ILogHelperFactory WithEnricher<TEnricher>(this ILogHelperFactory logHelperFactory) where TEnricher : ILogHelperLoggingEnricher, new()
{
    logHelperFactory.AddEnricher(new TEnricher());
    return logHelperFactory;
}

public static ILogHelperFactory EnrichWithProperty(this ILogHelperFactory logHelperFactory, string propertyName, object value, bool overwrite = false)
{
    logHelperFactory.AddEnricher(new PropertyLoggingEnricher(propertyName, value, overwrite));
    return logHelperFactory;
}

public static ILogHelperFactory EnrichWithProperty(this ILogHelperFactory logHelperFactory, string propertyName, Func<LogHelperLoggingEvent> valueFactory, bool overwrite = false)
{
    logHelperFactory.AddEnricher(new PropertyLoggingEnricher(propertyName, valueFactory, overwrite));
    return logHelperFactory;
}

public static ILogHelperFactory EnrichWithProperty(this ILogHelperFactory logHelperFactory, string propertyName, object value, Func<LogHelperLoggingEvent, bool> predict, bool overwrite = false)
{
    logHelperFactory.AddEnricher(new PropertyLoggingEnricher(propertyName, e => value, predict, overwrite));
    return logHelperFactory;
}

public static ILogHelperFactory EnrichWithProperty(this ILogHelperFactory logHelperFactory, string propertyName, Func<LogHelperLoggingEvent, object> valueFactory, Func<LogHelperLoggingEvent, bool> predict, bool overwrite = false)
{
    logHelperFactory.AddEnricher(new PropertyLoggingEnricher(propertyName, valueFactory, predict, overwrite));
    return logHelperFactory;
}

MessageTemplate

从上面的 LoggingEvent 中已经增长了 MessageTemplate，因而咱们引入了微软日志框架中日志的格式化，将 messageTemplate 和 parameters 转换成 Message 和 Properties，具体参考 https://github.com/WeihanLi/WeihanLi.Common/blob/276cc49cfda511f9b7b3bb8344ee52441c4a3b23/src/WeihanLi.Common/Logging/LoggingFormatter.cs

internal struct FormattedLogValue
{
    public string Msg { get; set; }

    public Dictionary<string, object> Values { get; set; }

    public FormattedLogValue(string msg, Dictionary<string, object> values)
    {
        Msg = msg;
        Values = values;
    }
}

internal static class LoggingFormatter
{
    public static FormattedLogValue Format(string msgTemplate, object[] values)
    {
        if (values == null || values.Length == 0)
            return new FormattedLogValue(msgTemplate, null);

        var formatter = new LogValuesFormatter(msgTemplate);
        var msg = formatter.Format(values);
        var dic = formatter.GetValues(values)
            .ToDictionary(x => x.Key, x => x.Value);

        return new FormattedLogValue(msg, dic);
    }
}

这样咱们就能够支持 messageTemplate 了，而后来改造一下咱们的 Logger

public interface ILogHelperLogger
{
    void Log(LogHelperLogLevel logLevel, Exception exception, string messageTemplate, params object[] parameters);

    bool IsEnabled(LogHelperLogLevel logLevel);
}

与上面不一样的是，咱们增长了 parameters

再来更新一下咱们的扩展方法，上面的扩展方法是直接使用 string.Format 的方式的格式化的，咱们这里要更新一下

public static void Info(this ILogHelperLogger logger, string msg, params object[] parameters)
{
    logger.Log(LogHelperLogLevel.Info, null, msg, parameters);
}

public static void Info(this ILogHelperLogger logger, Exception ex, string msg) => logger.Log(LogHelperLogLevel.Info, ex, msg);

public static void Info(this ILogHelperLogger logger, Exception ex) => logger.Log(LogHelperLogLevel.Info, ex, ex?.Message);

至此，功能基本完成，可是从 API 的角度来讲，感受如今的 ILogFactory过重了，这些 AddProvider/AddEnricher/AddFilter 都应该属性 ILogFactory 的内部属性，经过配置来完成，不该该成为它的接口方法，因而就有了下一版

V4

这一版主要是引入了 LoggingBuilder，经过 LoggingBuilder 来配置内部的 LogFactory 所须要的 Provider/Enricher/Filter，原来他们的配置方法和扩展方法均变成ILogHelperLoggingBuilder

public interface ILogHelperLoggingBuilder
{
    /// <summary>
    /// Adds an ILogHelperProvider to the logging system.
    /// </summary>
    /// <param name="provider">The ILogHelperProvider.</param>
    bool AddProvider(ILogHelperProvider provider);

    /// <summary>
    /// add log enricher
    /// </summary>
    /// <param name="enricher">log enricher</param>
    /// <returns></returns>
    bool AddEnricher(ILogHelperLoggingEnricher enricher);

    /// <summary>
    /// Add logs filter
    /// </summary>
    /// <param name="filterFunc">filterFunc, logProviderType/categoryName/Exception, whether to write log</param>
    bool AddFilter(Func<Type, string, LogHelperLogLevel, Exception, bool> filterFunc);

    ///// <summary>
    ///// config period batching
    ///// </summary>
    ///// <param name="period">period</param>
    ///// <param name="batchSize">batchSize</param>
    //void PeriodBatchingConfig(TimeSpan period, int batchSize);

    /// <summary>
    /// Build for LogFactory
    /// </summary>
    /// <returns></returns>
    ILogHelperFactory Build();
}

增长 logging 的配置：

public static class LogHelper
{
    private static ILogHelperFactory LogFactory { get; private set; } = NullLogHelperFactory.Instance;

    public static void ConfigureLogging(Action<ILogHelperLoggingBuilder> configureAction)
    {
        var loggingBuilder = new LogHelperLoggingBuilder();
        configureAction?.Invoke(loggingBuilder);
        LogFactory = loggingBuilder.Build();
    }

    public static ILogHelperLogger GetLogger<T>() => LogFactory.GetLogger(typeof(T));

    public static ILogHelperLogger GetLogger(Type type) => LogFactory.GetLogger(type);

    public static ILogHelperLogger GetLogger(string categoryName)
    {
        return LogFactory.CreateLogger(categoryName);
    }
}

最后的使用方式：

internal class LoggingTest
{
    private static readonly ILogHelperLogger Logger = LogHelper.GetLogger<LoggingTest>();

    public static void MainTest()
    {
        var abc = "1233";
        LogHelper.ConfigureLogging(builder =>
                                   {
                                       builder
                                           .AddLog4Net()
                                           //.AddSerilog(loggerConfig => loggerConfig.WriteTo.Console())
                                           .WithMinimumLevel(LogHelperLogLevel.Info)
                                           .WithFilter((category, level) => level > LogHelperLogLevel.Error && category.StartsWith("System"))
                                           .EnrichWithProperty("Entry0", ApplicationHelper.ApplicationName)
                                           .EnrichWithProperty("Entry1", ApplicationHelper.ApplicationName, e => e.LogLevel >= LogHelperLogLevel.Error)// 当 LogLevel 是 Error 及以上级别时才增长 Property
                                           ;
                                   });

        Logger.Debug("12333 {abc}", abc);
        Logger.Trace("122334334");
        Logger.Info($"122334334 {abc}");

        Logger.Warn("12333, err:{err}", "hahaha");
        Logger.Error("122334334");
        Logger.Fatal("12333");
    }
}

增长 LoggingEvent 还想作一个批量提交日志，如上面定义的 PeriodBatchingConfig 同样，批量同步到 Provider 可是实际使用下来，有些 provider 不支持设置日志的时间，时间是内部记录的，这样一来日志记录的时间就不许了，并且大多都不支持批量写日志，因此后面放弃了，可是若是只是用本身的扩展，不用 log4net 之类的外部的日志框架的话，我以为仍是能够作的，能够提升效率，目前主要用 Serilog 和 log4net，暂时不更新了，就先这样吧

下一版本要解决的事情

ILogProvider 记录日志返回一个 Task 感受有些鸡肋，没太大意义，后面再改一下吧
Serilog 的 Filter 是基于 LogEvent 的，后面看是否须要改一下，基于 LogEvent 的话更简洁，并且能够根据 LogEvent 内的 Properties 作过滤，因此 AddFilter 的API 能够更新一下 AddFilter(Func<LogHelperLoggingEvent, bool> filter)

动手造轮子：写一个日志框架

动手造轮子：写一个日志框架

Intro

V0

V1

V2

V3

引入 LoggingEvent

改造 LogProvider

增长 Enricher

MessageTemplate

V4

More

Reference