golib/logger/README.md

logger Package Documentation

The logger package provides a robust, thread-safe, and extensible logging system for Go applications.
It is built primarily on top of the logrus library, but also implements wrappers and integration for other logging systems such as

• the standard Go log package,
• Logrus
• SPF13 / jwalterweatherman,
• HashiCorp loggers
• GORM loggers.
• ...

---

Features

• Multiple log levels: Debug, Info, Warn, Error, Fatal, Panic, Nil
• Structured logging with custom fields and data
• Output to stdout, stderr, files, and syslog (via hooks)
• Dynamic configuration and runtime updates
• Filtering of log messages by pattern
• Integration with Go's log.Logger, spf13/jwalterweatherman, and others
• Cloning and context-aware loggers
• Thread-safe operations
• Access log support for HTTP servers
• Custom hooks and extensibility

---

Main Types & Interfaces

Logger Interface

The main interface for logging, supporting both structured and unstructured logs.

• SetLevel(lvl Level), GetLevel()
• SetIOWriterLevel(lvl Level), GetIOWriterLevel()
• SetIOWriterFilter(pattern ...), AddIOWriterFilter(pattern ...)
• SetOptions(opt *Options), GetOptions()
• SetFields(fields Fields), GetFields()
• Clone() Logger
• SetSPF13Level(lvl Level, log *jwalterweatherman.Notepad)
• GetStdLogger(lvl Level, logFlags int) *log.Logger
• SetStdLogger(lvl Level, logFlags int)
• Logging methods: Debug, Info, Warning, Error, Fatal, Panic, LogDetails, CheckError, Entry, Access
• Implements io.WriteCloser for compatibility

Logger Construction

• New(ctx FuncContext) Logger
  Create a new logger instance with a context provider.

---

Configuration

The logger is configured via the Options struct, which allows you to:

• Enable/disable stdout and stderr outputs, with color and trace options
• Add multiple file outputs with custom settings
• Add syslog outputs
• Set trace filters for file paths
• Control stack trace and timestamp inclusion

Configuration can be updated at runtime using SetOptions.

---

Usage Example

import (
    "github.com/nabbar/golib/logger"
    "github.com/nabbar/golib/logger/config"
    "github.com/nabbar/golib/logger/level"
    "context"
)

log := logger.New(func() context.Context { return context.Background() })
defer log.Close()

log.SetLevel(level.DebugLevel)
log.SetOptions(&config.Options{
    Stdout: &config.OptionsStd{EnableTrace: true},
})

log.Info("Application started", nil)
log.Debug("Debugging details: %v", map[string]interface{}{"foo": "bar"})
log.SetFields(log.GetFields().Add("service", "my-service"))
log.Error("An error occurred: %s", nil, "details")

---

Error Handling

All errors are wrapped with custom codes for diagnostics.
Use err.Error() for user-friendly messages and check error codes for troubleshooting.

---

Subpackages

The logger package is composed of several subpackages, each providing specialized features.
See each section for detailed documentation:

• config — Logger configuration structures and helpers. See the Config subpackage documentation for more details.
• entry — Log entry management and structured logging. See the Entry subpackage documentation for more details.
• fields — Structured fields for log entries. See the Fields subpackage documentation for more details.
• hookfile — File output hooks for logrus. See the HookFile subpackage documentation for more details.
• hookstderr — Stderr output hooks for logrus. See the HookStderr subpackage documentation for more details.
• hookstdout — Stdout output hooks for logrus. See the HookStdout subpackage documentation for more details.
• hooksyslog — Syslog output hooks for logrus. See the HookSyslog subpackage documentation for more details.
• level — Log level definitions and utilities. See the Level subpackage documentation for more details.
• types — Common types and interfaces for logger internals. See the Types subpackage documentation for more details.

In add, the logger package the provides adapters for external loggers, enabling seamless integration and type conversion with the main logging infrastructure:

• GORM logger adapter: Bridges gorm.io/gorm/logger to centralize and standardize GORM logs. See the GORM subpackage documentation for more details.
• HashiCorp hclog adapter: Integrates github.com/hashicorp/go-hclog with the unified logger system. See the HashiCorp subpackage documentation for more details.

---

logger/config Subpackage Documentation

