mlog - Context-Aware Logging Library

mlog is a context-aware logging library built on zap, designed specifically for Milvus distributed systems.

Design Goals

Mandatory Context Passing - All logging operations require a context, ensuring request traceability
Zero-Overhead Abstraction - Uses type aliases to avoid wrapper overhead, performance comparable to direct zap usage
Automatic Field Accumulation - Context fields automatically accumulate through the call chain, child contexts inherit parent fields
Cross-Service Propagation - Supports propagating key fields via gRPC metadata for distributed tracing
Lazy Encoding - Uses WithLazy for deferred field encoding, avoiding encoding overhead when log level is disabled

Architecture

┌──────────────────────────────────────────────────────────────────┐
│                           mlog Package                           │
├──────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐  ┌──────────────┐  ┌────────────────────────┐  │
│  │  logger.go   │  │  context.go  │  │      field.go          │  │
│  │              │  │              │  │                        │  │
│  │ - Log()      │  │ - WithFields │  │ - Field constructors   │  │
│  │ - Debug()    │  │ - GetProp..  │  │ - Field constructors   │  │
│  │ - Info()     │  │ - logContext │  │ - OptPropagated()      │  │
│  │ - Warn()     │  │              │  │                        │  │
│  │ - Error()    │  │              │  └────────────────────────┘  │
│  │ - Logger     │  └──────────────┘                              │
│  │   .With()    │  ┌──────────────┐  ┌────────────────────────┐  │
│  │   .WithLazy  │  │  rated.go    │  │    field_enum.go       │  │
│  └──────────────┘  │              │  │                        │  │
│                     │ - RatedLog   │  │ - Well-known keys      │  │
│  ┌──────────────┐  │ - RatedDebug │  │   (FieldXXX)           │  │
│  │  level.go    │  │ - RatedInfo  │  │ - Field helpers        │  │
│  │              │  │ - RatedWarn  │  │                        │  │
│  │ - SetLevel   │  │ - RatedError │  └────────────────────────┘  │
│  │ - GetLevel   │  └──────────────┘                              │
│  └──────────────┘                                                │
├──────────────────────────────────────────────────────────────────┤
│                     interceptor.go (gRPC)                        │
├──────────────────────────────────────────────────────────────────┤
│  - UnaryServerInterceptor(module)                                │
│  - StreamServerInterceptor(module)                               │
│  - UnaryClientInterceptor()                                      │
│  - StreamClientInterceptor()                                     │
│  - extractPropagated() / injectPropagated()                      │
└──────────────────────────────────────────────────────────────────┘

Core Concepts

1. logContext

The logging context stored in context.Context:

type logContext struct {
    fields []Field       // Ordered fields attached to the context
    logger *zap.Logger   // Cached logger with accumulated fields
}

fields: Preserves field insertion order across WithFields calls
logger: Cached logger with fields already added, avoiding repeated construction

2. Field Types

Type	Description	Propagated
`String`, `Int64`, ...	Regular fields, local logging only	No
`FieldXxx(..., OptPropagated())`	Well-known field marked for cross-service propagation	Yes
Typed constructor + `WithFields`	Local context field unless wrapped by a propagation-aware helper	No

3. Well-Known Keys

Predefined standard field names (camelCase in logs; gRPC metadata lowercases keys during propagation). Keys are unexported; use FieldXxx() constructors instead of raw key strings:

Key	FieldXxx Constructor
`nodeID`	`FieldNodeID(val)`
`module`	`FieldModule(val)`
`traceID`	`FieldTraceID(val)`
`spanID`	`FieldSpanID(val)`
`dbID`	`FieldDbID(val, opts...)`
`dbName`	`FieldDbName(val, opts...)`
`collectionID`	`FieldCollectionID(val, opts...)`
`collectionName`	`FieldCollectionName(val, opts...)`
`partitionID`	`FieldPartitionID(val, opts...)`
`partitionName`	`FieldPartitionName(val, opts...)`
`segmentID`	`FieldSegmentID(val, opts...)`
`indexID`	`FieldIndexID(val, opts...)`
`fieldID`	`FieldFieldID(val, opts...)`
`taskID`	`FieldTaskID(val, opts...)`
`broadcastID`	`FieldBroadcastID(val, opts...)`
`jobID`	`FieldJobID(val, opts...)`
`buildID`	`FieldBuildID(val, opts...)`
`vchannel`	`FieldVChannel(val, opts...)`
`pchannel`	`FieldPChannel(val, opts...)`
`messageID`	`FieldMessageID(val)`
`message`	`FieldMessage(val)`

