logging

README

Logging (日志系统)

pkg/logging 提供了 GoRAG 框架的统一日志接口及其工业级实现。

设计哲学

在工业级 RAG 系统中，日志不仅是调试工具，更是审计和排障的关键依据。本包采用了平权化接口设计，API 风格完全仿照 uber-go/zap 的调用约定：

1. 接口隔离：框架核心只依赖 Logger 接口，不绑定任何具体实现。
2. 渐进式升级：提供从极简控制台打印到高性能滚动日志的全量支持。
3. 零学习成本：用法与 zap 完全一致，key-value 交替传入。

核心接口

type Logger interface {
    Info(msg string, keyvals ...any)
    Error(msg string, err error, keyvals ...any)
    Debug(msg string, keyvals ...any)
    Warn(msg string, keyvals ...any)
}

使用示例

logger.Info("server started", "port", 8080, "host", "localhost")
logger.Warn("slow request", "duration", 2.5*time.Second, "path", "/api/search")
logger.Error("connection failed", err, "addr", "127.0.0.1:3306")
logger.Debug("cache hit", "key", userID)
// 不带字段也可以
logger.Info("heartbeat")

实现列表

1. ConsoleLogger (控制台日志)

• 用途：本地开发、单元测试。
• 特点：直接输出到 stdout。
• 初始化：logging.DefaultConsoleLogger()

2. FileLogger (文件日志)

• 用途：轻量级文件输出场景。
• 特点：写入指定文件，支持级别过滤。
• 初始化：

  logger, err := logging.DefaultFileLogger("app.log", logging.WithLevel(logging.DEBUG))
  defer logger.(*logging.defaultLogger).Close()
  

3. ZapLogger (工业级高性能日志)

• 用途：生产环境、高并发场景。
• 特点：
  • 基于 uber-go/zap，极低的内存分配和极高的吞吐量。
  • 自动滚动 (Rotation)：集成 lumberjack，支持基于文件大小、保留天数自动切割日志。
  • 日志压缩：旧日志自动 gzip 压缩。
  • 多路输出 (Tee)：支持同时输出 JSON 格式和控制台高亮格式。
• 初始化：

  logger := logging.DefaultZapLogger(logging.ZapConfig{
      Filename:   "logs/gorag.log",
      MaxSize:    100,  // MB
      MaxAge:     30,   // Days
      MaxBackups: 7,    // 备份数
      Compress:   true,
      Console:    true, // 同时打印到控制台
  })
  

4. NoopLogger (静默日志)

• 用途：不需要任何日志输出的场景或基准测试。
• 初始化：logging.DefaultNoopLogger()

在 GoRAG 中快速集成

// 生产环境推荐配置
idx, _ := gorag.NewHybridIndexer(
    logging.DefaultZapLogger(logging.ZapConfig{
        Filename:   "./data/logs/app.log",
        MaxSize:    500,
        MaxBackups: 7,
        MaxAge:     5,
        Console:    true,
    }),
    vectorStore, graphStore, docStore, llm, embedder,
)

Documentation

Overview

Package logging provides structured logging capabilities for the goRAG framework. It offers a simple, flexible logging interface with support for multiple log levels, file and console output, and structured field logging.

The API is designed to mirror uber-go/zap's calling convention:

logger.Info("server started", "port", 8080, "host", "localhost")
logger.Warn("slow request", "duration", 2.5*time.Second)
logger.Error("connection failed", err, "addr", "127.0.0.1:3306")
logger.Debug("cache hit", "key", userID)

The package provides three main implementations:

• Console logger: Outputs to stdout with minimal formatting
• File logger: Writes to a file with configurable log level
• No-op logger: Discards all log output (useful for testing)
• Zap logger: High-performance logger with log rotation (requires zap dependency)

Index

• type Level
  • func (l Level) String() string
• type Logger
  • func DefaultConsoleLogger() Logger
  • func DefaultFileLogger(filePath string, opts ...Option) (Logger, error)
  • func DefaultNoopLogger() Logger
  • func DefaultZapLogger(cfg ZapConfig) Logger
• type Option
  • func WithLevel(level Level) Option
• type ZapConfig

Types

type Level

type Level int

Level represents the severity level of a log message. Log levels are ordered from least to most severe: DEBUG < INFO < WARN < ERROR.

const (
	// DEBUG level is for detailed debugging information.
	DEBUG Level = iota

	// INFO level is for general operational information.
	INFO

	// WARN level is for warning messages that indicate potential issues.
	WARN

	// ERROR level is for error messages indicating failures.
	ERROR
)

Log level constants define the severity of log messages. Messages with a level below the configured threshold will not be logged.

func (Level) String

func (l Level) String() string

String returns the string representation of the log level.

type Logger

type Logger interface {
	// Info logs an informational message with optional key-value pairs.
	Info(msg string, keyvals ...any)

	// Error logs an error message. The error is automatically included in the output.
	// Additional key-value pairs can be provided after the error.
	Error(msg string, err error, keyvals ...any)

	// Debug logs a debug message with optional key-value pairs.
	Debug(msg string, keyvals ...any)

	// Warn logs a warning message with optional key-value pairs.
	Warn(msg string, keyvals ...any)
}

Logger defines the interface for structured logging. All methods accept optional key-value pairs (alternating string keys and any values), following the same convention as uber-go/zap.

Example:

logger.Info("user logged in", "user_id", 123, "ip", "192.168.1.1")
logger.Error("database error", err, "query", sql)
logger.Warn("rate limit approaching", "remaining", 5)
logger.Debug("processing chunk", "chunkID", chunk.ID)

func DefaultConsoleLogger

func DefaultConsoleLogger() Logger

DefaultConsoleLogger creates a logger that writes to stdout with INFO level.

func DefaultFileLogger

func DefaultFileLogger(filePath string, opts ...Option) (Logger, error)

DefaultFileLogger creates a logger that writes to a file. The file is created if it doesn't exist, and appended to if it does.

func DefaultNoopLogger

func DefaultNoopLogger() Logger

DefaultNoopLogger creates a logger that discards all output.

func DefaultZapLogger

func DefaultZapLogger(cfg ZapConfig) Logger

DefaultZapLogger creates a high-performance logger using uber-go/zap with lumberjack for log rotation.

type Option

type Option func(*defaultLogger)

Option is a function that configures a defaultLogger.

func WithLevel

func WithLevel(level Level) Option

WithLevel returns an Option that sets the minimum log level.

type ZapConfig

type ZapConfig struct {
	// Filename is the file to write logs to.
	Filename string
	// MaxSize is the maximum size in megabytes of the log file before it gets rotated.
	MaxSize int
	// MaxBackups is the maximum number of old log files to retain.
	MaxBackups int
	// MaxAge is the maximum number of days to retain old log files.
	MaxAge int
	// Compress determines if the rotated log files should be compressed using gzip.
	Compress bool
	// Console specifies if logs should also be printed to standard output.
	Console bool
}

ZapConfig defines the options for the Zap rolling logger