The logger/config subpackage provides configuration structures and utilities for customizing the behavior and outputs of the logger system. It enables fine-grained control over log destinations, formatting, filtering, and runtime options.

---

Features

• Centralized configuration for all logger outputs (stdout, files, syslog)
• Support for inheritance and merging of default options
• Validation helpers for configuration correctness
• Clone and merge utilities for dynamic configuration management

---

Main Types

Options

The main configuration struct for the logger.
Key fields:

• InheritDefault (bool): If true, inherits from a registered default options function.
• TraceFilter (string): Path filter for cleaning traces in log output.
• Stdout (*OptionsStd): Options for stdout/stderr logging.
• LogFileExtend (bool): If true, appends to default file outputs; otherwise, replaces them.
• LogFile (OptionsFiles): List of file output configurations.
• LogSyslogExtend (bool): If true, appends to default syslog outputs; otherwise, replaces them.
• LogSyslog (OptionsSyslogs): List of syslog output configurations.

Key methods:

• RegisterDefaultFunc(fct FuncOpt): Register a function to provide default options for inheritance.
• Validate(): Validate the configuration and return a custom error if invalid.
• Clone() Options: Deep copy of the options.
• Merge(opt *Options): Merge another options struct into the current one.
• Options() *Options: Return the effective options, applying inheritance if enabled.

---

OptionsStd

Configuration for standard output (stdout/stderr):

• DisableStandard (bool): Disable writing to stdout/stderr.
• DisableStack (bool): Disable goroutine ID in messages.
• DisableTimestamp (bool): Disable timestamps in messages.
• EnableTrace (bool): Enable caller/file/line tracing.
• DisableColor (bool): Disable color formatting.
• EnableAccessLog (bool): Enable access log for API routers.

Method:

• Clone() *OptionsStd: Deep copy of the struct.

---

OptionsFile and OptionsFiles

Configuration for file outputs:

• LogLevel ([]string): Allowed log levels for this file.
• Filepath (string): Path to the log file.
• Create (bool): Create the file if it does not exist.
• CreatePath (bool): Create the directory path if it does not exist.
• FileMode (Perm): File permissions.
• PathMode (Perm): Directory permissions.
• DisableStack, DisableTimestamp, EnableTrace, EnableAccessLog: Same as above.
• FileBufferSize (Size): Buffer size for file writes.

Methods:

• Clone() OptionsFile: Deep copy of the struct.
• Clone() OptionsFiles: Deep copy of the slice.

---

OptionsSyslog and OptionsSyslogs

Configuration for syslog outputs:

• LogLevel ([]string): Allowed log levels for this syslog.
• Network (string): Network type (e.g., tcp, udp).
• Host (string): Syslog server address.
• Facility (string): Syslog facility.
• Tag (string): Syslog tag or logger name.
• DisableStack, DisableTimestamp, EnableTrace, EnableAccessLog: Same as above.

Methods:

• Clone() OptionsSyslog: Deep copy of the struct.
• Clone() OptionsSyslogs: Deep copy of the slice.

---

Error Handling

Custom error codes are provided for configuration validation and parameter errors.
Use Validate() to check configuration correctness and handle errors accordingly.

---

Example Usage

import (
    "github.com/nabbar/golib/logger/config"
)

opts := &config.Options{
    InheritDefault: false,
    TraceFilter: "/src/",
    Stdout: &config.OptionsStd{
        EnableTrace: true,
    },
    LogFile: config.OptionsFiles{
        {
            LogLevel: []string{"Debug", "Info"},
            Filepath: "/var/log/myapp.log",
            Create: true,
            FileMode: 0644,
        },
    },
}

if err := opts.Validate(); err != nil {
    // handle configuration error
}

---

Notes

• All configuration structs support cloning and merging for dynamic and layered setups.
• Designed for use with the main logger package and its subpackages.
• Ensures thread-safe and consistent logger configuration across your application.

---

logger/entry Subpackage Documentation

The logger/entry subpackage provides the core types and methods for creating, managing, and logging structured log entries. It enables advanced logging scenarios with support for custom fields, error handling, data attachment, and integration with frameworks like Gin.

---

Features

• Creation and manipulation of structured log entries
• Support for custom fields and data
• Error collection and management within log entries
• Integration with Gin context for error propagation
• Flexible logging with level and context control
• Thread-safe design