Usage Guide

Basic Logging

ctx := context.Background()

mlog.Debug(ctx, "debug message", mlog.String("key", "value"))
mlog.Info(ctx, "info message", mlog.Int64("count", 42))
mlog.Warn(ctx, "warning message", mlog.Duration("latency", time.Second))
mlog.Error(ctx, "error message", mlog.Err(err))

Component-Level Logger

Components can create their own Logger with preset fields. Fields are automatically merged with ctx fields when logging:

// Create component Logger (fields pre-encoded for best performance)
type QueryNode struct {
    logger *mlog.Logger
}

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

func (qn *QueryNode) Search(ctx context.Context, req *SearchRequest) {
    // ctx carries request-level fields (traceID, collectionID, etc.)
    // Automatically merges component fields + ctx fields when logging
    qn.logger.Info(ctx, "search started", mlog.Int64("nq", req.NQ))
    // Output: {"module":"querynode", "nodeID":123, "traceID":"xxx", "nq":10, ...}
}

Logger Methods:

Method	Description
`mlog.With(fields...)`	Create new Logger with immediately encoded fields
`mlog.WithLazy(fields...)`	Create new Logger with lazily encoded fields
`mlog.WithOptions(opts...)`	Create new Logger from the global logger with options applied
`(*Logger) With(fields...)`	Add fields (immediately encoded), returns new Logger
`(*Logger) WithLazy(fields...)`	Add fields (lazily encoded), returns new Logger
`(*Logger) WithOptions(opts...)`	Apply logger options, returns new Logger
`Level()`	Get current log level
`Log(ctx, level, msg, fields...)`	Log at specified level
`Debug/Info/Warn/Error(ctx, msg, fields...)`	Log a message

Performance Optimization:

When logging, compares the pre-encoded field count between ctx and component Logger, selects the one with more fields as base logger:

Component Logger: 2 fields (module, nodeID) - pre-encoded
ctx logger:       5 fields (traceID, spanID, ...) - pre-encoded

→ Select ctx logger as base, only need to encode component's 2 fields
→ Faster than using component logger and encoding 5 ctx fields

Context Fields

// Add fields to context (fields accumulate)
ctx = mlog.WithFields(ctx, mlog.String("request_id", "abc123"))
ctx = mlog.WithFields(ctx, mlog.Int64("user_id", 42))

// Subsequent logs automatically include these fields
mlog.Info(ctx, "processing request")
// Output: {"msg":"processing request", "request_id":"abc123", "user_id":42, ...}

Field Ordering and Duplicate Keys

ctx = mlog.WithFields(ctx, mlog.String("status", "pending"))
ctx = mlog.WithFields(ctx, mlog.String("status", "completed"))

mlog.Info(ctx, "task done")
// Output keeps both fields in order:
// {"msg":"task done", "status":"pending", "status":"completed", ...}

mlog does not automatically deduplicate fields across context fields, component Logger fields, or call-site fields. This matches zap's field-list behavior and avoids hidden work on hot logging paths. Callers should avoid reusing the same key for different meanings in one log entry. If duplicate keys are emitted, downstream JSON consumers decide how to interpret them, and behavior can differ across tools.

APIs that project fields into a map, such as GetPropagated, cannot preserve duplicate keys; for those map projections, later propagated fields with the same key overwrite earlier values.

Cross-Service Field Propagation

// Client: Mark fields for propagation
ctx = mlog.WithFields(ctx,
    mlog.FieldCollectionName("my_collection", mlog.OptPropagated()),
    mlog.FieldCollectionID(12345, mlog.OptPropagated()),
)

// Get propagated fields (for manual propagation scenarios)
props := mlog.GetPropagated(ctx)
// props = map[string]string{"collectionName": "my_collection", "collectionID": "12345"}

gRPC Interceptors

Interceptors are defined in interceptor.go within the mlog package (not a subpackage):

