zap采样器与性能优化内幕

1. Sampler 源码全解

1.1 数据结构（sampler.go:28-42）

const (
    _numLevels        = _maxLevel - _minLevel + 1   // 7 个级别
    _countersPerLevel = 4096                        // 每级别 4096 个槽位
)

type counter struct {
    resetAt atomic.Int64    // 本周期截止时刻（UnixNano）
    counter atomic.Uint64   // 周期内计数
}

type counters [_numLevels][_countersPerLevel]counter   // 二维定长数组

func (cs *counters) get(lvl Level, key string) *counter {
    i := lvl - _minLevel                       // 行：级别
    j := fnv32a(key) % _countersPerLevel       // 列：消息哈希
    return &cs[i][j]
}

设计要点：

• 预分配 7 × 4096 个计数器，永不扩容、无 map、无锁------用哈希槽位换确定性内存

• 4096 槽 + fnv32a 意味着不同消息可能撞槽（假阳性）→ 采样是近似的：官方文档明说 "optimized for speed over absolute precision"（150-151 行）

• get 返回槽位指针，后续全靠原子操作------整个采样路径零锁

1.2 fnv32a：无分配字符串哈希（51-62）

// 从标准库 hash/fnv 抄的，去掉了 []byte(string) 转换的分配
func fnv32a(s string) uint32 {
    const ( offset32 = 2166136261; prime32 = 16777619 )
    hash := uint32(offset32)
    for i := 0; i < len(s); i++ {
        hash ^= uint32(s[i])
        hash *= prime32
    }
    return hash
}

FNV-1a：一遍扫描、每字节一次异或一次乘法。抄标准库只为直接吃 string（标准库接口收 \[\]byte 会强制分配）。

1.3 IncCheckReset：计数 + 周期重置（64-81）

func (c *counter) IncCheckReset(t time.Time, tick time.Duration) uint64 {
    tn := t.UnixNano()
    resetAfter := c.resetAt.Load()
    if resetAfter > tn {
        return c.counter.Add(1)          // ① 周期内：原子 +1
    }

    c.counter.Store(1)                   // ② 周期到：重置为 1（自己是本周期第一条）

    newResetAfter := tn + tick.Nanoseconds()
    if !c.resetAt.CompareAndSwap(resetAfter, newResetAfter) {
        // ③ CAS 失败：别的 goroutine 抢先重置了（它也 Store(1)）
        return c.counter.Add(1)          //    所以我接着 +1
    }
    return 1
}

并发场景推演：两个 goroutine 同时发现超周期------A 先 CAS 成功（返回 1），B 的 Store(1) 和 A 的竞争......最坏情况计数略偏差，但绝不会死锁/崩溃，且周期语义大体正确。这是"lock-free + 尽力正确"的典型取舍。

1.4 sampler Core 的 Check（214-229）

func (s *sampler) Check(ent Entry, ce *CheckedEntry) *CheckedEntry {
    if !s.Enabled(ent.Level) { return ce }

    if ent.Level >= _minLevel && ent.Level <= _maxLevel {
        counter := s.counts.get(ent.Level, ent.Message)    // 槽位 = (级别, 消息)
        n := counter.IncCheckReset(ent.Time, s.tick)       // 本周期第 n 条
        if n > s.first && (s.thereafter == 0 || (n-s.first)%s.thereafter != 0) {
            s.hook(ent, LogDropped)
            return ce        // ★ 不 AddCore → 丢弃（前 first 条 & 每 thereafter 条放行）
        }
        s.hook(ent, LogSampled)
    }
    return s.Core.Check(ent, ce)
}

放行公式：n <= first（前 N 条）或 (n-first) % thereafter == 0（之后每 M 条）。first=100, thereafter=100：每秒同消息 1万条 → 记前 100 + 第 200/300/... 条 ≈ 200 条。

其他方法：

• With（203-212）：counts 指针共享------所有子 logger 共用同一套计数器（采样是全局语义，不随 With 分裂）

• Hook（121-125）：SamplerHook 选项注册决策回调，SamplingDecision 是 bit field（LogDropped=1<<i, LogSampled=1<<1，87-92）

2. 对象池全景

zap 热路径上的对象几乎全部池化，一张表看全：

池	位置	池化对象	归还点
_cePool	zapcore/entry.go:35	CheckedEntry（cores 预分 4 槽）	ce.Write 末尾（292）
_jsonPool	zapcore/json_encoder.go:37	jsonEncoder	putJSONEncoder（EncodeEntry 后/console 用完）
_sliceEncoderPool	zapcore/console_encoder.go:31	sliceArrayEncoder	console 编码完（41-44）
_stackPool	internal/stacktrace/stack.go:33	Stack（storage 预分 64 帧槽）	stack.Free()（logger.go:380 defer）
bufferpool	internal/bufferpool	buffer.Buffer（1KiB 起）	buf.Free()（ioCore.Write:100 等）
_errArrayElemPool	error.go:28	errArrayElem	MarshalLogArray 用完（66）
buffer.Pool	buffer/pool.go	各实例池的底层	---

