手写日志框架：从ILogger到Provider与异步队列的完整实践

1. 日志报警没响，关键日志却丢了：为什么建议你把日志框架拆开看看

1.1 只会用 ILogger 的尴尬

我在排查线上问题的时候，最怕的不是报错，而是连日志都没有。代码里明明写了_logger.LogInformation("开始处理订单:{orderId}")，运行期日志里却一片安静，既没有报错，也没有记录。花两小时翻代码，最后发现不是业务逻辑错了，而是日志框架的过滤配置、Provider 注册顺序和 Category 不对，把我们要的信息全部吞掉了。经历过那次之后，我就不再满足于“会用 ILogger”，而是认真研究日志框架背后到底是怎么流转的，并且动手写了一套简化版来验证自己的理解。

很多人对日志框架的认知停留在“调ILogger接口方法”这一层。写业务的时候确实够用，但一旦涉及诊断，问题就来了：为什么日志没输出？为什么同一个消息打了两遍？为什么业务线程被日志拖到超时？这些问题不把框架内部结构看清楚，就只能靠猜。靠猜排查问题，效率极低。

1.2 拆开框架的三个直接收益

先说清楚，这篇文章不是带着你把官方源码一行行读完，而是通过手写一个简化但结构完整的日志框架，把 LoggerFactory、Logger、Provider、LogLevel、异步写入这些核心概念全部串起来。我自己实践下来的感觉是：写一遍，比读十遍文档都管用。

收益一，是可控性。你知道日志从调用到落地经过哪些环节，出问题就能快速定位是在生成环节、过滤环节还是输出环节丢的。

收益二，是诊断能力。线上看到“日志重复”“日志丢失”“日志级别不对”，你不会再一头雾水，脑子里会有一张完整的流转图。

收益三，是性能意识。手写过程中你会自然而然地碰到“同步写文件卡业务线程”这个坎，然后理解为什么生产环境的日志系统要引入队列，为什么有些日志宁可丢弃也不能阻塞主流程。这些经验，是单纯调 API 学不到的。

2. 日志框架的核心抽象：Logger、Level 与 Provider 的关系

2.1 三个角色分别干什么

先做一个生活化类比。你去银行办事，门口有接待员问你办什么业务，然后帮你取号、引导你去对应柜台。接待员不负责真正处理业务，但他决定你去哪个窗口。柜台里的柜员才真正干活。

在日志框架里，ILogger就是那个接待员，它接收你“记一条日志”的请求，然后按照规则把请求分发给一组“柜员”。这组柜员就是ILoggerProvider，也就是真正的输出端，Console、文件、数据库、远程日志服务都是 Provider 在干活。

那ILoggerFactory是什么？它是银行的大堂经理，负责管理和分配接待员。工厂内部维护着一张“接待员名单”，你告诉它你想记录哪个模块的日志（Category），它给你一个对应名字的ILogger。同一个 Category 会复用同一个 Logger 实例，避免频繁创建对象的开销。

很多初学者会把 Logger 和 Provider 混为一谈，觉得ILogger就是输出日志的。其实它只是一个转发者，真正决定日志写到哪里、用什么格式写的，是 Provider。搞清楚这一层，后面理解“日志为什么没输出”就会容易很多。

2.2 日志从调用到落地的完整流转

一条日志的完整生命周期，可以拆成四个环节。

第一个环节是你调用logger.Info("xxx")或logger.LogInformation("xxx")。注意，此刻日志还没有被输出，它只是被包装成了一个消息对象。

第二个环节是日志框架判断这条日志要不要记录。判断依据是 LogLevel，也就是 Trace、Debug、Information、Warning、Error、Critical 这几个级别。每个框架通常都有一个最小日志级别，比如配置了MinLevel = Warning，那么 Warning 以下的日志直接丢弃。

第三个环节是把消息分发给所有注册的 Provider。这里要留意，日志框架是“广播”模式：注册了两个 Provider，同一条日志就会被写两次，一个写 Console，一个写文件。

第四个环节是 Provider 真正把消息格式化并输出到目标介质。到这里，日志才算落地。

这四步里每一步都可能出问题。最小日志级别太高，日志会在第一步被丢；Provider 没注册成功，到了第三步就没人接收；格式化顺序写错，第四步输出的内容就是乱的。后面诊断部分我详细展开。

2.3 从最原始的 Console 输出反推抽象边界

假如没有框架，你可能会这么写：

public static class LogHelper { public static void Info(string message) { Console.WriteLine($"[INFO] {DateTime.Now:yyyy-MM-dd HH:mm:ss} {message}"); } }