---

Main Types

Entry Interface

Represents a single log entry with methods for configuration and logging:

• SetLogger(fct func() *logrus.Logger) Entry
  Set the logger instance provider for this entry.
• SetLevel(lvl Level) Entry
  Set the log level for the entry.
• SetMessageOnly(flag bool) Entry
  Log only the message, ignoring structured fields.
• SetEntryContext(etime, stack, caller, file, line, msg) Entry
  Set context information (timestamp, stack, caller, etc.).
• SetGinContext(ctx *gin.Context) Entry
  Attach a Gin context for error propagation.
• DataSet(data interface{}) Entry
  Attach arbitrary data to the entry.
• Check(lvlNoErr Level) bool
  Log the entry and return true if errors are present.
• Log()
  Log the entry using the configured logger.

Field Management

• FieldAdd(key string, val interface{}) Entry
  Add a custom field to the entry.
• FieldMerge(fields Fields) Entry
  Merge multiple fields into the entry.
• FieldSet(fields Fields) Entry
  Replace all custom fields.
• FieldClean(keys ...string) Entry
  Remove specific fields by key.

Error Management

• ErrorClean() Entry
  Remove all errors from the entry.
• ErrorSet(err []error) Entry
  Set the error slice for the entry.
• ErrorAdd(cleanNil bool, err ...error) Entry
  Add one or more errors, optionally skipping nil values.

---

Example Usage

import (
    "github.com/nabbar/golib/logger/entry"
    "github.com/nabbar/golib/logger/level"
)

e := entry.New(level.InfoLevel).
    FieldAdd("user", "alice").
    ErrorAdd(true, someError).
    DataSet(map[string]interface{}{"extra": 123})

e.Log()

---

Integration

• Gin: Use SetGinContext to propagate errors to the Gin context.
• Custom Fields: Use FieldAdd, FieldMerge, and FieldSet for structured logging.
• Error Handling: Use ErrorAdd, ErrorSet, and ErrorClean to manage error slices within entries.

---

Notes

• All entry methods are chainable for fluent usage.
• Logging is performed via Logrus and supports all configured logger outputs.
• Designed for use with the main logger package and compatible with other subpackages.

---

logger/fields Subpackage Documentation

The logger/fields subpackage provides a flexible and thread-safe way to manage structured key-value pairs (fields) for log entries. It is designed to integrate seamlessly with the logger system, supporting advanced field manipulation, cloning, and serialization.

---

Features

• Thread-safe storage and manipulation of log fields
• Integration with context for field inheritance and isolation
• JSON marshaling and unmarshaling for structured logging
• Conversion to Logrus fields for compatibility
• Functional mapping and dynamic field updates
• Cloning of field sets for context propagation

---

Main Types

Fields Interface

Represents a set of structured fields for log entries.

• Inherits from Config[string] (context-aware configuration)
• Implements json.Marshaler and json.Unmarshaler
• FieldsClone(ctx context.Context) Fields
  Clone the fields set, optionally with a new context.
• Add(key string, val interface{}) Fields
  Add or update a key-value pair in the fields.
• Logrus() logrus.Fields
  Convert the fields to a logrus.Fields map for Logrus integration.
• Map(fct func(key string, val interface{}) interface{}) Fields
  Apply a function to each field value and update it.

Construction

• New(ctx FuncContext) Fields
  Create a new Fields instance with a context provider.

---

Example Usage

import (
    "github.com/nabbar/golib/logger/fields"
    "context"
)

f := fields.New(func() context.Context { return context.Background() })
f = f.Add("user", "alice").Add("role", "admin")

logrusFields := f.Logrus() // Use with Logrus logger

// Clone fields for a new context
f2 := f.FieldsClone(context.TODO())

// Map example: uppercase all string values
f.Map(func(key string, val interface{}) interface{} {
    if s, ok := val.(string); ok {
        return strings.ToUpper(s)
    }
    return val
})

---

Integration

• Use Fields to attach structured data to log entries.
• Supports context-based field inheritance for request-scoped logging.
• Compatible with Logrus and JSON-based loggers.

---

Notes

• All operations are safe for concurrent use.
• Fields can be serialized/deserialized as JSON for structured logging.
• Designed for use with the main logger package and its subpackages.

