动手造轮子：写一个日志框架
Intro
日志框架有很多，比如 log4net / nlog / serilog / microsoft.extensions.logging 等，如何在切换日志框架的时候做到不用修改代码，只需要切换不同的 loggingProvider 就可以了，最低成本的降低切换日志框架的成本，处于这个考虑自己写了一个日志框架，为不同的日志框架写一个适配，需要用到什么日志框架，配置一下就可以了，业务代码无需变动。
V0
最初的日志强依赖于 log4net，log4net 是我使用的第一个日志框架，所以很长一段时间都在使用它来做日志记录，但是由于是强依赖，在想换日志框架时就会很难受，大量代码要改动，不符合开放封闭的基本原则，于是就有了第一个版本的日志。
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 等方法，扩展定义如下：
public static void Log(this ILogHelperLogger logger, LogHelperLevel loggerLevel, string msg) => logger.Log(loggerLevel, null, msg);
#region Infopublic 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 即可，但是从功能性上来说还是很弱的
如果想要某些日志不记录，比如说，Debug 级别的日志不记录，比如说某一个 Logger 下只记录 Error 级别的日志，现在是有些吃力，只能通过 log4net 的配置来限制了，于是就有了第二个版本，增加了 LoggingFilter 可以针对 Provider/Logger/LogLevel/Exception 来设置 filter，过滤不需要记录的日志，这也是参考了微软的日志框架的 Filter，但是实现不太一样，有兴趣的小伙伴可以自己深入研究一下。
V2
V2 版，在 ILogFactory 的接口上增加了 AddFilter 的方法，定义如下：
/// <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的PeriodBatchinghttps://github.com/serilog/serilog-sinks-periodicbatchingSerilog可以自定义一些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");}
}
More
增加 LoggingEvent 还想做一个批量提交日志，如上面定义的 PeriodBatchingConfig 一样，批量同步到 Provider 但是实际使用下来，有些 provider 不支持设置日志的时间，时间是内部记录的，这样一来日志记录的时间就不准了，而且大多都不支持批量写日志，所以后面放弃了，但是如果只是用自己的扩展，不用 log4net 之类的外部的日志框架的话，我觉得还是可以做的，可以提高效率，目前主要用 Serilog 和 log4net，暂时不更新了，就先这样吧
下一版本要解决的事情
ILogProvider记录日志返回一个 Task 感觉有些鸡肋，没太大意义，后面再改一下吧Serilog的 Filter 是基于LogEvent的，后面看是否需要改一下，基于 LogEvent 的话更简洁，而且可以根据 LogEvent 内的 Properties 做过滤，所以 AddFilter 的API 可以更新一下AddFilter(Func<LogHelperLoggingEvent,bool>filter)
Reference
https://github.com/serilog/serilog
https://github.com/serilog/serilog-sinks-periodicbatching
https://github.com/aspnet/Logging
https://github.com/aspnet/Extensions/tree/master/src/Logging
https://github.com/WeihanLi/WeihanLi.Common/tree/dev/src/WeihanLi.Common/Logging