这个 helper 在小型项目里够用，但问题很多：硬编码了输出端，想改成写文件就得改工具类；只有一个全局方法，没法按模块分开控制级别；一旦代码里到处直接调用 Console，后面想接入远程日志服务，就是一场噩梦。

于是你自然会想到抽接口，把“记录日志的动作”和“输出的目的地”分开。这就诞生了两个核心接口：一个是开发者直接面对的 Logger 接口，一个是负责输出的 Provider（Sink）接口。而工厂类负责把两者组装起来。整个日志框架的骨架，其实就是这三个角色和两个接口之间的协作关系。

public interface ILogSink { bool IsEnabled(LogLevel level); void Write(LogLevel level, string category, string message); }

Provider 之所以需要单独实现IsEnabled，是因为不同输出端可以有不同的策略。比如文件日志可能只想记录 Warning 以上，Console 却希望什么都打出来。这种差异如果只在工厂层面统一过滤，就做不到。

3. 手写第一版：Provider 模式与 Category 隔离

3.1 接口设计：先定协议再写实现

开始写代码之前，我强烈建议先把接口定下来。协议定了，后面扩展组件就是增量的活。

我需要四个东西：LogLevel枚举、ILogSink接口（输出端）、IAppLogger接口（开发者入口）、AppLoggerFactory（组装工厂）。

public enum LogLevel { Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5 } public interface ILogSink { bool IsEnabled(LogLevel level); void Write(LogLevel level, string category, string message); } public interface IAppLogger { void Log(LogLevel level, string message); void Info(string message); void Warning(string message); void Error(string message, Exception? exception = null); }

这里有个关键设计：IAppLogger是面向业务代码的，先不暴露 Category，因为业务代码不该关心这个。Category 由工厂在创建 Logger 时注入。这样不同模块拿到的 Logger 天然就带上了自己的身份标识，输出时可以区分来源。

3.2 工厂接管 Provider 注册

接下来是工厂和默认 Logger 的实现。

public sealed class AppLoggerFactory { private readonly object _gate = new(); private readonly List<ILogSink> _sinks = new(); private readonly Dictionary<string, IAppLogger> _loggers = new(); public void AddSink(ILogSink sink) { lock (_gate) { _sinks.Add(sink); } } public IAppLogger CreateLogger(string category) { lock (_gate) { if (_loggers.TryGetValue(category, out var existing)) { return existing; } var logger = new AppLogger(_sinks, category); _loggers[category] = logger; return logger; } } } public sealed class AppLogger : IAppLogger { private readonly ILogSink[] _sinks; private readonly string _category; private readonly LogLevel _minLevel; public AppLogger(IList<ILogSink> sinks, string category, LogLevel minLevel = LogLevel.Trace) { _category = category; _minLevel = minLevel; _sinks = sinks.ToArray(); } public void Log(LogLevel level, string message) { if (level < _minLevel) { return; } var line = $"{DateTime.Now:yyyy-MM-dd HH:mm:ss.fff} [{level}] [{_category}] {message}"; foreach (var sink in _sinks) { if (sink.IsEnabled(level)) { sink.Write(level, _category, line); } } } public void Info(string message) => Log(LogLevel.Information, message); public void Warning(string message) => Log(LogLevel.Warning, message); public void Error(string message, Exception? exception = null) => Log(LogLevel.Error, exception is null ? message : $"{message}{Environment.NewLine}{exception}"); }

这里有一个细节值得展开：为什么AppLogger接收的是_sinks.ToArray()这个快照？因为_sinks可能被后续AddSink修改，而 Logger 实例已经被业务代码拿着了。用数组快照保证遍历的时候不会出现并发修改异常，同时每次创建 Logger 时都把当前已有的 Sink 固定下来。这也是“Logger 持有 Provider 集合”的一种具体实现方式。

3.3 为什么官方把 Logger 又包了一层 ILogger

很多人用官方抽象库时会困惑：有了ILoggerFactory.CreateLogger("CategoryName")，为什么还要ILogger<T>？直接ILogger<T>拿到的 Logger，Category 自动就是typeof(T).FullName。

这个设计的好处是强类型和免拼字符串。你用ILogger<OrderService>的时候，Category 自动是OrderService的命名空间加类名，不会出现手写字符串拼错的问题。而且在依赖注入容器里，ILogger<T>可以直接注册成泛型，解析的时候框架自动帮你把 T 的类型名作为 Category。

我手写的这个简化版本没有加泛型包装，但思路是通用的：Category 就是日志的分组标签，你既可以手写字符串，也可以用类型全名充当。诊断的时候看到[OrderService]标签，立刻就知道是哪段代码打的日志，这就是 Category 隔离的意义。