---

logger/hookfile Subpackage Documentation

The logger/hookfile subpackage provides file output hooks for the logger system, enabling efficient, buffered, and concurrent logging to files. It is designed for integration with Logrus and supports advanced file management features.

---

Features

• Logrus-compatible file output hook
• Supports multiple log levels per file
• Buffered and batched writes for performance
• Automatic file and directory creation with configurable permissions
• Optional stack trace, timestamp, and trace information filtering
• Access log support for API routers
• Thread-safe and context-aware operation
• Graceful shutdown and buffer flushing

---

Main Types

HookFile Interface

Represents a file output hook for Logrus.

• Inherits from the logger Hook interface
• Done() <-chan struct{}: Returns a channel closed when the hook is stopped

Construction

• New(opt OptionsFile, format logrus.Formatter) (HookFile, error)
  Creates a new file hook with the given configuration and formatter.
  Returns an error if the file path is missing or cannot be created.

---

Configuration

The hook is configured using an OptionsFile struct, which includes:

• LogLevel: List of log levels to write to this file
• Filepath: Path to the log file
• Create: Whether to create the file if it does not exist
• CreatePath: Whether to create the directory path if it does not exist
• FileMode, PathMode: File and directory permissions
• DisableStack, DisableTimestamp, EnableTrace, EnableAccessLog: Output options
• FileBufferSize: Buffer size for batched writes

---

Usage Example

import (
    "github.com/nabbar/golib/logger/hookfile"
    "github.com/nabbar/golib/logger/config"
    "github.com/sirupsen/logrus"
    "context"
)

opt := config.OptionsFile{
    Filepath: "/var/log/myapp.log",
    Create: true,
    FileMode: 0644,
    LogLevel: []string{"Info", "Error"},
}

hook, err := hookfile.New(opt, &logrus.TextFormatter{})
if err != nil {
    // handle error
}

log := logrus.New()
hook.RegisterHook(log)

// Start the hook's background writer
ctx, cancel := context.WithCancel(context.Background())
go hook.(*hookfile.HookFileImpl).Run(ctx)

// ... use logrus as usual

// On shutdown
cancel()
<-hook.Done()

---

Buffering and Performance

• Writes are buffered and flushed periodically or when the buffer is full.
• On shutdown, all buffered logs are flushed to disk.
• Buffer size is configurable for performance tuning.

---

Error Handling

• Returns errors for missing file paths, closed streams, or file system issues.
• Errors are surfaced during hook creation or log writing.

---

Notes

• Designed for use with the main logger package and Logrus.
• All operations are safe for concurrent use.
• Supports dynamic log level filtering and flexible file management.
• Integrates with the logger configuration system for unified setup.

---

logger/hookstderr Subpackage Documentation

The logger/hookstderr subpackage provides a Logrus-compatible hook for logging to stderr, with support for color output, log level filtering, and advanced formatting options. It is designed for seamless integration with the main logger system and supports both standard and access log modes.

---

Features

• Logrus hook for writing logs to stderr
• Supports colorized output (with automatic detection)
• Configurable log levels per hook
• Optional stack trace, timestamp, and trace information filtering
• Access log mode for API routers
• Thread-safe and context-aware
• Compatible with custom formatters

---

Main Types

HookStdErr Interface

Represents a stderr output hook for Logrus.

• Inherits from the logger Hook interface

Construction

• New(opt *OptionsStd, lvls []logrus.Level, f logrus.Formatter) (HookStdErr, error)
  Creates a new stderr hook with the given configuration, log levels, and formatter.
  Returns nil if standard output is disabled.

---

Configuration

The hook is configured using an OptionsStd struct, which includes:

• DisableStandard: Disable writing to stderr
• DisableStack: Remove stack trace from log output
• DisableTimestamp: Remove timestamps from log output
• EnableTrace: Include caller, file, and line information
• DisableColor: Disable color formatting
• EnableAccessLog: Enable access log mode (plain message output)

---

Usage Example

import (
    "github.com/nabbar/golib/logger/hookstderr"
    "github.com/nabbar/golib/logger/config"
    "github.com/sirupsen/logrus"
)

opt := &config.OptionsStd{
    EnableTrace: true,
    DisableColor: false,
}

