v0.8.0

Compare Source

Major release with breaking changes to logger and stacktrace packages. Please review the Breaking Changes section carefully before upgrading.

This release focuses on improving the logger and stacktrace packages with better caller capture, thread safety, and a simplified adapter interface.

⚠️ Breaking Changes

• Change logger.New() constructor signature (a818939, dbbf7a2, ef40e6a)
  Constructor changed from New(adapter Adapter, maxLevel int) to New(adapter Adapter, opts ...Option). The maxLevel parameter is now passed via WithLevel(level) option.

• Rework logger.Adapter interface (3e99e98)
  The Adapter interface has been simplified. Logger name and stacktrace functionality is now handled by the logger itself, with these values passed as fields.

• Remove NopAdapter and change nil adapter handling (ac007a8)
  NopAdapter has been removed. All loggers with nil adapter are now treated as no-op loggers. No-op loggers can only be created with logger.NewNop(). logger.New() now panics if it receives a nil adapter.

• Change logger name and error passthrough mechanism (dbbf7a2)
  Logger name and error are now passed to adapters as fields rather than handled in a special way.

• Rework stacktrace package API (7d77230, e4d4715)
  stacktrace.Capture() renamed to stacktrace.CaptureStack(). Stack type is now read-only; modification methods have been removed.

Added

• New logger configuration options (a818939, dbbf7a2, ef40e6a)
  Added multiple new options for configuring logger behavior:

  • WithLevel(level int) - Set maximum log level
  • WithCallerAtLevel(level int) - Enable automatic caller capture at or below specified level
  • WithCallerMapper(fn) - Custom caller frame mapping with DefaultCallerMapper provided
  • WithNameMapper(fn) - Custom logger name field mapping
  • WithNameFormatter(fn) - Custom logger name formatting (hierarchical with : or replacement strategies)
  • WithErrorMapper(fn) - Custom error field mapping
  • WithStackTraceMapper(fn) - Custom stacktrace field mapping

• New stacktrace.CaptureCaller() function (e4d4715)
  Captures a single stack frame with specified skip. More performant for cases when only the caller's frame is required.

• New stacktrace.Frame type (6b86721)
  Represents a single stack frame containing program counter, file path, line number, and function name. Simplified representation of runtime.Frame that is safe to store and use after stack trace capture.

• Logger comparison method (ef40e6a)
  New logger.IsEqual() method for comparing if two loggers are functionally the same.

• Thread-safe buffer adapter improvements (bb3745f)
  bufferadapter.LogEntries type is now thread-safe. New bufferadapter.NewWithBuffer() method allows usage of pre-existing buffer.

• Stacktrace capture support (dbbf7a2)
  Full stacktrace capture functionality integrated into logger package.

Changed

• Finalize logger documentation (dbbf7a2)
  Comprehensive documentation added to the logger package.

• Improve adapter documentation (3e99e98)
  Added detailed package documentation for logrusadapter, slogadapter, and zapadapter.

• Simplify bufferadapter.New() (bb3745f)
  Now creates and returns both adapter and buffer together for convenience.

• Upgrade golangci-lint configuration (17f1b9c)
  Updated linter config to support golangci-lint v2.6 and fixed all lint issues.

Fixed

• Fix logger name carrying with multiple children (ef40e6a)
  Previously, when multiple child loggers changed names, it would result in multiple fields with the same name. The new approach allows for logger name rewrites and custom logger name generation strategies.

Upgrade Guide

For Logger Users:

1. Updating logger.New() calls:

// Before (v0.7.0)
logger := logger.New(adapter, logger.LevelDebug)

// After (v0.8.0)
logger := logger.New(adapter, logger.WithLevel(logger.LevelDebug))

// Or use default level (LevelInfo) with no options
logger := logger.New(adapter)

2. Creating no-op loggers:

// Before
logger := logger.New(logger.NopAdapter{}, someLevel)

// After
logger := logger.NewNop()

3. Calling stacktrace functions:

// Before
stack := stacktrace.Capture(skip)

// After
stack := stacktrace.CaptureStack(skip)

// Or for single frame:
frame := stacktrace.CaptureCaller(skip)

4. Modifying Stack instances:

Remove any code that modifies Stack - it's now read-only. Capture the stack with the correct skip value instead.

For Adapter Implementers:

The Adapter interface has been simplified. Logger name and stacktrace functionality is now handled by the logger itself, with these values passed as fields.

Review the updated documentation in logrusadapter, slogadapter, and zapadapter packages for examples of the new implementation pattern.

Contributors

• a.zinoviev a.zinoviev@gaijin.team