📚 课程目录第2章日志系统设计原则

日志系统设计原则：可观测性、低侵入、高性能

做SDK接入改造，日志系统就是你的眼睛。

你想想看，SDK跑到用户App里，你什么都看不见。出了Bug只能靠猜？那不行。所以日志系统必须设计好。我个人习惯是把设计原则浓缩成三个词：可观测性、低侵入、高性能。

这三点共同决定了日志系统能不能真正帮到你。

核心总结：可观测性让你看得清，低侵入让你不发愁，高性能让你跑得动。三者缺一不可。

一、可观测性：别让日志变成黑盒

什么叫可观测性？简单说，就是出了问题你能快速定位到根因。

我在项目中遇到过一件糟心事：用户反馈SDK初始化失败，但日志只打了“初始化失败”一句话。是网络不通？参数错误？还是权限没给？完全不知道。最后只能给用户发定制包，加日志，再跑一次。折腾了两周。

所以现在我的日志设计，必须满足几个条件：

有标识：每个请求/会话都有唯一ID，方便串联全链路。
有上下文：比如错误码、耗时、关键参数。不是光说“失败”，要说“网络请求失败，错误码1001，超时5000ms”。
有等级：DEBUG/INFO/WARN/ERROR，分得清轻重缓急。
有因果：日志之间能形成调用链。A调B，B调C，每一步都有记录。

我的小技巧：日志里加一个“traceId”字段。所有打印都带上它。出问题后，直接按traceId搜索，整条链路就出来了。

可观测性不是堆日志。关键在于日志能不能回答三个问题：

发生了什么？
为什么发生？
影响范围多大？

能回答，就算合格。不能回答，日志就白打了。

二、低侵入：别拖累主业务

SDK是寄生在宿主App里的。

日志采集如果做得太重，会严重影响主业务性能。用户App卡顿、闪退、流量飙升，全怪到你头上。我见过一个案例：某款支付SDK因为日志写入太频繁，导致用户手机发烫，最后被App Store下架了。

所以低侵入设计，是我反复强调的原则。

具体怎么做？几个关键思路：

异步写日志：别在主线程里写文件。开一个后台线程，攒一批再写。或者塞到内存队列里，让消费者线程去处理。
控制采样率：不是所有日志都要落盘。DEBUG日志可以全关，只在出问题时动态开启。线上只保留WARN/ERROR级别的关键日志。
压缩传输：网络日志统一压缩。我习惯用gzip，压缩后体积能减少70%以上。既省流量，又省电量。
限流降级：如果短时间日志爆炸，别硬扛。直接丢弃一部分，或者降级到只记录错误。

曾经踩过的坑：我以前做过一个日志组件，在每行日志都加锁写文件。结果线上QPS一高，锁竞争导致主线程卡死。后来改成无锁环形缓冲区，性能提升了一个数量级。

低侵入的核心思想是：日志是辅助，不是主角。永远不要让日志成为性能瓶颈。

三、高性能：日志采集不能拖后腿

高性能和低侵入其实是互相绑定的。

但高性能有它自己的具体要求。SDK日志系统通常要处理几类场景：

场景	性能要求	设计思路
埋点上报	每秒数千条	批量上报，减少网络请求次数
错误日志	实时性高	高优先级队列，立即触发上传
性能数据	低开销	采样+聚合，避免逐条记录
用户行为流	高吞吐	本地存储+分片，异步压缩上传

我建议用分层架构来保证性能。底层用内存队列缓冲，中间用批量压缩，上层用异步上传。每一层都做好背压和限流。

// 伪代码示例：高性能日志写入
public class HighPerfLogger {
    private final RingBuffer<LogEvent> buffer;  // 无锁环形缓冲区
    
    public void log(LogEvent event) {
        // 超快速入队
        buffer.write(event);
    }
    
    // 后台消费者线程
    private void flushLoop() {
        while (true) {
            List<LogEvent> batch = buffer.batchRead(100, 100ms);
            if (!batch.isEmpty()) {
                String json = compress(batch);  // 批量压缩
                uploadAsync(json);              // 异步上传
            }
        }
    }
}

这个模式我在多个项目里验证过。单机写入速度能达到每秒10万条以上，CPU占用不到1%。

优化细节：不要用new String()拼接日志，用StringBuilder。不要频繁创建临时对象，避免触发GC。内存池化也是个好选择。

四、如何权衡三者？

三个原则之间其实有矛盾。

可观测性要打得多，会拖低性能。高性能要写得快，可能会丢日志。低侵入要求轻量，但日志结构又不能太简单。怎么办？

我通常按优先级排：

线上环境：低侵入 > 高性能 > 可观测性。先保证不拖垮App，再考虑详细日志。
Debug环境：可观测性 > 高性能 > 低侵入。能打多详细就打多详细，性能退后。
预发布环境：三者平衡。适当降低采样率，保留关键链路日志。

这样做的好处是：线上出了问题，可以通过动态开关快速切换到全量日志模式。我管这叫“分级切换策略”。

注意：别把线上日志级别设成DEBUG。我曾经看到过一个团队，线上跑了DEBUG级别的日志，结果一天产生了10GB日志文件，撑爆了磁盘。

知识结构总览

下面这张图总结了我们刚聊的核心内容。

这三个原则不是孤立存在的。可观测性决定了日志的广度和深度，低侵入保证了日志不会影响主业务流程，高性能则确保日志系统在高压力下依然能稳定输出。三者互相制约，也互相促进。

嗯，你在设计日志系统时，可以拿这个框架去对照。每个模块的设计，都问自己一句：我满足这三个原则中的哪几个？如果某个模块明显违背了某条原则，那就该重新思考了。