import "github.com/milvus-io/milvus/pkg/v3/mlog"

// Server configuration
server := grpc.NewServer(
    grpc.UnaryInterceptor(mlog.UnaryServerInterceptor("querynode")),
    grpc.StreamInterceptor(mlog.StreamServerInterceptor("querynode")),
)

// Client configuration
conn, _ := grpc.Dial(addr,
    grpc.WithUnaryInterceptor(mlog.UnaryClientInterceptor()),
    grpc.WithStreamInterceptor(mlog.StreamClientInterceptor()),
)

Interceptor Functions:

Interceptor	Function
`UnaryServerInterceptor(module)`	Extract propagated mlog fields from metadata and auto-add module
`StreamServerInterceptor(module)`	Same as above, for streaming RPC
`UnaryClientInterceptor()`	Inject propagated fields into outgoing metadata
`StreamClientInterceptor()`	Same as above, for streaming RPC

Dynamic Log Level

// Change log level at runtime
mlog.SetLevel(mlog.DebugLevel)
mlog.SetLevel(mlog.WarnLevel)

// Get current level
level := mlog.GetLevel()

// Get AtomicLevel (for custom configuration integration)
atomicLevel := mlog.GetAtomicLevel()

Performance Optimizations

1. Early Return & LevelEnabled Guard

Log functions return immediately when the level is disabled, avoiding field processing. For hot paths where field construction itself is expensive, use LevelEnabled to skip the entire block:

// Internal early return (automatic)
func Log(ctx context.Context, level Level, msg string, fields ...Field) {
    if !globalLevel.Enabled(level) {
        return  // Fast return, zero overhead
    }
    // ...
}

// Caller-side guard for expensive field construction
if mlog.LevelEnabled(mlog.DebugLevel) {
    mlog.Debug(ctx, "details", mlog.String("dump", expensiveDump()))
}

2. Lazy Field Encoding

Context fields use zap.WithLazy for deferred encoding, only encoded when log is actually written:

// WithFields uses WithLazy internally
ctx = mlog.WithFields(ctx, mlog.String("key", "value"))

// Fields are only encoded when log is written
mlog.Info(ctx, "message")  // Fields encoded here

// If log level is disabled, fields are never encoded
mlog.SetLevel(mlog.ErrorLevel)
mlog.Debug(ctx, "message")  // Fields not encoded, zero overhead

Note: Global fields (like nodeID) use .With() for immediate encoding since they always need to be output.

3. Logger Caching

Each logContext caches the constructed logger, avoiding repeated construction:

type logContext struct {
    fields []Field
    logger *zap.Logger  // Cached logger
}

4. Ordered Field Accumulation

Context fields are appended to an ordered slice so log output preserves the order in which fields are attached:

ctx = mlog.WithFields(ctx, mlog.String("request_id", reqID))
ctx = mlog.WithFields(ctx, mlog.FieldCollectionID(collectionID))

Best Practices

1. Always Pass Valid Context

// Recommended
mlog.Info(ctx, "message")

// Not recommended (adds _ctx_nil warning field)
mlog.Info(nil, "message")

2. Add Request-Level Fields at Entry Points

func HandleRequest(ctx context.Context, req *Request) {
    ctx = mlog.WithFields(ctx,
        mlog.String("request_id", req.ID),
        mlog.String("method", req.Method),
    )
    // All subsequent logs automatically include these fields
    processRequest(ctx, req)
}

3. Use OptPropagated() for Cross-Service Fields

// Use OptPropagated() for fields that need cross-service tracing
ctx = mlog.WithFields(ctx,
    mlog.FieldCollectionName(collectionName, mlog.OptPropagated()),
    mlog.FieldCollectionID(collectionId, mlog.OptPropagated()),
)

4. Use Predefined FieldXxx Constructors

// Recommended: Use FieldXxx constructors
mlog.FieldCollectionName(name)

// Not recommended: Hard-coded key strings
mlog.String("collectionName", name)

5. Specify Module Name in Server Interceptors

// Each service uses its corresponding module name
mlog.UnaryServerInterceptor("proxy")
mlog.UnaryServerInterceptor("querynode")
mlog.UnaryServerInterceptor("datanode")

API Reference

mlog Package

Global Functions:

