Milvus mlog 日志规范：上下文传递、字段构建与限流日志的完整实践指南

本文基于 Milvus 仓库中的 mlog AI Agent 日志指南 与 mlog 库文档，系统讲解 Milvus 统一日志框架 mlog 的使用规范：如何强制传递 context、如何选用日志级别、如何用 FieldXxx 构建结构化字段、如何用 Rated 变体与 LevelEnabled 保护热路径，并结合 pkg/mlog 源码揭示延迟编码、Logger 缓存与 gRPC 字段跨服务传播的底层实现，帮助你在 Milvus 组件中写出可追溯、低开销且可检索的日志。

一、核心原则：统一入口，禁用裸日志包

Milvus 的日志规范只有两条铁律：

1. 所有日志必须使用 github.com/milvus-io/milvus/pkg/v3/mlog 包输出；
2. 严禁直接使用 zap、标准库 log 或旧版 pkg/log 包做运行时日志。

mlog 是构建在 zap 之上的 context-aware 日志库（见 pkg/mlog/README.md 的“Design Goals”），它的设计目标与这两条规范一一对应：

设计目标	对应的规范意义
强制传递 Context	所有日志调用必须携带 ctx，保证请求全链路可追溯
零开销抽象	通过类型别名（type Field = zap.Field）避免包装层开销，性能接近直接调用 zap
字段自动累积	Context 中的字段沿调用链累积，子 context 继承父字段
跨服务传播	支持通过 gRPC metadata 传播关键字段，实现分布式日志关联
延迟编码	WithLazy 延迟字段编码，日志级别关闭时零编码开销

统一入口的价值在于：traceID/spanID 注入、限流计数、模块名（module 字段）等能力都收敛在 mlog 内部，绕过它意味着这些能力全部失效。

二、Context 传递规则：永不传 nil

规则 1：每个日志调用都必须接收一个 ctx context.Context，禁止传 nil。 选择 ctx 的优先级为：

1. 函数参数中的 ctx（首选）；
2. 结构体级别的 ctx（如 s.ctx）；
3. context.TODO()——仅在确实拿不到请求/组件上下文时使用；
4. 不要为了记日志而使用 context.Background()。

从源码看，这条规则并非空话。pkg/mlog/logger.go 中 prepareLog 对 ctx == nil 会额外附加一个告警字段：

if ctx == nil {
    // Safe: fields originates from variadic ...Field, so its cap == len;
    // append always allocates a new backing array here.
    return getLogger(), append(fields, nilContextField)
}

其中 nilContextField = zap.Bool("_ctx_nil", true)（pkg/mlog/logger.go#L15-L17）。也就是说，传 nil 不仅丢失了全部上下文字段，还会在日志中留下 _ctx_nil: true 的“自曝”标记，方便排查不规范的调用点。因此规范强调 ctx 优先级排序：函数参数 > 结构体字段 > context.TODO()。

三、Logger 方法 vs 包级函数

规则 2：如果当前结构体持有 *mlog.Logger 字段，优先用它；否则使用包级函数。 基本用法如下：

// 包级函数（无 Logger 字段时）
mlog.Info(ctx, "segment loaded", mlog.FieldSegmentID(id), mlog.Duration("cost", d))
mlog.Error(ctx, "flush failed", mlog.Err(err))

// Logger 方法（结构体持有 *mlog.Logger 时）
l.Info(ctx, "search started", mlog.Int64("nq", nq))

组件级 Logger 的典型构建方式是在组件构造时绑定组件生命周期内不变的字段（pkg/mlog/README.md “Component-Level Logger”一节）：

type QueryNode struct {
    logger *mlog.Logger
}

func NewQueryNode(nodeID int64) *QueryNode {
    return &QueryNode{
        logger: mlog.With(
            mlog.FieldModule("querynode"),
            mlog.FieldNodeID(nodeID),
        ),
    }
}

*mlog.Logger 的内部结构（pkg/mlog/logger.go#L149-L152）同时保存了“已编码的 zap logger”和“原始字段拷贝”：

type Logger struct {
    logger *zap.Logger // pre-encoded with component fields
    fields []Field     // copy of component fields for passing to other loggers
}

Logger 方法族与包级函数签名完全一致：Debug/Info/Warn/Error/DPanic/Panic/Fatal/Log(ctx, level, msg, fields...)，以及限流版 RatedDebug/RatedInfo/RatedWarn/RatedError/RatedLog。此外还有 With（立即编码）、WithLazy（延迟编码）、WithOptions、Level() 与 LevelEnabled(level) 等辅助方法。

四、日志级别选择

原文档给出的级别选择表需要完整保留，这是写日志时最直接的对标依据：