hook, err := hookstderr.New(opt, []logrus.Level{logrus.InfoLevel, logrus.ErrorLevel}, &logrus.TextFormatter{})
if err != nil {
    // handle error
}

log := logrus.New()
hook.RegisterHook(log)

// Use logrus as usual; logs will be sent to stderr via the hook
log.Info("This is an info message")

---

Output Behavior

• If color is enabled, output is colorized for better readability.
• In access log mode, only the message is output, with a newline.
• Stack trace, timestamp, and trace fields can be included or filtered based on configuration.
• The hook is safe for concurrent use.

---

Error Handling

• Returns an error if the writer is not set up.
• All write operations are checked for errors.

---

Notes

• Designed for use with the main logger package and Logrus.
• Integrates with the logger configuration system for unified setup.
• All operations are thread-safe and suitable for production environments.

---

logger/hookstdout Subpackage Documentation

The logger/hookstdout subpackage provides a Logrus-compatible hook for logging to stdout, supporting color output, log level filtering, and advanced formatting options. It is designed for seamless integration with the main logger system and supports both standard and access log modes.

---

Features

• Logrus hook for writing logs to stdout
• Supports colorized output (with automatic detection)
• Configurable log levels per hook
• Optional stack trace, timestamp, and trace information filtering
• Access log mode for API routers
• Thread-safe and context-aware
• Compatible with custom formatters

---

Main Types

HookStdOut Interface

Represents a stdout output hook for Logrus.

• Inherits from the logger Hook interface

Construction

• New(opt *OptionsStd, lvls []logrus.Level, f logrus.Formatter) (HookStdOut, error)
  Creates a new stdout hook with the given configuration, log levels, and formatter.
  Returns nil if standard output is disabled.

---

Configuration

The hook is configured using an OptionsStd struct, which includes:

• DisableStandard: Disable writing to stdout
• DisableStack: Remove stack trace from log output
• DisableTimestamp: Remove timestamps from log output
• EnableTrace: Include caller, file, and line information
• DisableColor: Disable color formatting
• EnableAccessLog: Enable access log mode (plain message output)

---

Usage Example

import (
    "github.com/nabbar/golib/logger/hookstdout"
    "github.com/nabbar/golib/logger/config"
    "github.com/sirupsen/logrus"
)

opt := &config.OptionsStd{
    EnableTrace: true,
    DisableColor: false,
}

hook, err := hookstdout.New(opt, []logrus.Level{logrus.InfoLevel, logrus.ErrorLevel}, &logrus.TextFormatter{})
if err != nil {
    // handle error
}

log := logrus.New()
hook.RegisterHook(log)

// Use logrus as usual; logs will be sent to stdout via the hook
log.Info("This is an info message")

---

Output Behavior

• If color is enabled, output is colorized for better readability.
• In access log mode, only the message is output, with a newline.
• Stack trace, timestamp, and trace fields can be included or filtered based on configuration.
• The hook is safe for concurrent use.

---

Error Handling

• Returns an error if the writer is not set up.
• All write operations are checked for errors.

---

Notes

• Designed for use with the main logger package and Logrus.
• Integrates with the logger configuration system for unified setup.
• All operations are thread-safe and suitable for production environments.

---

logger/hooksyslog Subpackage Documentation

The logger/hooksyslog subpackage provides a Logrus-compatible hook for sending logs to syslog servers, supporting both Unix and Windows platforms. It offers advanced configuration for syslog facilities, severities, network protocols, and formatting, making it suitable for production-grade logging in distributed systems.

---

Features

• Logrus hook for sending logs to syslog (local or remote)
• Supports all standard syslog facilities and severities
• Configurable network protocol (e.g., UDP, TCP, Unix socket)
• Customizable log levels per hook
• Optional stack trace, timestamp, and trace information filtering
• Access log mode for API routers
• Thread-safe and context-aware
• Graceful shutdown and error handling
• Compatible with custom formatters

---

Main Types

HookSyslog Interface

Represents a syslog output hook for Logrus.

• Inherits from the logger Hook interface
• Done() <-chan struct{}: Returns a channel closed when the hook is stopped
• WriteSev(s SyslogSeverity, p []byte) (n int, err error): Write a message with a specific syslog severity