3.4 写一个控制台 Sink 验证跑通

public sealed class ConsoleSink : ILogSink { private readonly LogLevel _minLevel; public ConsoleSink(LogLevel minLevel = LogLevel.Trace) { _minLevel = minLevel; } public bool IsEnabled(LogLevel level) => level >= _minLevel; public void Write(LogLevel level, string category, string message) { var previousColor = Console.ForegroundColor; Console.ForegroundColor = level >= LogLevel.Warning ? ConsoleColor.Red : level == LogLevel.Information ? ConsoleColor.Cyan : ConsoleColor.Gray; Console.WriteLine(message); Console.ForegroundColor = previousColor; } }

然后组装：

var factory = new AppLoggerFactory(); factory.AddSink(new ConsoleSink(LogLevel.Debug)); var orderLogger = factory.CreateLogger("OrderService"); orderLogger.Info("订单已创建，订单号:{0}", "...");

跑到这里，一个可用的手写日志框架就算跑通了。它能按 Category 区分来源，能按 Level 过滤，后续加文件输出也不需要改业务代码。套用一句行话：面向接口编程的好处，在这一刻就体现出来了。

4. 向多 Provider 演进：Console 与 File 共存

4.1 新增文件 Sink，Logger 一行没改

现在我要加一个文件输出端。做法很简单：实现ILogSink接口，然后在工厂里注册。

public sealed class FileSink : ILogSink, IDisposable { private readonly StreamWriter _writer; private readonly LogLevel _minLevel; private long _writeCount; public FileSink(string filePath, LogLevel minLevel = LogLevel.Warning) { _minLevel = minLevel; var stream = new FileStream(filePath, FileMode.Append, FileAccess.Write, FileShare.Read); _writer = new StreamWriter(stream) { AutoFlush = true }; } public bool IsEnabled(LogLevel level) => level >= _minLevel; public void Write(LogLevel level, string category, string message) { _writer.WriteLine(message); Interlocked.Increment(ref _writeCount); } public void Dispose() { _writer.Flush(); _writer.Dispose(); } }

注意构造函数里的FileShare.Read。这个参数的意思是，文件写入时允许其他进程以只读方式打开这个文件，比如你用记事本或日志采集 agent 查看日志而不会直接报“文件被占用”。这个细节对运维场景特别重要，我用第一次实验时没加，结果日志 agent 读取文件一直失败。

注册方式没有任何变化：

factory.AddSink(new ConsoleSink(LogLevel.Debug)); factory.AddSink(new FileSink("logs/app.log", LogLevel.Warning));

现在同样一条 Info 日志，会同时出现在控制台和文件里；而 Warning 以下的日志只会进控制台，不会进文件。这种“不同输出端有不同的详细程度”的需求，用 Provider 模式做起来非常干净。新增输出能力，原有代码一行不改，这就是开闭原则的实际例子。

4.2 格式化与写入时序的坑

多 Provider 共存后，第一个坑就是格式不统一。比如 ConsoleSink 里我用的是“时间 + 级别 + Category + 消息”的格式，而 FileSink 想输出成 JSON 方便日志分析系统解析。怎么办？

常见的做法是引入一个格式化器（Formatter），把“格式化消息”这个动作从 Provider 里剥离开。格式化器负责把日志对象渲染成字符串，Provider 只负责把字符串写到目的地。稍微复杂一点的框架还会针对不同 Provider 注册不同的格式器。官方的 Console Provider 和 OpenTelemetry Provider 就是各自处理各自的格式。

我手写实现时为了简单，直接让 Logger 在分发前先统一拼好字符串。演示没有问题，但你心里要清楚：真实项目里日志会携带结构化信息（对象、事件 ID、异常堆栈），把这些信息转成字符串应该尽量延后，最好在输出端再做格式化。这样做的好处很大，比如想输出 JSON 格式时，你可以拿到原始字段而不是去解析拼好的字符串。

另一个坑是写文件的缓冲问题。如果不做AutoFlush，日志会积在 StreamWriter 的内存缓冲区里，程序崩溃时缓冲区内容直接丢光。做了AutoFlush，每次写都会刷盘，性能又会受影响。这个矛盾是日志框架性能优化的核心话题之一，下一节专门讲。

4.3 官方框架还多做了哪些事

到了这一步，我手写的框架和官方抽象库的结构已经很接近了。官方本质上就是：ILoggerFactory管 Provider 集合，Logger是分发器，Provider是输出端，外加一套 Filter 规则和一个依赖注入容器。

但官方还有两个我暂时没做的东西，值得你知道。