级别	使用场景
Debug	仅开发或排障时有用的内部状态细节，生产环境默认禁用
Info	正常运营事件：启动、关闭、配置加载、请求完成、任务结束
Warn	意外但可恢复的情况：超时重试、可重试的瞬时 RPC 失败、走了降级路径、调用了废弃 API
Error	操作失败且无法继续：不可恢复的 RPC 失败、数据损坏、不变量被破坏。必须附加 mlog.Err(err)
Fatal	进程无法继续，调用 os.Exit(1)。仅用于初始化阶段不可恢复的配置/装配失败
DPanic / Panic	保留给“绝不应该发生”的不变量违例，极少使用

每个级别都有对应的 Rated 变体（RatedDebug…RatedError、RatedLog），用于循环与热路径，详见第六节。

从 pkg/mlog/level.go 看，全局默认级别是 InfoLevel（defaultGlobalLevel = zap.NewAtomicLevelAt(InfoLevel)），这解释了为何“Debug 在生产环境默认禁用”。级别常量是 zapcore.Level 的类型别名与再导出（Level = zapcore.Level），因此 mlog 与 zap 生态的级别体系天然兼容。

五、字段构建：FieldXxx 优先于手写 key

规则 3：当 key 已有预定义 FieldXxx 构造器时，必须使用 FieldXxx(val)，绝不允许手写 mlog.Int64("segmentID", v)。 字段构建的优先级为：

FieldXxx(val)  >  类型化构造器如 mlog.String(key, val)  >  mlog.Any(key, val)

预定义 FieldXxx 构造器（key 内置，禁止手写 key 字符串；完整定义见 pkg/mlog/field_enum.go）：

函数	类型	内置 Key
FieldNodeID(v)	int64	nodeID
FieldModule(v)	string	module
FieldTraceID(v)	string	traceID
FieldSpanID(v)	string	spanID
FieldDbID(v)	int64	dbID
FieldDbName(v)	string	dbName
FieldCollectionID(v)	int64	collectionID
FieldCollectionName(v)	string	collectionName
FieldPartitionID(v)	int64	partitionID
FieldPartitionName(v)	string	partitionName
FieldSegmentID(v)	int64	segmentID
FieldIndexID(v)	int64	indexID
FieldFieldID(v)	int64	fieldID
FieldTaskID(v)	int64	taskID
FieldBroadcastID(v)	int64	broadcastID
FieldJobID(v)	int64	jobID
FieldBuildID(v)	int64	buildID
FieldVChannel(v)	string	vchannel
FieldPChannel(v)	string	pchannel
FieldMessageID(v)	ObjectMarshaler	messageID
FieldMessage(v)	ObjectMarshaler	message
FieldSchema(v)	*schemapb.CollectionSchema	schema（外部凭据会被脱敏）

注意两个实现细节：

• 大多数 FieldXxx 接受可选的 ...FieldOption 参数，例如 FieldCollectionID(id, mlog.OptPropagated()) 会标记该字段跨 RPC 传播（见第七节）；FieldNodeID、FieldModule、FieldTraceID 等基础设施字段不接受 option。
• FieldSchema 是一个安全敏感的特例：它内部调用 externalspec.RedactCollectionSchemaForLog(val) 对 schema 中的外部凭据做脱敏后再记录（pkg/mlog/field_enum.go#L242-L245），因此记录 schema 时应一律走 FieldSchema 而非 Any("schema", ...)。

通用类型化构造器（无对应 FieldXxx 时使用；函数名与 Go 类型一致）：String / Int64 / Int / Float64 / Bool / Duration / Time / Stringer / Binary / Err（key 固定为 "error"）等，完整清单见 pkg/mlog/field.go。每种类型都有指针变体 Xxxp 和切片变体 Xxxs，例如 Stringp、Int64s、Float64s。

规则 6：mlog.Any 性能差，仅在类型完全未知时使用。 这是因为 Any 会触发反射路径，而类型化构造器是直接编码。

六、热路径：Rated 限流与 LevelEnabled 守卫

规则 4：在循环或热路径中，使用 Rated 变体：

// 限流日志（循环/热路径）。limit = 每秒允许的事件数；rate.Inf 表示不限流
mlog.RatedWarn(ctx, 1.0, "lagging", mlog.Int64("gap", gap))

规则 5：当 Debug 日志位于热路径且字段构建本身昂贵（fmt.Sprintf、序列化、遍历）时，用 LevelEnabled 守卫：

if mlog.LevelEnabled(mlog.DebugLevel) {
    mlog.Debug(ctx, "detail", mlog.String("dump", strings.Join(paths, ",")))
}

这两条规则背后的机制可以分别深入看：

Rated 的实现（pkg/mlog/rated.go）：

