The Log API provides a structured logging system with level filtering, context support, and multiple output formats.
Interfaces
Logger
Core logger interface.
type Logger interface {
Log(level Level, keyvals ...any) error
}
Log level (Debug, Info, Warn, Error, Fatal)
Key-value pairs for structured logging. Must be provided in pairs.
Types
Level
Log level enumeration.
type Level int8
const (
LevelDebug Level = iota - 1 // -1
LevelInfo // 0
LevelWarn // 1
LevelError // 2
LevelFatal // 3
)
Debug level for detailed information
Info level for general information
Warn level for warning messages
Error level for error messages
Fatal level for fatal errors
func (l Level) String() string
func (l Level) Key() string
Helper
Logger helper with convenience methods.
type Helper struct {
// contains filtered or unexported fields
}
Functions
NewStdLogger
Creates a new standard logger.
func NewStdLogger(w io.Writer) Logger
Output writer (e.g., os.Stdout, file)
import "os"
logger := log.NewStdLogger(os.Stdout)
NewHelper
Creates a logger helper with convenience methods.
func NewHelper(logger Logger, opts ...Option) *Helper
helper := log.NewHelper(logger)
helper.Info("Server started")
helper.Errorf("Failed to connect: %v", err)
With
Adds fields to the logger.
func With(l Logger, kv ...any) Logger
Key-value pairs to add to all log messages
logger = log.With(logger,
"service", "user-service",
"version", "v1.0.0",
)
WithContext
Attaches a context to the logger.
func WithContext(ctx context.Context, l Logger) Logger
NewFilter
Creates a logger with filtering.
func NewFilter(logger Logger, opts ...FilterOption) *Filter
logger = log.NewFilter(logger,
log.FilterLevel(log.LevelInfo),
log.FilterKey("password", "token"),
)
ParseLevel
Parses a level string into a Level value.
func ParseLevel(s string) Level
Level string (“DEBUG”, “INFO”, “WARN”, “ERROR”, “FATAL”)
Parsed level (defaults to LevelInfo if invalid)
Helper Methods
Debug / Debugf / Debugw
Logs at debug level.
func (h *Helper) Debug(a ...any)
func (h *Helper) Debugf(format string, a ...any)
func (h *Helper) Debugw(keyvals ...any)
Info / Infof / Infow
Logs at info level.
func (h *Helper) Info(a ...any)
func (h *Helper) Infof(format string, a ...any)
func (h *Helper) Infow(keyvals ...any)
Warn / Warnf / Warnw
Logs at warn level.
func (h *Helper) Warn(a ...any)
func (h *Helper) Warnf(format string, a ...any)
func (h *Helper) Warnw(keyvals ...any)
Error / Errorf / Errorw
Logs at error level.
func (h *Helper) Error(a ...any)
func (h *Helper) Errorf(format string, a ...any)
func (h *Helper) Errorw(keyvals ...any)
Fatal / Fatalf / Fatalw
Logs at fatal level and exits.
func (h *Helper) Fatal(a ...any)
func (h *Helper) Fatalf(format string, a ...any)
func (h *Helper) Fatalw(keyvals ...any)
Filter Options
FilterLevel
Filters logs below the specified level.
func FilterLevel(level Level) FilterOption
FilterKey
Masks specified keys in log output.
func FilterKey(key ...string) FilterOption
FilterValue
Masks specified values in log output.
func FilterValue(value ...string) FilterOption
FilterFunc
Custom filter function.
func FilterFunc(f func(level Level, keyvals ...any) bool) FilterOption
Helper Options
WithMessageKey
Sets the message key.
func WithMessageKey(k string) Option
WithSprint
Sets custom sprint function.
func WithSprint(sprint func(...any) string) Option
WithSprintf
Sets custom sprintf function.
func WithSprintf(sprintf func(format string, a ...any) string) Option
Usage Examples
Basic Logging
package main
import (
"os"
"github.com/go-kratos/kratos/v2/log"
)
func main() {
logger := log.NewStdLogger(os.Stdout)
helper := log.NewHelper(logger)
helper.Info("Application started")
helper.Infof("Port: %d", 8080)
helper.Infow("event", "startup", "port", 8080)
}
Structured Logging with Fields
logger := log.NewStdLogger(os.Stdout)
logger = log.With(logger,
"service", "user-service",
"version", "v1.0.0",
"env", "production",
)
helper := log.NewHelper(logger)
helper.Info("Server started")
// Output: INFO service=user-service version=v1.0.0 env=production msg="Server started"
Level Filtering
logger := log.NewStdLogger(os.Stdout)
logger = log.NewFilter(logger,
log.FilterLevel(log.LevelWarn),
)
helper := log.NewHelper(logger)
helper.Debug("This won't be logged")
helper.Info("This won't be logged")
helper.Warn("This will be logged")
helper.Error("This will be logged")
Sensitive Data Filtering
logger := log.NewFilter(
log.NewStdLogger(os.Stdout),
log.FilterKey("password", "token", "secret"),
)
helper := log.NewHelper(logger)
helper.Infow(
"user", "john",
"password", "secret123", // Will be masked as ***
"email", "[email protected]",
)
// Output: INFO user=john password=*** [email protected]
Context Logging
func handleRequest(ctx context.Context) {
logger := log.NewStdLogger(os.Stdout)
logger = log.WithContext(ctx, logger)
logger = log.With(logger,
"request_id", requestID(ctx),
"user_id", userID(ctx),
)
helper := log.NewHelper(logger)
helper.Info("Processing request")
}
Custom Logger Implementation
type myLogger struct {
// custom fields
}
func (l *myLogger) Log(level log.Level, keyvals ...any) error {
// Custom logging implementation
// Send to external service, format differently, etc.
return nil
}
// Use custom logger
logger := &myLogger{}
helper := log.NewHelper(logger)