一是日志作用域（Scope）。它是IDisposable，用来给一批日志附加上下文信息。比如处理某个请求时，你希望这个请求过程中打的所有日志都带上同一个TraceId。官方用BeginScope实现，底层是在 Provider 内部维护一个作用域栈。我手写的版本没有做，因为 scope 的核心难点是对线程上下文的传播，代码量不小。

二是日志源生成器。官方推荐用[LoggerMessage]特性让编译期生成高性能的日志调用代码，避免字符串模板的装箱和格式化开销。这个属于性能优化，了解即可，不影响理解原理。

5. 性能与稳定性：异步队列和日志丢弃策略

5.1 同步写 IO 为什么扛不住

把日志写到控制台还好，如果写到文件、网络或者数据库，IO 延迟是毫秒到几十毫秒级别，可能出现比你业务逻辑还慢的情况。

打个比方：你的业务线程像一辆送餐车，正常跑一趟 5 分钟。现在每送一单都要求司机先绕道 500 公里外取个东西，送餐效率会瞬间崩掉。同步写日志就是这个意思——Logger是在业务线程里调用的，Provider同步写文件，等于让业务线程替日志服务干活。

解决思路很清晰：把“生产日志”和“输出日志”解耦。业务线程只把日志塞进一个队列，立刻返回；后台专门开一个线程（或几个线程）消费队列，真正去写文件、发网络。这就是生产者-消费者模型。

5.2 用 Channel 实现生产者-消费者模型

.NET 里实现这个模型，我推荐用System.Threading.Channels。它是官方提供的并发队列，设计目标就是高性能的生产者-消费者场景。

