grovelog

README

GroveLog

GroveLog is a flexible logging library for Go, built on top of the standard log/slog package. It provides enhanced formatting options, color support, group handling, context-aware logging, and optimized performance.

Features

• Multiple output formats: JSON, Plain Text, and Colored Text
• Thread-safe for concurrent use
• Efficient memory usage with buffer pooling
• Support for structured logging with attributes
• Advanced grouping of attributes with nesting
• Context-aware logging with attribute propagation
• Error wrapping with context preservation
• Compatible with the standard log/slog interface
• Customizable time formats

Installation

go get github.com/AlonMell/grovelog

Quick Start

package main

import (
    "os"
    "log/slog"

    "github.com/AlonMell/grovelog"
)

func main() {
    // Create a color logger with INFO level
    opts := grovelog.NewOptions(slog.LevelInfo, "", grovelog.Color)
    logger := grovelog.NewLogger(os.Stdout, opts)

    // Simple logging
    logger.Info("Hello, GroveLog!")

    // With attributes
    logger.Info("User logged in",
        "user_id", 1234,
        "source", "api")

    // With groups
    dbLogger := logger.WithGroup("database")
    dbLogger.Info("Query executed",
        "query", "SELECT * FROM users",
        "duration_ms", 42)
}

Output Formats

GroveLog supports three output formats:

JSON Format

opts := grovelog.NewOptions(slog.LevelInfo, "", grovelog.JSON)
logger := grovelog.NewLogger(os.Stdout, opts)
logger.Info("Hello JSON", "key", "value")

Output:

{"time":"2025-04-07T10:30:45.123456789Z","level":"INFO","msg":"Hello JSON","key":"value"}

Plain Text Format

opts := grovelog.NewOptions(slog.LevelInfo, "", grovelog.Plain)
logger := grovelog.NewLogger(os.Stdout, opts)
logger.Info("Hello Plain", "key", "value")

Output:

time=2025-04-07T10:30:45.123456789Z level=INFO msg="Hello Plain" key=value

Color Format

opts := grovelog.NewOptions(slog.LevelInfo, "", grovelog.Color)
logger := grovelog.NewLogger(os.Stdout, opts)
logger.Info("Hello Color", "key", "value")

Output:

[10:30:45.123] INFO: Hello Color {"key":"value"}

Advanced Usage

Custom Time Format

opts := grovelog.NewOptions(slog.LevelInfo, "2006-01-02 15:04:05", grovelog.Color)
logger := grovelog.NewLogger(os.Stdout, opts)

Nested Groups

apiLogger := logger.WithGroup("api")
userLogger := apiLogger.WithGroup("users")
userLogger.Info("User created", "id", 1001, "email", "user@example.com")

Output:

[10:30:45.123] INFO: User created {"api.users.id":1001,"api.users.email":"user@example.com"}

Group and Attributes

authLogger := logger.WithGroup("auth").With("service", "oauth")
authLogger.Info("Token generated", "expires_in", 3600)

Performance

GroveLog is designed with performance in mind:

• Buffer pooling to reduce memory allocations
• Efficient JSON serialization
• Minimal lock contention for thread safety

Development

Testing, Linting, Coverage, Benchmarks

make help

License

MIT License - see the LICENSE file for details.

Documentation

Index

• Constants
• func NewHandler(out io.Writer, opts Options) slog.Handler
• func NewLogger(out io.Writer, opts Options) *slog.Logger
• type Format
• type Handler
  • func (h *Handler) Enabled(ctx context.Context, level slog.Level) bool
  • func (h *Handler) Handle(ctx context.Context, r slog.Record) error
  • func (h *Handler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (h *Handler) WithGroup(name string) slog.Handler
• type Options
  • func NewOptions(level slog.Level, timeFormat string, format Format) Options

Constants

const DefaultTimeFormat = "[15:05:05.000]"

DefaultTimeFormat is the default time format

Functions

func NewHandler

func NewHandler(out io.Writer, opts Options) slog.Handler

NewHandler creates a new slog.Handler

func NewLogger

func NewLogger(out io.Writer, opts Options) *slog.Logger

NewLogger creates a new slog.Logger with the specified options

Types

type Format

type Format int

Format defines log output format

const (
	// JSON format outputs logs in JSON format
	JSON Format = iota
	// Plain format outputs logs in plain text format
	Plain
	// Color format outputs logs with color highlighting
	Color
)

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler implements the slog.Handler interface with custom formatting

func (*Handler) Enabled

func (h *Handler) Enabled(ctx context.Context, level slog.Level) bool

Enabled determines if this level should be logged

func (*Handler) Handle

func (h *Handler) Handle(ctx context.Context, r slog.Record) error

Handle processes a log record The gocritic linter is disabled here because it warns about passing large values (like context and record) by value, but this signature is required by the slog.Handler interface

func (*Handler) WithAttrs

func (h *Handler) WithAttrs(attrs []slog.Attr) slog.Handler

WithAttrs returns a new Handler with the given attributes added

func (*Handler) WithGroup

func (h *Handler) WithGroup(name string) slog.Handler

WithGroup returns a new Handler with the given group name added

type Options

type Options struct {
	SlogOpts   *slog.HandlerOptions
	TimeFormat string
	Format     Format
}

Options holds configuration options for the logger

func NewOptions

func NewOptions(level slog.Level, timeFormat string, format Format) Options

NewOptions creates Options with the specified level, time format, and output format