为什么 log.Printf 在高并发写日志时会卡住主线程
因为默认的 log.Logger 是同步阻塞的：每次调用 log.Printf 都会直接写入 os.Stderr 或你指定的 io.Writer，磁盘 I/O 或网络日志后端（比如 syslog）一慢，整个 goroutine 就得等着。不是“偶尔慢”，是“必然拖垮吞吐”。
常见错误现象：pprof 显示大量 goroutine 堆在 syscall.Write 或 writev 上；QPS 突然掉 30% 以上，而 CPU 使用率没涨；日志文件写入延迟从毫秒级跳到几百毫秒。
- 别用
log.SetOutput换成带缓冲的bufio.Writer—— 它只缓输出层，不解决日志调用本身阻塞问题 - 别在 HTTP handler 里直接调
log.Printf，尤其带 JSON 序列化或堆栈打印时 - 真正要解耦的是“记录动作”和“落盘动作”，必须引入异步通道 + 单独 writer goroutine
用 zap 的 Core + RingBuffer 替代手写 channel
自己用 chan *LogEntry 写异步日志器看着简单，实际容易漏掉：消息丢失（channel 满了 panic 或丢弃）、序列化竞争（多个 goroutine 同时 json.Marshal）、OOM（无背压控制）。zap 的 core 层已内置环形缓冲和批量刷写逻辑，比裸 channel 更稳。
使用场景：每秒日志量 > 5k 条、要求日志不丢（至少尽力）、需要结构化字段（zap.String("user_id", uid)）。
立即学习“go语言免费学习笔记（深入）”；
- 启用缓冲：用
zap.WrapCore包一层zapcore.NewSampler控制采样，再用zapcore.NewTee接多个输出，避免单点瓶颈 - 关键参数：
zapcore.NewCore的第三个参数（EncoderConfig）里设EncodeLevel: zapcore.CapitalLevelEncoder，避免字符串拼接开销 - 性能影响：开启
zap.AddCaller()会触发runtime.Caller，增加约 15% 耗时，生产环境建议关掉或只在 error 级别开
file-rotatelogs 和 lumberjack 的写入延迟差异
轮转日志不是“换个文件名”那么简单。当写满 100MB 触发 rotate 时，lumberjack 默认会阻塞所有日志写入，直到压缩/归档完成；而 file-rotatelogs（配合 io.MultiWriter）可把 rotate 操作扔进 goroutine，主线程继续写新文件。
错误现象：lumberjack 在 rotate 瞬间出现 200ms+ 的 Write 延迟；日志行时间戳乱序（旧日志写到新文件末尾）。
- 用
lumberjack必须设LocalTime: true和Compress: false，压缩操作绝对不能在写日志路径里做 -
file-rotatelogs要搭配sync.Pool复用bytes.Buffer，否则高频 rotate 下 GC 压力陡增 - 兼容性注意：Windows 下
file-rotatelogs的文件锁行为和 Linux 不同，测试时务必用目标 OS
什么时候该放弃纯内存缓冲，改用本地队列落地
当单机日志峰值超过 5w QPS，且下游是 Kafka / Loki 这类远程服务时，纯内存 chan 或 ring buffer 容易被冲垮——goroutine 堆积、GC 频繁、OOM。这时候得把缓冲下沉到磁盘，用本地队列兜底。
推荐方案：用 github.com/segmentio/kafka-go 的 Writer 自带的 AsyncWriter + QueueCapacity 参数，或者轻量级 github.com/buraksezer/olric 做本地嵌入式队列（不依赖外部服务）。
- 不要自己实现基于
mmap的日志队列 —— 边界条件太多（断电恢复、偏移错位、fsync 时机） - 本地队列必须设硬上限（比如 512MB），超限时丢 error 级日志，但绝不能 panic
- 最容易被忽略的一点：队列持久化路径的磁盘必须和系统盘分离，否则日志刷盘会拖慢整个节点的调度响应