Construction

• New(opt OptionsSyslog, format logrus.Formatter) (HookSyslog, error)
  Creates a new syslog hook with the given configuration and formatter.

---

Configuration

The hook is configured using an OptionsSyslog struct, which includes:

• LogLevel: List of log levels to send to syslog
• Network: Network protocol (e.g., tcp, udp, unix)
• Host: Syslog server address or socket path
• Facility: Syslog facility (e.g., LOCAL0, DAEMON)
• Tag: Syslog tag or logger name
• DisableStack: Remove stack trace from log output
• DisableTimestamp: Remove timestamps from log output
• EnableTrace: Include caller, file, and line information
• EnableAccessLog: Enable access log mode (plain message output)

---

Syslog Severity and Facility

• SyslogSeverity: Enum for syslog severities (EMERG, ALERT, CRIT, ERR, WARNING, NOTICE, INFO, DEBUG)
• SyslogFacility: Enum for syslog facilities (KERN, USER, MAIL, DAEMON, AUTH, SYSLOG, LPR, NEWS, UUCP, CRON, AUTHPRIV, FTP, LOCAL0-LOCAL7)
• Use MakeSeverity(string) and MakeFacility(string) to parse string values

---

Usage Example

import (
    "github.com/nabbar/golib/logger/hooksyslog"
    "github.com/nabbar/golib/logger/config"
    "github.com/sirupsen/logrus"
    "context"
)

opt := config.OptionsSyslog{
    Network:  "udp",
    Host:     "127.0.0.1:514",
    Facility: "LOCAL0",
    Tag:      "myapp",
    LogLevel: []string{"info", "error"},
}

hook, err := hooksyslog.New(opt, &logrus.TextFormatter{})
if err != nil {
    panic(err)
}

log := logrus.New()
hook.RegisterHook(log)

// Start the syslog hook background process
ctx, cancel := context.WithCancel(context.Background())
go hook.(*hooksyslog.HookSyslogImpl).Run(ctx)

// Use logrus as usual; logs will be sent to syslog
log.Info("This is an info message")

// On shutdown
cancel()
<-hook.Done()

---

Output Behavior

• Maps Logrus levels to syslog severities automatically
• In access log mode, only the message is sent, with a newline
• Stack trace, timestamp, and trace fields can be included or filtered based on configuration
• Handles connection setup and reconnection transparently

---

Error Handling

• Returns errors for connection issues, closed streams, or syslog server errors
• All write operations are checked for errors and reported

---

Notes

• Designed for use with the main logger package and Logrus
• Integrates with the logger configuration system for unified setup
• All operations are thread-safe and suitable for production environments
• Supports both Unix syslog and Windows event log (with platform-specific behavior)
• Graceful shutdown ensures all logs are flushed before exit

---

logger/level Subpackage Documentation

The logger/level subpackage defines log levels and provides utilities for parsing, converting, and integrating log levels with other logging systems such as Logrus.

---

Features

• Definition of standard log levels (Panic, Fatal, Error, Warn, Info, Debug, Nil)
• String and numeric conversion utilities
• Parsing from string to level
• Integration helpers for Logrus compatibility
• Listing of all available log levels

---

Main Types

Level Type

Represents the log level as a uint8 type.

Constants

• PanicLevel: Critical error, triggers a panic (trace + fatal)
• FatalLevel: Fatal error, triggers process exit
• ErrorLevel: Error, process should stop and return to caller
• WarnLevel: Warning, process continues but an issue occurred
• InfoLevel: Informational message, no impact on process
• DebugLevel: Debug message, useful for troubleshooting
• NilLevel: Disables logging for this entry

---

Functions & Methods

ListLevels() []string

Returns a list of all available log level names as lowercase strings.

Parse(l string) Level

Parses a string and returns the corresponding Level. If the string does not match a known level, returns InfoLevel.

Level.String() string

Returns the string representation of the log level (e.g., "Debug", "Info", "Warning", "Error", "Fatal", "Critical").

Level.Uint8() uint8

Returns the numeric value of the log level.

Level.Logrus() logrus.Level

Converts the custom Level to the corresponding Logrus log level.

---

Example Usage

import (
    "github.com/nabbar/golib/logger/level"
    "github.com/sirupsen/logrus"
)