internal/pool 是对 sync.Pool 的泛型封装（pool.New(func() T)），统一 Get/New 语义，且兼容 Go 版本差异。

池化的纪律（值得抄走的经验）：

1. 归还前清引用 （reset() 逐元素置 nil）------防内存泄漏

2. 池对象不得逃逸到归还之后（CheckedEntry 的 dirty 检测就是防这个）

3. 预分配"够用的容量"（cores=4、storage=64、elems=2）------多数场景免扩容

3. stacktrace：栈捕获的优化

internal/stacktrace/stack.go：

// 33-37：池 + 64 帧预分配
var _stackPool = pool.New(func() *Stack {
    return &Stack{storage: make([]uintptr, 64)}
})

// Capture（71-109）
func Capture(skip int, depth Depth) *Stack {
    stack := _stackPool.Get()
    switch depth {
    case First: stack.pcs = stack.storage[:1]    // caller 用：只要 1 帧，runtime.Callers 快得多
    case Full:  stack.pcs = stack.storage        // 堆栈用：先用 64 帧
    }
    numFrames := runtime.Callers(skip+2, stack.pcs)

    if depth == Full {
        pcs := stack.pcs
        for numFrames == len(pcs) {              // 帧数 == 容量 → 可能被截断
            pcs = make([]uintptr, len(pcs)*2)    // 容量翻倍重取
            numFrames = runtime.Callers(skip+2, pcs)
        }
        stack.storage = pcs                      // 深栈场景：池内 storage 被逐步换成大槽
        stack.pcs = pcs[:numFrames]
    } else {
        stack.pcs = stack.pcs[:numFrames]
    }
    stack.frames = runtime.CallersFrames(stack.pcs)
    return stack
}

细节：

• storage 与 pcs 分离：池归还的是大数组，使用的是其子切片（44-51 注释）

• First 深度只采 1 帧------caller 标注便宜、堆栈昂贵的分界就在这

• 深栈自适配：连续深栈时池里会沉淀出大 storage，浅栈时不浪费

zap.Stack() 字段走 stacktrace.Take()（同文件），Skip 可调帧起点。

4. zap 为什么快：九大手段总账

#	手段	源码锚点	效果
1	禁用日志零成本	logger.go:331 级别前置短路	关掉的 Debug 连 Entry 都不构造
2	强类型 Field + Type 分发	zapcore/field.go:114 switch	编码零反射
3	零分配字节编码	buffer/buffer.go + strconv.AppendXxx	数字/布尔直接进 byte slice
4	手写 JSON 转义	json_encoder.go:509 快路径整段直通	纯 ASCII 串零处理；不转义 HTML 字符
5	万物皆池	第 2 节的表	热路径 ~0 次分配，GC 压力极小
6	上下文预编码	ioCore.With → EncodeEntry 字节直拷（json_encoder.go:416-419）	With 的字段每条日志只做 memcpy
7	Check/Write 两段式	CheckedEntry 收集同意者	采样/过滤在写前拦截，白写的活一点不干
8	无锁采样 + 定长槽	fnv32a + 原子计数	高频日志限流本身不成为瓶颈
9	caller 按需、单帧优先	First/Full 深度区分	默认路径不采栈，caller 只采 1 帧

配套的"不快"取舍（诚实的代价表）：

• Sugar：装箱 + Any 分发（2~3 alloc）

• Reflect/Any 兜底：反射 + json.Encoder

• console 编码：fmt.Fprint 反射

• caller/stack：runtime.Callers 微秒级

• 强类型 API 的"啰嗦"就是性能的价格（人体工学 vs 零分配不可兼得）

5. Any 的泛型技巧（field.go:444-481）

有趣的编译器故事：巨型 type switch 会让 Go 编译器给 zap.Any 分配 ~4.8KB 栈空间（每个 case 一份 Field 构造的栈帧）。解法：

type anyFieldC[T any] func(string, T) Field      // 包装成"函数类型"

func (f anyFieldC[T]) Any(key string, val any) Field {
    v, _ := val.(T)
    return f(key, v)                              // 统一入口，收敛栈帧
}

// 用法：
case int:
    c = anyFieldC[int](Int)      // 函数引用不装箱
...
return c.Any(key, value)          // 只有一处调用点 → 一个栈帧