public sealed class AsyncFileSink : ILogSink, IDisposable { private readonly Channel<LogEntry> _channel; private readonly Task _worker; private readonly StreamWriter _writer; private bool _disposed; public AsyncFileSink(string filePath, int capacity = 1024) { var options = new BoundedChannelOptions(capacity) { FullMode = BoundedChannelFullMode.DropWrite, SingleReader = true }; _channel = Channel.CreateBounded<LogEntry>(options); _writer = new StreamWriter(new FileStream(filePath, FileMode.Append, FileAccess.Write, FileShare.Read)); _worker = Task.Factory.StartNew(ProcessQueueAsync, CancellationToken.None, TaskCreationOptions.LongRunning, TaskScheduler.Default); } public bool IsEnabled(LogLevel level) => true; public void Write(LogLevel level, string category, string message) { var entry = new LogEntry(level, category, message); // 队列满了直接丢弃，并统计丢弃数量 if (!_channel.Writer.TryWrite(entry)) { Interlocked.Increment(ref _droppedCount); } } private async Task ProcessQueueAsync() { await foreach (var entry in _channel.Reader.ReadAllAsync()) { await _writer.WriteLineAsync(entry.ToString()); } } public void Dispose() { if (_disposed) return; _disposed = true; _channel.Writer.TryComplete(); _worker.Wait(TimeSpan.FromSeconds(5)); _writer.Flush(); _writer.Dispose(); } } public sealed record LogEntry(LogLevel Level, string Category, string Message) { public override string ToString() => $"{DateTime.Now:yyyy-MM-dd HH:mm:ss.fff} [{Level}] [{Category}] {Message}"; }

这个版本有一个我没在代码里标注的动作：BoundedChannelFullMode.DropWrite表示队列满的时候，新的日志条目会被直接丢弃。对日志系统来说，丢失一部分非关键日志，比阻塞业务线程导致请求超时要划算得多。这个取舍，每个项目要根据日志重要性自己定。

5.3 队列满了怎么办：背压与降级

写到这就要提一个决策点：队列容量设多少，满了以后是丢弃还是等待。

设太多，内存压力大。假设置成 10 万条，每条日志字符串平均 200 字节，那就是 20 MB 起步，如果日志里还带异常堆栈，轻松上百 MB。设太少，日志频繁丢弃，排查问题时可能正好丢掉关键信息。

我的经验是分场景：关键业务日志用有界队列加等待策略，宁可让写日志的线程等一下，也不能丢；普通调试日志用有界队列加丢弃策略，记录一个丢弃计数器，等排查性能问题时再去看计数器数值。

这里还有一个容易忽略的收尾动作：进程要正常退出时，必须先TryComplete让生产者停止写入，再等消费者把队列里剩余的日志全部排空。我见过不少自研日志模块崩溃时丢日志，原因就是进程 exiting 事件里直接Environment.Exit(0)，后台线程来不及 flush 就死了。

5.4 Error 级别需要特殊对待吗

日志系统常常会给 Error、Critical 级别开绿色通道。原因很直白：Error 是出大事的证据，丢失代价最高。有些框架的做法是单独开一个高优先级队列，或者干脆对 Error 级别退化为同步写，确保它一定落盘。

我个人的建议：框架可以默认只对 Critical 级别同步写，Error 级别走异步但容量较小的专用队列并且不丢弃。这样既保证了关键错误可追溯，又不至于让所有错误日志都拖慢业务。至于在官方框架层面有没有这个能力，不同版本不同系统实现不一，但原理都是这套。

6. 诊断实战：从“日志没输出”到“日志重复输出”

6.1 日志没输出：三级过滤逐个查

现在回到开头那个场景：日志没打出来。有了前面的原理，排查链路就很清晰。我会按下面的顺序逐层检查。

第一层：Logger 实例有没有正确拿到。如果你是手写工厂，检查是不是每次CreateLogger都传了不同的字符串，导致你以为在用同一个 Category，实际拿到了两个不同的 Logger。如果你用的是官方抽象库，检查依赖注入容器里有没有在构造函数里要求ILoggerFactory却忘了注册。

第二层：日志级别过滤。检查创建 Logger 时设置的_minLevel、工厂层有没有全局级别、以及 Provider 自己的IsEnabled。这三处任何一处把级别过滤掉了，日志就不会输出。我用一个表格把这几个检查点列出来：

第三层：Provider 本身是否可用。比如 FileSink 打开文件路径时抛了异常，但异常被静默捕获了，日志就无声无息地丢掉了。一个负责任的手写框架，Provider 的初始化异常至少应该输出到标准错误，而不是吞掉。

6.2 日志重复输出：Provider 注册的幂等性

日志打了两遍，是另一个高频问题。出现这种情况，九成原因是同一个 Provider 被重复注册了。

比如工厂初始化代码被调用了两次，AddSink(new FileSink(...))执行了两遍，但你只看到一份文件，内容里是双份日志。或者官方抽象库的场景里，你在多个模块里都对容器调用了AddConsole()。

诊断思路很简单：在AddSink方法里给每个 Sink 分配一个唯一 ID，然后输出注册列表的哈希值，看看运行时容器里到底有哪些 Sink。不过最简单的方法其实是看日志内容格式，两份日志如果时间戳完全一致，只是重复出现，多半就是重复注册。

另外一个隐藏更深的原因：多个工厂实例。如果你的应用同时存在两个AppLoggerFactory实例，一个注册了 Console，一个注册了 File，业务代码拿到了其中一个，另一个也在写，看起来像“日志从不同地方冒出来”，实际上还是注册管理混乱。解决方法是把工厂设计成全局单例，或者统一走依赖注入容器。

6.3 日志闪烁丢失：进程退出与缓冲

日志丢失，尤其是异步队列模式下丢失，是最难排查的一类问题。因为日志“没有发生过”，连错误都没有。

我踩过的坑是这么一种情况：控制台里日志一切正常，文件日志却有缺口，每次进程重启后，最后一次批量刷新的日志总是少几条。后来定位到原因，是程序退出时没有等后台消费线程把队列排空。进程退出太快，后台线程被强制结束了。

解决方法就是我在异步 Sink 里写的那个Dispose：调用TryComplete()通知消费者“生产结束了”，再用_worker.Wait(TimeSpan.FromSeconds(5))给消费者一个宽限期，宽限期内把剩余日志全部刷盘。这个逻辑必须在进程退出钩子里被可靠调用，而不是靠垃圾回收。

还有一类丢失是磁盘满或者权限问题。FileSink 写文件失败后，如果异常被吞掉，日志就很安静地丢了。负责任的做法是写失败时尝试输出到备用输出端，比如 Windows 事件日志或者System.Diagnostics.Trace，至少让运维人员知道日志系统本身坏了。

6.4 日志系统的日常体检

最后分享一个我自己养成的习惯：每个季度给日志系统做一次“体检”。

体检项目包括：异步队列的丢弃计数是否为 0，文件写入是否出现异常日志，Provider 的启动时间是否异常，日志文件的大小增长是否符合预期。特别是异步队列的丢弃计数，它是个非常重要的健康指标。如果计数一直在涨，说明日志生产速度长期高于消费速度，要么扩容消费线程，要么调大队列，要么降低冗余日志的级别。

日志框架看起来是基础设施里最不起眼的部分，但恰恰是这份“不起眼”让它很少被认真审视。真正出问题的时候，它又会变成最影响排查效率的环节。手写一个简化版，不是为了重复造轮子，而是为了在出问题的时候，脑子里那张流转图能第一时间把问题指出来。