lvl := level.Parse("debug")
if lvl == level.DebugLevel {
    // Enable debug logging
}

logrusLevel := lvl.Logrus()
logrus.SetLevel(logrusLevel)

for _, l := range level.ListLevels() {
    println(l)
}

---

Notes

• NilLevel disables logging and should not be used with SetLogLevel.
• String representations are case-insensitive when parsing.
• Designed for seamless integration with the main logger package and Logrus.

---

logger/types Subpackage Documentation

The logger/types subpackage provides common types, constants, and interfaces used throughout the logger system. It defines standard field names for structured logging and the base interface for logger hooks, ensuring consistency and extensibility across all logger outputs.

---

Features

• Standardized field names for structured log entries
• Base Hook interface for implementing custom logrus hooks
• Integration with context and I/O interfaces
• Ensures compatibility and extensibility for logger outputs

---

Main Types

Field Name Constants

Defines string constants for common log entry fields:

• FieldTime: Timestamp of the log entry
• FieldLevel: Log level (e.g., info, error)
• FieldStack: Stack trace information
• FieldCaller: Caller function or method
• FieldFile: Source file name
• FieldLine: Source line number
• FieldMessage: Log message
• FieldError: Error details
• FieldData: Additional structured data

Use these constants to ensure consistent field naming in structured logs.

---

Hook Interface

Represents the base interface for logger hooks, designed for integration with Logrus and custom outputs.

• Inherits from logrus.Hook for log event handling
• Inherits from io.WriteCloser for I/O compatibility
• RegisterHook(log *logrus.Logger): Register the hook with a Logrus logger
• Run(ctx context.Context): Start the hook's background process (if needed)

This interface allows the creation of custom hooks that can be registered with the logger and manage their own lifecycle.

---

Example Usage

import (
    "github.com/nabbar/golib/logger/types"
    "github.com/sirupsen/logrus"
    "context"
)

type MyCustomHook struct{}

func (h *MyCustomHook) Fire(entry *logrus.Entry) error { /* ... */ return nil }
func (h *MyCustomHook) Levels() []logrus.Level         { /* ... */ return nil }
func (h *MyCustomHook) Write(p []byte) (int, error)    { /* ... */ return 0, nil }
func (h *MyCustomHook) Close() error                   { /* ... */ return nil }
func (h *MyCustomHook) RegisterHook(log *logrus.Logger) { log.AddHook(h) }
func (h *MyCustomHook) Run(ctx context.Context)        { /* ... */ }

var hook types.Hook = &MyCustomHook{}
log := logrus.New()
hook.RegisterHook(log)
go hook.Run(context.Background())

---

Notes

• The field name constants should be used for all structured log entries to maintain consistency.
• The Hook interface is the foundation for all logger output hooks (stdout, stderr, file, syslog, etc.).
• Designed for use with the main logger package and its subpackages.
• All operations are thread-safe and suitable for concurrent environments.

---

logger/gorm Subpackage Documentation

The logger/gorm subpackage provides an adapter to integrate the main logger system with the GORM ORM logger interface. It enables centralized, structured, and configurable logging for all GORM database operations, supporting log level mapping, error handling, and slow query detection.

---

Features

• Implements the gorm.io/gorm/logger.Interface for seamless GORM integration
• Maps GORM log levels to the main logger's levels
• Structured logging with custom fields for SQL queries, rows, and elapsed time
• Configurable slow query threshold and error filtering
• Option to ignore "record not found" errors in logs
• Thread-safe and context-aware

---

Main Types

GORM Logger Adapter

• New(fct func() Logger, ignoreRecordNotFoundError bool, slowThreshold time.Duration) gormlogger.Interface
  Creates a new GORM logger adapter.
  • fct: Function returning the main logger instance
  • ignoreRecordNotFoundError: If true, skips logging "record not found" errors
  • slowThreshold: Duration above which queries are considered slow and logged as warnings

---

Log Level Mapping

• Silent: Disables logging (NilLevel)
• Info: Logs as InfoLevel
• Warn: Logs as WarnLevel
• Error: Logs as ErrorLevel

---

Logging Methods