• 限流器按调用点隔离：每次调用通过 runtime.Caller(1) 取回调用方的程序计数器 pc，在 ratedRegistry sync.Map 中懒初始化一个 rate.Limiter（burst=1），因此不同调用点互不抢占配额；
• 被抑制的日志不会丢弃计数：ignoreCount 累加，下一次放行时通过 Int64("_suppressed", ignored) 把抑制条数附加到放行日志上，保证“发生过 N 次”这个事实可审计：

func ratedAllow(pc uintptr, limit rate.Limit, fields *[]Field) bool {
    entry := getOrCreateRatedEntry(pc, limit)
    if !entry.limiter.Allow() {
        entry.ignoreCount.Add(1)
        return false
    }
    if ignored := entry.ignoreCount.Swap(0); ignored > 0 {
        *fields = append(*fields, Int64("_suppressed", ignored))
    }
    return true
}

• 级别检查前置：Rated* 函数先 currentLevel().Enabled(level) 再取 pc，级别关闭时几乎零成本。

LevelEnabled 的实现（pkg/mlog/level.go#L55-L57）就是一个对原子级别指针的 Enabled 判断。注意它与函数内部自带的级别检查是互补的：函数内部的提前返回只能省掉 zap 的编码开销，但 mlog.String("dump", expensiveDump()) 这类实参在调用前就已经求值了，只有 LevelEnabled 包裹整个代码块才能把昂贵计算一并跳过。

七、字段绑定：跟着请求走，还是跟着组件走

原文档给出的决策树是字段设计的核心方法论，完整继承如下：

字段是否应跟随请求链（绑定到 ctx）？
├─ 是 → ctx = mlog.WithFields(ctx, fields...)
│       延迟编码；字段保持插入顺序，重复 key 均保留。
│       若需跨 gRPC 传播，附加 OptPropagated()：
│         mlog.WithFields(ctx, mlog.FieldCollectionID(id, mlog.OptPropagated()))
│
└─ 否 → 绑定到 Logger
        ├─ 组件级（结构体生命周期）→ mlog.With(fields...) 存为结构体字段
        ├─ 函数级（作用域内多次日志共享）→ l := mlog.With(fields...) 作为局部变量
        └─ 字段可能按级别被过滤 → mlog.WithLazy(fields...) —— 延迟编码

对应的标准写法：

// 在请求入口绑定到 ctx
ctx = mlog.WithFields(ctx, mlog.FieldCollectionID(collID), mlog.String("request_id", reqID))

// 在组件构造时绑定到 Logger
l := mlog.With(mlog.FieldModule("querynode"), mlog.FieldNodeID(nodeID))

// 局部 Logger，消除函数内重复字段
func (s *compactor) compact(ctx context.Context, segID int64, plan *Plan) error {
    l := mlog.With(mlog.FieldSegmentID(segID), mlog.Int64("planID", plan.ID))
    l.Info(ctx, "compact start")
    // ...
    l.Info(ctx, "compact done", mlog.Duration("cost", elapsed))
    return nil
}

从 pkg/mlog/context.go 的 WithFields/withFields 实现可以确认决策树中的两个语义细节：

• 有序累积、保留重复 key：newFields 是 lc.fields 与新字段的顺序拼接，不做去重。这与 zap 的字段列表行为一致，避免热路径上的隐藏去重成本；因此 README 特别提醒，下游 JSON 消费方对重复 key 的解释可能不同，调用方应避免在一条日志中对同一 key 赋予两种含义。
• ctx 侧的字段走 zap.WithLazy 延迟编码（withLazy(lc.logger, fields)），而组件 Logger 的 With 是立即编码——这正是决策树中“字段可能按级别被过滤 → 用 WithLazy”的底层依据。

八、底层机制：缓存、Trace 注入与 gRPC 传播

理解了上面几条规则“为什么”，才能在边界场景做对选择。以下是从源码可以确认的关键机制：

1. logContext 与 Logger 选择优化。 context 中保存的 logContext 同时持有有序字段切片和已应用字段的缓存 logger（pkg/mlog/context.go#L15-L18）。Logger 的 prepareLog（pkg/mlog/logger.go#L251-L292）在合并组件字段与 ctx 字段时，会比较“组件 Logger 预编码字段数”与“ctx 缓存字段数”，选取字段多的一方作为 base logger，只为另一方做即时编码——预编码字段越多、即时编码越少，日志越快。

2. Trace 字段自动注入。 appendTraceFields（pkg/mlog/logger.go#L36-L53）在每次日志输出前从 OTel SpanContext 读取 traceID/spanID 并自动追加为 FieldTraceID/FieldSpanID。因此只要请求链上带有有效 span，日志中的 traceID 字段是自动出现的，排障时可以直接按 traceID 检索全链路日志，无需手工传递。

3. 跨服务字段传播。 只有标记了 OptPropagated() 的 well-known 字段才会通过 gRPC metadata 传输，且是按需传播——未标记的字段永远不会离开本进程，避免 metadata 膨胀。gRPC 拦截器（pkg/mlog/interceptor.go）定义了四个入口：