Function	Description
`Debug(ctx, msg, fields...)`	Log at Debug level
`Info(ctx, msg, fields...)`	Log at Info level
`Warn(ctx, msg, fields...)`	Log at Warn level
`Error(ctx, msg, fields...)`	Log at Error level
`DPanic(ctx, msg, fields...)`	Log at DPanic level
`Panic(ctx, msg, fields...)`	Log at Panic level, then panic
`Fatal(ctx, msg, fields...)`	Log at Fatal level, then exit
`Log(ctx, level, msg, fields...)`	Log at specified level
`With(fields...)`	Create Logger with immediately encoded fields
`WithLazy(fields...)`	Create Logger with lazily encoded fields
`WithOptions(opts...)`	Create Logger from the global logger with options applied
`WithFields(ctx, fields...)`	Add fields to context
`FieldsFromContext(ctx)`	Extract fields from context
`GetPropagated(ctx)`	Get propagated fields
`LevelEnabled(level)`	Check if a level would be logged
`SetLevel(level)`	Set log level
`GetLevel()`	Get current log level
`GetAtomicLevel()`	Get AtomicLevel for custom config integration

Logger Type:

Method	Description
`With(fields...)`	Create component-level Logger with immediately encoded fields
`WithLazy(fields...)`	Create component-level Logger with lazily encoded fields
`(*Logger) With(fields...)`	Add fields (immediately encoded), returns new Logger
`(*Logger) WithLazy(fields...)`	Add fields (lazily encoded), returns new Logger
`(*Logger) WithOptions(opts...)`	Apply logger options, returns new Logger
`(*Logger) Level()`	Get current log level
`(*Logger) LevelEnabled(level)`	Check if a level would be logged
`(*Logger) Debug(ctx, msg, fields...)`	Log at Debug level
`(*Logger) Info(ctx, msg, fields...)`	Log at Info level
`(*Logger) Warn(ctx, msg, fields...)`	Log at Warn level
`(*Logger) Error(ctx, msg, fields...)`	Log at Error level
`(*Logger) DPanic(ctx, msg, fields...)`	Log at DPanic level
`(*Logger) Panic(ctx, msg, fields...)`	Log at Panic level, then panic
`(*Logger) Fatal(ctx, msg, fields...)`	Log at Fatal level, then exit
`(*Logger) Log(ctx, level, msg, fields...)`	Log at specified level

Rate-Limited Functions (package-level and Logger):

Function	Description
`RatedDebug(ctx, limit, msg, fields...)`	Rate-limited log at Debug level
`RatedInfo(ctx, limit, msg, fields...)`	Rate-limited log at Info level
`RatedWarn(ctx, limit, msg, fields...)`	Rate-limited log at Warn level
`RatedError(ctx, limit, msg, fields...)`	Rate-limited log at Error level
`RatedLog(ctx, level, limit, msg, fields...)`	Rate-limited log at specified level

Rate-limited functions use per-call-site rate.Limiter (lazy-initialized via sync.Map). When a log entry is suppressed, a _suppressed count field is attached to the next allowed entry.

gRPC Interceptors (in mlog package)

Function	Description
`UnaryServerInterceptor(module)`	Unary server interceptor
`StreamServerInterceptor(module)`	Stream server interceptor
`UnaryClientInterceptor()`	Unary client interceptor
`StreamClientInterceptor()`	Stream client interceptor

Field Constructors

Complete list of field constructors (corresponding to zap):

Category	Functions
String	`String`, `Stringp`, `Strings`, `ByteString`, `ByteStrings`, `Stringer`
Bool	`Bool`, `Boolp`, `Bools`
Int	`Int`, `Intp`, `Ints`, `Int8/16/32/64` and their `p`/`s` variants
Uint	`Uint`, `Uintp`, `Uints`, `Uint8/16/32/64` and their `p`/`s` variants, `Uintptr`, `Uintptrp`, `Uintptrs`
Float	`Float32`, `Float32p`, `Float32s`, `Float64`, `Float64p`, `Float64s`
Complex	`Complex64`, `Complex64p`, `Complex64s`, `Complex128`, `Complex128p`, `Complex128s`
Time	`Time`, `Timep`, `Times`, `Duration`, `Durationp`, `Durations`
Error	`Err`, `NamedError`, `Errors`
Special	`Any`, `Binary`, `Reflect`
Structured	`Object`, `Array`, `Inline`, `Namespace`
Debug	`Stack`, `StackSkip`, `Skip`
Options	`AddCallerSkip`
Aliases	`ObjectEncoder`, `ObjectMarshaler`, `ObjectMarshalerFunc`
Propagation	`OptPropagated` on well-known `FieldXxx` constructors