• Info(ctx, msg, ...args): Logs informational messages
• Warn(ctx, msg, ...args): Logs warnings
• Error(ctx, msg, ...args): Logs errors
• Trace(ctx, begin, fc, err): Logs SQL queries with execution time, rows affected, and error details
  • If the query is slow (exceeds slowThreshold), logs as a warning
  • If an error occurs (and is not ignored), logs as an error
  • Otherwise, logs as info

---

Example Usage

import (
    "github.com/nabbar/golib/logger"
    "github.com/nabbar/golib/logger/gorm"
    "gorm.io/gorm"
    "time"
)

log := logger.New(/* context provider */)
gormLogger := gorm.New(
    func() logger.Logger { return log },
    true,                  // ignoreRecordNotFoundError
    200*time.Millisecond,  // slowThreshold
)

db, err := gorm.Open(/* ... */, &gorm.Config{
    Logger: gormLogger,
})

---

Output Behavior

• Each GORM operation is logged with structured fields:
  • elapsed ms: Query duration in milliseconds
  • rows: Number of rows affected (or "-" if unknown)
  • query: The executed SQL statement
• Errors and slow queries are highlighted according to configuration

---

Notes

• Designed for use with the main logger package for unified logging across your application
• Supports dynamic log level changes via the LogMode method
• All operations are safe for concurrent use and production environments

---

logger/hashicorp Subpackage Documentation

The logger/hashicorp subpackage provides an adapter to integrate the main logger system with the HashiCorp hclog logging interface. This enables unified, structured, and configurable logging for libraries and tools that use hclog, with full support for log level mapping, context fields, and logger options.

---

Features

• Implements the hclog.Logger interface for seamless HashiCorp integration
• Maps hclog log levels to the main logger's levels
• Supports structured logging with custom fields and logger names
• Dynamic log level control and trace support
• Thread-safe and context-aware
• Provides standard logger and writer for compatibility

---

Main Types

HashiCorp Logger Adapter

• New(logger FuncLog) hclog.Logger
  Creates a new hclog-compatible logger adapter.

  • logger: Function returning the main logger instance

• SetDefault(log FuncLog)
  Sets the default hclog logger globally to use the adapter.

---

Log Level Mapping

• NoLevel, Off: Disables logging (NilLevel)
• Trace, Debug: Logs as DebugLevel (with trace support for Trace)
• Info: Logs as InfoLevel
• Warn: Logs as WarnLevel
• Error: Logs as ErrorLevel

---

Logging Methods

• Log(level, msg, ...args): Generic log method for all levels
• Trace(msg, ...args), Debug(msg, ...args), Info(msg, ...args), Warn(msg, ...args), Error(msg, ...args): Level-specific logging
• IsTrace(), IsDebug(), IsInfo(), IsWarn(), IsError(): Check if a level is enabled
• With(args...): Returns a logger with additional context fields
• Name(), Named(name), ResetNamed(name): Manage logger names for context
• SetLevel(level), GetLevel(): Set or get the current log level
• ImpliedArgs(): Returns the current context fields
• StandardLogger(opts), StandardWriter(opts): Provides standard log.Logger and io.Writer for compatibility

---

Example Usage

import (
    "github.com/nabbar/golib/logger"
    "github.com/nabbar/golib/logger/hashicorp"
    "github.com/hashicorp/go-hclog"
    "context"
)

log := logger.New(func() context.Context { return context.Background() })
hclogger := hashicorp.New(func() logger.Logger { return log })

// Use hclogger as a drop-in replacement for hclog.Logger
hclogger.Info("Starting HashiCorp component", "component", "example")

// Set as the default hclog logger
hashicorp.SetDefault(func() logger.Logger { return log })

---

Output Behavior

• All hclog log messages are routed through the main logger, preserving structured fields and logger names.
• Log level and trace options are mapped according to the main logger configuration.
• Supports dynamic changes to log level and logger context.

---

Notes

• Designed for use with the main logger package for unified logging across your application and third-party libraries.
• All operations are safe for concurrent use and production environments.
• Supports full compatibility with the hclog API, including standard logger and writer methods.

---

Notes

• Designed for Go 1.18+.
• All operations are thread-safe.
• Integrates with standard Go logging and third-party libraries.
• Suitable for high-concurrency and production environments.

For more details, refer to the GoDoc or the source code in the logger package and its subpackages.