拦截器	作用
UnaryServerInterceptor(module)	从入站 metadata 提取传播字段，并自动写入 module 字段
StreamServerInterceptor(module)	同上，用于流式 RPC
UnaryClientInterceptor()	把传播字段注入出站 metadata
StreamClientInterceptor()	同上，用于流式 RPC

wire 格式为 mlog-s-<key>（string）与 mlog-i-<key>（int64）两类类型编码前缀（MetadataPrefix = "mlog-"）；服务端提取时会通过 restoreWellKnownLogKey 把被 metadata 小写化的 key 还原为日志中的 camelCase（如 collectionid → collectionID）。手动场景下也可用 mlog.GetPropagated(ctx) 拿到 map[string]string 供自定义传输使用。

// 服务端配置
server := grpc.NewServer(
    grpc.UnaryInterceptor(mlog.UnaryServerInterceptor("querynode")),
    grpc.StreamInterceptor(mlog.StreamServerInterceptor("querynode")),
)

// 客户端配置
conn, _ := grpc.Dial(addr,
    grpc.WithUnaryInterceptor(mlog.UnaryClientInterceptor()),
    grpc.WithStreamInterceptor(mlog.StreamClientInterceptor()),
)

九、日志级别配置与运行时调整

Milvus 的日志级别通过 configs/milvus.yaml 配置，其中 log.level 默认为 info，支持 debug, info, warn, error, panic, fatal（文件第 1063-1066 行）：

log:
  level: info
  file:
    ...

运行时也可以直接调整全局级别（pkg/mlog/level.go）：

mlog.SetLevel(mlog.DebugLevel)   // 运行时切换级别
level := mlog.GetLevel()         // 读取当前级别
atomicLevel := mlog.GetAtomicLevel() // 拿 AtomicLevel 供自定义 zap.Config 集成

SetLevel 通过 atomic.Pointer[zap.AtomicLevel] 生效，影响所有默认配置的 logger，因此线上排障时把级别从 info 临时切到 debug 是安全且即时生效的操作；反过来，LevelEnabled 守卫的 Debug 块在切回 info 后即刻变为零成本。

十、性能结论：规范背后有基准数据支撑

pkg/mlog/README.md 附带了基准测试（Intel Core i7-8700、Go 1.24），可以印证上述规则的性能收益：

场景	ns/op	B/op	allocs/op
裸 zap.Info（基线）	377	0	0
MlogInfo（包级）	382	0	0
MlogInfoWithContextFields（ctx 已预编码字段）	415	0	0
zap.Info + 3 个现场编码字段	598	192	1
MlogInfoDisabledLevel（级别关闭）	2.7	0	0
RatedInfoAllowed	918	248	2
RatedInfoSuppressed	521	248	2

要点：mlog 包级调用相对裸 zap 仅约 5ns 上下文查找开销；ctx 字段经 WithFields 预编码后零分配，反而比现场编码 3 个字段的 zap 更快；级别关闭时约 2.7ns 提前返回；Rated 系列因为 runtime.Caller + sync.Map 查询会有额外成本，所以规范把它限定在“循环/热路径”而非全量使用。

十一、规范速查

回到原文档的六条规则，加上本文补充的实现依据，形成一份可执行的检查清单：

1. ctx 必传且非 nil：函数参数 > 结构体 ctx > context.TODO()；不要为记日志用 context.Background()。传 nil 会留下 _ctx_nil 标记（pkg/mlog/logger.go#L15-L17）。
2. 有 *mlog.Logger 字段就用它，否则用 mlog.Info(ctx, ...) 等包级函数。
3. key 有 FieldXxx 就用 FieldXxx，禁止手写 mlog.Int64("segmentID", v)；涉及 schema 必须用脱敏的 FieldSchema。
4. 循环/热路径用 Rated*，limit 为每秒事件数，rate.Inf 不限；被抑制次数会以 _suppressed 计数补记。
5. 昂贵字段构建用 LevelEnabled 守卫，尤其是 Debug 日志。
6. mlog.Any 仅用于类型未知场景，其余一律用类型化构造器（含 Xxxp/Xxxs 变体）。
7. 字段归属按“是否跟随请求链”判断：请求级字段 → mlog.WithFields；组件级 → mlog.With；函数级共享 → 局部 l := mlog.With(...)；需跨服务 → 追加 mlog.OptPropagated()。

主要参考文件：日志规范原文、mlog 库文档、pkg/mlog/logger.go、pkg/mlog/context.go、pkg/mlog/level.go、pkg/mlog/rated.go、pkg/mlog/field_enum.go、pkg/mlog/interceptor.go、configs/milvus.yaml、observability 指南索引。