Well-Known Field Functions

Predefined field constructors providing type-safe field creation:

Function	Type	Description
`FieldNodeID(val)`	int64	Node ID
`FieldModule(val)`	string	Module name
`FieldTraceID(val)`	string	Trace ID
`FieldSpanID(val)`	string	Span ID
`FieldDbID(val)`	int64	Database ID
`FieldDbName(val)`	string	Database name
`FieldCollectionID(val)`	int64	Collection ID
`FieldCollectionName(val)`	string	Collection name
`FieldPartitionID(val)`	int64	Partition ID
`FieldPartitionName(val)`	string	Partition name
`FieldSegmentID(val)`	int64	Segment ID
`FieldIndexID(val)`	int64	Index ID
`FieldFieldID(val)`	int64	Field ID
`FieldTaskID(val)`	int64	Task ID
`FieldBroadcastID(val)`	int64	Broadcast ID
`FieldJobID(val)`	int64	Job ID
`FieldBuildID(val)`	int64	Build ID
`FieldVChannel(val)`	string	Virtual channel name
`FieldPChannel(val)`	string	Physical channel name
`FieldMessageID(val)`	ObjectMarshaler	Message ID
`FieldMessage(val)`	ObjectMarshaler	Message content

Usage Example:

// Using FieldXxx functions (recommended)
mlog.Info(ctx, "segment loaded",
    mlog.FieldCollectionID(12345),
    mlog.FieldSegmentID(67890),
)

// Equivalent raw key usage (not recommended — keys are unexported)
mlog.Info(ctx, "segment loaded",
    mlog.Int64("collectionID", 12345),
    mlog.Int64("segmentID", 67890),
)

Benchmark Report

Environment: Intel Core i7-8700 @ 3.20GHz, Linux amd64, Go 1.24

Baseline: Native zap.Logger

Benchmark	ns/op	B/op	allocs/op
ZapInfo	377	0	0
ZapInfoWithFields (3 fields)	598	192	1
ZapInfoDisabledLevel	6.4	0	0

Package-Level Functions

Benchmark	ns/op	B/op	allocs/op
MlogInfo	382	0	0
MlogInfoWithFields (3 fields)	627	192	1
MlogInfoWithContextFields	415	0	0
MlogInfoWithContext+CallFields	647	192	1
MlogInfoDisabledLevel	2.7	0	0

Logger Methods

Benchmark	ns/op	B/op	allocs/op
LoggerInfo	404	0	0
LoggerInfoWithFields (3 fields)	624	192	1
LoggerInfoWithContextFields	471	0	0
LoggerInfoDisabledLevel	2.9	0	0

Rate-Limited Functions

Benchmark	ns/op	B/op	allocs/op
RatedInfoAllowed	918	248	2
RatedInfoSuppressed	521	248	2
RatedInfoDisabledLevel	2.9	0	0
LoggerRatedInfoAllowed	924	248	2
LoggerRatedInfoSuppressed	507	248	2

Key Takeaways

mlog vs zap (zero overhead): mlog.Info achieves 0 allocs and near-identical latency to bare zap.Info, with only ~5ns overhead from context lookup and atomic load of the global logger.
Zero allocation with context fields: When fields are pre-encoded via WithFields, MlogInfoWithContextFields achieves 0 allocs at 415ns — faster than native zap.Info with 3 fields (598ns, 1 alloc).
Disabled level is extremely fast: ~2.7ns with 0 allocs, 2.4x faster than zap's 6.4ns, because mlog returns before calling into zap.
Rate limiting (allowed): ~920ns total, with overhead from runtime.Caller(1) + sync.Map lookup + rate.Limiter.Allow().
Rate limiting (suppressed): ~510ns, skips log encoding entirely, only performs atomic operations and runtime.Caller.