log

package module
v1.6.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 26, 2025 License: MIT Imports: 15 Imported by: 5

README

go-lib-log

A simple, high-performance, and configurable logging library for Go, built on zerolog.

This library aims to provide a consistent logging interface with advanced features like rate limiting, buffering, and structured logging, suitable for high-throughput applications.

Overview

go-lib-log is a high-performance logging library for Go that wraps zerolog with additional production-ready features. It provides a clean builder pattern API for creating customized loggers with advanced capabilities like event grouping, buffering, and rate limiting.

Features

Core Logging Features
  • Multiple Log Levels: Supports Trace, Debug, Info, Warn, Error, Fatal, and Panic levels
  • Structured Logging: Output in JSON or human-readable console format
  • Builder Pattern API: Modern, chainable configuration using NewLogger()
  • Environment Variable Configuration: Easy setup in different environments without code changes
  • Compatibility Layer: Maintains compatibility with go-logging.v1
Performance Features
  • High-Performance Buffering: Asynchronous processing with configurable buffer sizes
  • Rate Limiting: Prevents log flooding with configurable limits and burst handling
  • Zero-Allocation JSON: Leverages zerolog's efficient JSON marshaling
  • Reduced Lock Contention: Optimized internal locking for concurrent applications
Advanced Features
  • Event Grouping: Automatically groups identical log messages within configurable time windows to reduce noise and improve readability
  • Backpressure Handling: Automatic reporting of dropped log messages due to buffer overflow
  • Flexible Buffering Control: Choose between buffered (high performance) or unbuffered (immediate write) modes
  • Custom Output Destinations: Support for custom writers and output formats
Configuration Features
  • Programmatic Configuration: Full control via builder pattern methods
  • Environment Variable Support: Configure all features via environment variables
  • Runtime Flexibility: Mix and match features as needed (grouping, buffering, rate limiting)

Performance

go-lib-log is designed for high performance, leveraging zerolog's efficient JSON marshaling and introducing its own optimizations for buffering and rate limiting.

In benchmarks, go-lib-log with its BufferedRateLimitedWriter (which includes features like asynchronous processing, rate limiting, and drop reporting) demonstrates significantly better performance compared to the standard library's log package, especially in high-throughput scenarios.

Here's a comparative overview of approximate performance for a simple logging operation (logging a short string and an integer):

Feature / Logger go-lib-log (Buffered) Standard Library log zerolog (Direct)
Approx. ns/op ~33 ns/op ~350+ ns/op ~30 ns/op
Event Grouping Overhead ~2-7% (when enabled) N/A N/A
Asynchronous Processing Yes (Buffered) No (Synchronous) No (Synchronous)
Structured Logging (JSON) Yes (via zerolog) Manual / Verbose Yes (Core)
Rate Limiting Yes No No
Buffering Yes No No
Dropped Message Reporting Yes No No
Zero-Allocation JSON (underlying) Yes (via zerolog) No Yes (Core)

Notes:

  • Performance numbers can vary based on the specific benchmark, hardware, and logging configuration (e.g., output destination, log format).
  • Event grouping adds minimal overhead (~2-7%) but provides significant benefits in reducing log noise and storage costs.
  • The Standard Library log figures are for attempts to achieve similar structured-like output; basic log.Println would be faster but unstructured.
  • zerolog (Direct) serves as a baseline for the underlying logging engine without the additional features of go-lib-log's writer.

The key takeaway is that go-lib-log aims to provide advanced logging features (like buffering and rate limiting) with a minimal performance overhead compared to raw zerolog, and a substantial improvement over less optimized or more feature-heavy logging solutions, including the standard library logger when structured output and asynchronous behavior are desired.

The performance benefits are primarily due to:

  • Asynchronous Processing: Log messages are written to an in-memory buffer and processed by a separate goroutine, minimizing blocking in the application's hot paths.
  • Efficient Serialization: zerolog's focus on zero-allocation JSON marshaling.
  • Reduced Lock Contention: Recent optimizations have further reduced internal lock contention, particularly in the BufferedRateLimitedWriter.

When comparing, ensure that the standard library logger is configured to produce a similar output format (e.g., JSON-like or structured text) and consider its synchronous nature by default, which can be a bottleneck in concurrent applications.

Installation

go get github.com/thedataflows/go-lib-log

Usage

Basic Logging
package main

import (
 "errors"
 "os"

 "github.com/thedataflows/go-lib-log/log" // Adjust import path
)

func main() {
 // Create a logger using the builder pattern
 logger := log.NewLogger().Build()
 // Ensure to close it on application shutdown to flush buffers
 defer logger.Close()

 logger.Info().Msg("Application started")
 logger.Debug().Msg("This is a debug message.")
 logger.Warn().Str("issue", "potential issue").Msg("Something to be aware of")
 err := errors.New("something went wrong")
 logger.Error().Err(err).Msg("An error occurred")

 // Example of creating logger with custom configuration
 customLogger := log.NewLogger().
  WithBufferSize(1000).
  WithRateLimit(500).
  AsJSON().
  Build()
 defer customLogger.Close()

 // Demonstrate event grouping with repeated messages
 for range 5 {
  logger.Error().Err(errors.New("connection failed")).Msg("Database connection error")
  // These identical messages will be grouped automatically
 }

 // To see Fatal or Panic in action (uncomment to test):
 // logger.Fatal().Err(err).Msg("A fatal error occurred, exiting.")
 // logger.Panic().Err(err).Msg("A panic occurred.")
}
Configuration

The logger can be configured using the following environment variables:

  • LOG_LEVEL: Sets the minimum log level.
    • Supported values: trace, debug, info, warn, error, fatal, panic.
    • Default: info.
  • LOG_FORMAT: Sets the log output format.
    • Supported values: console, json.
    • Default: console.
  • LOG_BUFFER_SIZE: Sets the size of the internal log message buffer.
    • Default: 100000.
  • LOG_RATE_LIMIT: Sets the maximum number of log messages per second.
    • Default: 50000.
  • LOG_RATE_BURST: Sets the burst size for the rate limiter.
    • Default: 10000.
  • LOG_DISABLE_BUFFERING: Disables buffering and writes log messages directly to output.
    • Supported values: true, 1, yes (to disable buffering).
    • Default: false (buffering enabled).
    • When disabled, messages are written immediately with rate limiting only.
  • LOG_GROUP_WINDOW: Sets the time window (in seconds) for grouping similar log events.
    • Default: 1 (1 second, >= 0 enables event grouping with 0 using default value).
    • Set to -1 to disable event grouping.
  • ENV_LOG_DROP_REPORT_INTERVAL: Sets the interval (in seconds) for reporting dropped log messages.
    • Default: 10.

Event Grouping

Event grouping is a powerful feature that reduces log noise by grouping identical messages within a configurable time window. This feature is enabled by default with a 1-second grouping window. When multiple identical log messages are received within the window, only the first one is logged immediately, and subsequent identical messages increment a counter. When the window expires, a final grouped message is emitted showing the total count.

How It Works
  1. Message Hashing: Each log message is hashed based on its content and level
  2. Time Windows: Messages are grouped within configurable time windows (default: 1 second)
  3. Atomic Operations: Uses lock-free atomic operations for high performance
  4. Zero Allocation: Maintains zero-copy performance where possible
Grouped Message Format

When messages are grouped, the final log entry includes additional fields:

{
  "time": "2025-06-13T10:30:00Z",
  "level": "error",
  "message": "Database connection failed",
  "group_count": 15,
  "group_window": "1s",
  "group_first": "2025-06-13T10:29:59Z"
}
Using Event Grouping
// Default logger with event grouping enabled (1 second window)
logger := log.NewLogger().Build()
defer logger.Close()

// These messages will be grouped if sent within 1 second
logger.Error().Msg("Database connection failed")
logger.Error().Msg("Database connection failed") // Will be grouped
logger.Error().Msg("Database connection failed") // Will be grouped

// Create logger with custom grouping window
logger := log.NewLogger().WithGroupWindow(2 * time.Second).Build()
defer logger.Close()

// Create logger with grouping explicitly disabled
logger := log.NewLogger().WithoutGrouping().Build()
defer logger.Close()

// Different messages won't be grouped
logger.Error().Msg("Redis connection failed") // Separate message

// Environment variable configuration
os.Setenv("LOG_GROUP_WINDOW", "2") // 2 second window
logger := log.NewLogger().Build() // Will use environment configuration

// Disable grouping via environment variable
os.Setenv("LOG_GROUP_WINDOW", "-1") // Disables grouping
logger := log.NewLogger().Build()

Buffering Control

The library supports both buffered and unbuffered logging modes to suit different performance and reliability requirements:

Buffered Mode (Default)

In buffered mode, log messages are queued in an internal buffer and processed asynchronously by a background goroutine. This provides:

  • High Performance: Minimal impact on application performance
  • High Throughput: Can handle burst logging scenarios efficiently
  • Backpressure Handling: Messages are dropped if buffer is full, with periodic drop reports
// Default buffered logger
logger := log.NewLogger().Build()
defer logger.Close() // Important: ensures all buffered messages are flushed

logger.Info().Msg("This message goes to the buffer first")
Unbuffered Mode

In unbuffered mode, log messages are written directly to the output with rate limiting only. This provides:

  • Immediate Writing: Messages appear in logs immediately
  • No Message Loss: No buffering means no risk of losing messages due to buffer overflow
  • Lower Throughput: Direct I/O can impact application performance under high load
Enable via Environment Variable
export LOG_DISABLE_BUFFERING=true
# or
export LOG_DISABLE_BUFFERING=1
# or
export LOG_DISABLE_BUFFERING=yes

// Will use unbuffered mode due to environment variable
logger := log.NewLogger().Build()
logger.Info().Msg("This message is written immediately")
Enable Programmatically
// Explicitly create unbuffered logger
logger := log.NewLogger().WithoutBuffering().Build()
logger.Info().Msg("This message is written immediately")

// Unbuffered with event grouping disabled
logger := log.NewLogger().WithoutBuffering().WithoutGrouping().Build()
logger.Info().Msg("Immediate write, no grouping")
When to Use Each Mode

Use Buffered Mode (Default) When:

  • High logging throughput is required
  • Application performance is critical
  • Some message loss is acceptable under extreme load
  • Logging is primarily for debugging/monitoring

Use Unbuffered Mode When:

  • Every log message is critical (e.g., audit logs, financial transactions)
  • Immediate log visibility is required
  • Debugging scenarios where timing is important
  • Lower logging volume applications
Programmatic Configuration

You can also configure the logger programmatically:

package main

import (
 "github.com/thedataflows/go-lib-log/log" // Adjust import path
 "github.com/rs/zerolog"
 "os"
 "time"
)

func main() {
 // Create logger with programmatic configuration
 logger := log.NewLogger().
  WithLogLevelString("debug").
  AsJSON().
  WithBufferSize(10000).
  WithRateLimit(1000).
  Build()
 defer logger.Close()

 logger.Info().Msg("Logger configured programmatically.")

 // For more advanced custom logger setup with custom output:
 customOutput := zerolog.ConsoleWriter{Out: os.Stdout, TimeFormat: time.RFC3339}
 customLogger := log.NewLogger().
  WithOutput(customOutput).
  WithLogLevel(zerolog.InfoLevel).
  Build()
 defer customLogger.Close()

 customLogger.Info().Msg("This is from a custom logger instance")
}
Logger Configuration with Builder Pattern

The library uses a builder pattern for creating loggers with flexible configuration:

// Default logger with event grouping enabled (1 second window)
logger := log.NewLogger().Build()

// Logger with custom event grouping window
logger := log.NewLogger().WithGroupWindow(5 * time.Second).Build()

// Logger with event grouping explicitly disabled
logger := log.NewLogger().WithoutGrouping().Build()

// JSON-only logger (always outputs JSON format)
logger := log.NewLogger().AsJSON().Build()

// High-performance buffered logger with custom configuration
logger := log.NewLogger().
    WithBufferSize(50000).
    WithRateLimit(10000).
    WithGroupWindow(2 * time.Second).
    Build()

// Unbuffered logger for critical logging
logger := log.NewLogger().
    WithoutBuffering().
    WithoutGrouping().
    Build()

Important: Close() Method

Always call Close() on your logger instances to ensure proper cleanup and message flushing:

logger := log.NewLogger().Build()
defer logger.Close() // Critical for proper cleanup

The Close() method performs several important operations:

  1. Flushes Pending Grouped Messages: Any messages waiting in the event grouper are immediately flushed
  2. Processes Buffered Messages: All messages in the internal buffer are processed through rate limiting
  3. Stops Background Goroutines: Cleanly shuts down the processor and drop reporter goroutines
  4. Prevents Message Loss: Ensures no messages are lost during application shutdown
Close() Behavior
  • Thread-Safe: Can be called multiple times safely (subsequent calls are no-ops)
  • Blocking: Will wait for all pending messages to be processed
  • Rate-Limited: Pending grouped messages go through normal rate limiting during flush
  • Atomic: Uses atomic operations to prevent race conditions during shutdown
Example with Proper Cleanup
func main() {
    logger := log.NewLogger().Build()
    defer logger.Close() // Ensures all messages are flushed

    // Send many identical messages - these will be grouped
    for range 100 {
        logger.Error().Msg("Database connection failed")
    }

    // Close() will flush the grouped message before exiting
    // Without Close(), the grouped message might be lost
}

Note: The global logger used by package-level functions (log.Info(), log.Error(), etc.) should also be closed with log.Close() for proper cleanup.

Using the Global Logger vs Instance Logger

You can use the library in two ways:

// Option 1: Global logger (backwards compatible)
import log "github.com/thedataflows/go-lib-log"

func main() {
    defer log.Close() // Close global logger
    log.Info("pkg", "Using global logger")
}

// Option 2: Instance logger (recommended for new code)
import log "github.com/thedataflows/go-lib-log"

func main() {
    logger := log.NewLogger().Build()
    defer logger.Close()
    logger.Info().Msg("Using instance logger")
}

Migration from Previous Versions

For existing users: The library now uses a modern builder pattern API. If you prefer the previous behavior without event grouping, you can:

  1. Use log.NewLogger().WithoutGrouping().Build() instead of log.NewLogger().Build()
  2. Set the environment variable LOG_GROUP_WINDOW=-1 to disable grouping
  3. Use log.NewLogger().WithGroupWindow(-1).Build() to explicitly disable grouping

The new API provides more flexibility and cleaner configuration options.

License

MIT License

Documentation

Overview

Package log provides a high-performance logging library with advanced features including rate limiting, buffering, event grouping, and configurable output formats.

Buffering Control

The library supports both buffered and unbuffered logging modes:

Buffered Mode (default):

  • Messages are queued in a buffer and processed asynchronously
  • High throughput with minimal impact on application performance
  • Messages may be dropped if buffer is full (backpressure handling)
  • Suitable for high-frequency logging scenarios

Unbuffered Mode:

  • Messages are written directly to the output with rate limiting
  • Immediate writing ensures no message loss due to buffering
  • Lower throughput but guaranteed message delivery
  • Suitable for critical logging where message loss is unacceptable

Environment Variables

The following environment variables control logging behavior:

  • LOG_DISABLE_BUFFERING: Set to "true", "1", or "yes" to disable buffering
  • LOG_BUFFER_SIZE: Buffer size for buffered mode (default: 100000)
  • LOG_RATE_LIMIT: Rate limit in messages per second (default: 50000)
  • LOG_RATE_BURST: Burst size for rate limiting (default: 10000)
  • LOG_GROUP_WINDOW: Event grouping window in seconds (default: 1)
  • LOG_DROP_REPORT_INTERVAL: Drop report interval in seconds (default: 10)
  • LOG_LEVEL: Log level (debug, info, warn, error, fatal, panic)
  • LOG_FORMAT: Output format (json, console)

Usage Examples

Basic usage with default configuration: 

logger := log.NewLogger().Build()
logger.Info().Msg("This is a buffered log message")
logger.Close() // Flush remaining messages

Configure with builder pattern: 

logger := log.NewLogger().
	WithoutBuffering().
	WithGroupWindow(5 * time.Second).
	AsJSON().
	Build()
logger.Info().Msg("This message is written immediately with 5s grouping")

Disable buffering via environment variable: 

os.Setenv("LOG_DISABLE_BUFFERING", "true")
logger := log.NewLogger().Build()
logger.Info().Msg("This message is written immediately")

Create unbuffered logger with builder: 

logger := log.NewLogger().WithoutBuffering().Build()
logger.Info().Msg("This message is written immediately")

Unbuffered with grouping disabled: 

logger := log.NewLogger().WithoutBuffering().WithoutGrouping().Build()
logger.Info().Msg("No buffering, no grouping")

Package log provides global logger functionality and state management. This file contains all global logger objects and functions that were moved from log.go to improve code organization and maintainability.

Index

Constants

View Source 
const (
	// ENV_LOG_LEVEL is the environment variable for the log level.
	ENV_LOG_LEVEL = "LOG_LEVEL"
	// ENV_LOG_FORMAT is the environment variable for the log format.
	ENV_LOG_FORMAT = "LOG_FORMAT"
	// ENV_LOG_BUFFER_SIZE is the environment variable for the log buffer size.
	ENV_LOG_BUFFER_SIZE = "LOG_BUFFER_SIZE"
	// ENV_LOG_RATE_LIMIT is the environment variable for the log rate limit.
	ENV_LOG_RATE_LIMIT = "LOG_RATE_LIMIT" // messages per second
	// ENV_LOG_RATE_BURST is the environment variable for the log rate burst size.
	ENV_LOG_RATE_BURST = "LOG_RATE_BURST" // burst size
	// ENV_LOG_DROP_REPORT_INTERVAL is the environment variable for the log drop report interval.
	ENV_LOG_DROP_REPORT_INTERVAL = "LOG_DROP_REPORT_INTERVAL" // seconds between drop reports
	// ENV_LOG_GROUP_WINDOW is the environment variable for the log event grouping window.
	ENV_LOG_GROUP_WINDOW = "LOG_GROUP_WINDOW" // seconds for event grouping window
	// ENV_LOG_DISABLE_BUFFERING is the environment variable to disable buffering.
	ENV_LOG_DISABLE_BUFFERING = "LOG_DISABLE_BUFFERING" // set to "true" to disable buffering
	// DEFAULT_BUFFER_SIZE is the default buffer size for the logger.
	DEFAULT_BUFFER_SIZE = 100000 // High throughput: 100K buffer
	// DEFAULT_RATE_LIMIT is the default rate limit for the logger in messages per second.
	DEFAULT_RATE_LIMIT = 50000 // High throughput: 50K msgs/sec
	// DEFAULT_RATE_BURST is the default rate burst for the logger.
	DEFAULT_RATE_BURST = 10000 // High throughput: 10K burst
	// DEFAULT_DROP_REPORT_INTERVAL is the default interval in seconds for reporting dropped messages.
	DEFAULT_DROP_REPORT_INTERVAL = 10 // Report drops every 10 seconds
	// DEFAULT_GROUP_WINDOW is the default window in seconds for grouping similar events.
	DEFAULT_GROUP_WINDOW = 1 // Group events over 1 second window
	// KEY_PKG is the key used for the package name in log fields.
	KEY_PKG = "pkg"
)

Variables

View Source 
var (
	// ParseLevel parses a string into a zerolog.Level. It's a convenience wrapper around zerolog.ParseLevel.
	ParseLevel = zerolog.ParseLevel

	// DebugLevel defines the debug log level.
	DebugLevel = zerolog.DebugLevel
	// InfoLevel defines the info log level.
	InfoLevel = zerolog.InfoLevel
	// WarnLevel defines the warn log level.
	WarnLevel = zerolog.WarnLevel
	// ErrorLevel defines the error log level.
	ErrorLevel = zerolog.ErrorLevel
	// FatalLevel defines the fatal log level.
	FatalLevel = zerolog.FatalLevel
	// PanicLevel defines the panic log level.
	PanicLevel = zerolog.PanicLevel
	// NoLevel defines an absent log level.
	NoLevel = zerolog.NoLevel
	// Disabled disables the logger.
	Disabled = zerolog.Disabled
	// TraceLevel defines the trace log level.
	TraceLevel = zerolog.TraceLevel
)
View Source 
var AllLogFormats = [_logFormatCount]LogFormat{
	LOG_FORMAT_CONSOLE,
	LOG_FORMAT_JSON,
}

AllLogFormats is a list of all supported LogFormat values.

Functions

func AllLogFormatsStrings added in v1.2.0 

func AllLogFormatsStrings() []string

AllLogFormatsStrings returns a slice of strings representing all supported log formats.

func Close added in v1.2.0 

func Close()

Close closes the global Logger instance, ensuring cleanup of its resources. This should be called when the application is shutting down to flush any buffered logs.

func Debug 

func Debug(packageName string, msg any)

Debug logs a message at DebugLevel with the given package name.

func Debugf 

func Debugf(packageName string, format string, msg ...any)

Debugf logs a formatted message at DebugLevel with the given package name.

func Error 

func Error(packageName string, err error, msg any)

Error logs a message at ErrorLevel with the given package name and error.

func Errorf 

func Errorf(packageName string, err error, format string, msg ...any)

Errorf logs a formatted message at ErrorLevel with the given package name and error.

func EventHash added in v1.3.0 

func EventHash(event []byte) string

EventHash is a helper function that computes the hash of an event and returns it as a string. This can be used for logging or debugging purposes to identify events.

func Fatal 

func Fatal(packageName string, err error, msg any)

Fatal logs a message at FatalLevel with the given package name and error, then exits.

func Fatalf 

func Fatalf(packageName string, err error, format string, msg ...any)

Fatalf logs a formatted message at FatalLevel with the given package name and error, then exits.

func Flush added in v1.6.0 

func Flush()

Flush ensures all buffered messages in the global Logger are written to the output. This is useful when you want to force immediate output without closing the logger.

func GroupEvents added in v1.3.0 

func GroupEvents(events [][]byte) map[uint64][][]byte

GroupEvents groups the given events by their hash value computed from the event data. It returns a map where the key is the hash value and the value is a slice of events (byte slices) that correspond to the same hash.

func Hash added in v1.3.0 

func Hash(data []byte) uint64

Hash computes the hash of the given byte slice using the FNV-1a algorithm. It returns the hash value as an uint64.

func Info 

func Info(packageName string, msg any)

Info logs a message at InfoLevel with the given package name.

func Infof 

func Infof(packageName string, format string, msg ...any)

Infof logs a formatted message at InfoLevel with the given package name.

func IsValidLogFormat added in v1.2.0 

func IsValidLogFormat(s string) bool

IsValidLogFormat checks if a given string is a valid log format.

func Panic 

func Panic(packageName string, err error, msg any)

Panic logs a message at PanicLevel with the given package name and error, then panics.

func Panicf 

func Panicf(packageName string, err error, format string, msg ...any)

Panicf logs a formatted message at PanicLevel with the given package name and error, then panics.

func PreferredWriter 

func PreferredWriter() io.Writer

PreferredWriter returns an io.Writer that writes to both a new bytes.Buffer and os.Stderr. This is typically used for console logging to capture output for testing or other purposes while still printing to the standard error stream.

func PrettyYaml 

func PrettyYaml(data any) ([]byte, error)

PrettyYaml marshals the given data into a YAML string with an indent of 2 spaces. It uses github.com/goccy/go-yaml for marshaling.

func PrettyYamlString 

func PrettyYamlString(data any) string

PrettyYamlString is a convenience wrapper around PrettyYaml that returns the YAML as a string. If an error occurs during marshaling, it returns an empty string.

func Print 

func Print(packageName string, msg any)

Print logs a message at NoLevel (effectively always printing) with the given package name. It explicitly sets a "level" field to "-" in the output.

func Printf 

func Printf(packageName string, format string, msg ...any)

Printf logs a formatted message at NoLevel (effectively always printing) with the given package name. It explicitly sets a "level" field to "-" in the output.

func SetGlobalLogger added in v1.6.0 

func SetGlobalLogger(logger *CustomLogger)

SetGlobalLogger replaces the global Logger with a new one. This allows users to configure the global logger with custom settings while ensuring that subsequent calls to SetGlobalLoggerLogFormat preserve those settings.

func SetGlobalLoggerBuilder added in v1.6.0 

func SetGlobalLoggerBuilder(builder *LoggerBuilder)

SetGlobalLoggerBuilder replaces the global Logger with a new one built from the provided builder. This allows users to configure the global logger with custom settings while ensuring that subsequent calls to SetGlobalLoggerLogFormat preserve those settings.

func SetGlobalLoggerLogFormat added in v1.6.0 

func SetGlobalLoggerLogFormat(logFormat string) error

SetGlobalLoggerLogFormat sets the log format for the global Logger. It parses the provided logFormat string and updates the Logger's underlying writer to either a console writer or a JSON writer. This preserves all other configuration settings of the global logger. Returns an error if the logFormat string is invalid.

func SetGlobalLoggerLogLevel added in v1.6.0 

func SetGlobalLoggerLogLevel(level string) error

SetGlobalLoggerLogLevel sets the global log level for the default Logger. If the provided level string is empty, it defaults to InfoLevel. It returns an error if the level string is invalid. This preserves all other configuration settings of the global logger.

func Trace 

func Trace(packageName string, msg any)

Trace logs a message at TraceLevel with the given package name.

func Tracef 

func Tracef(packageName string, format string, msg ...any)

Tracef logs a formatted message at TraceLevel with the given package name.

func Warn 

func Warn(packageName string, msg any)

Warn logs a message at WarnLevel with the given package name.

func Warnf 

func Warnf(packageName string, format string, msg ...any)

Warnf logs a formatted message at WarnLevel with the given package name.

Types

type BufferedRateLimitedWriter added in v1.2.0 

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

BufferedRateLimitedWriter wraps an io.Writer with rate limiting and buffering. It ensures that logs are written at a controlled pace and buffers messages to handle bursts, dropping messages if the buffer is full and reporting drops. It also supports event grouping to reduce duplicate log noise.

func (*BufferedRateLimitedWriter) Close added in v1.2.0 

func (w *BufferedRateLimitedWriter) Close() error

Close closes the BufferedRateLimitedWriter, ensuring all buffered messages are processed and the drop reporter is stopped.

func (*BufferedRateLimitedWriter) Flush added in v1.6.0 

func (w *BufferedRateLimitedWriter) Flush()

Flush ensures all buffered messages are written to the target. This is useful when you want to force immediate output without closing the writer.

func (*BufferedRateLimitedWriter) Write added in v1.2.0 

func (w *BufferedRateLimitedWriter) Write(p []byte) (int, error)

Write writes the provided byte slice to the buffer. It implements io.Writer. If the buffer is full, messages are dropped, and the drop count is incremented. It starts the processor and drop reporter on the first write. If buffering is disabled, writes directly to the target with rate limiting.

type CustomLogger 

type CustomLogger struct {
	zerolog.Logger
	// contains filtered or unexported fields
}

CustomLogger wraps zerolog.Logger to provide additional functionalities like rate limiting, buffering, and custom formatting.

func Logger 

func Logger() *CustomLogger

Logger returns the global Logger instance.

func (*CustomLogger) Close added in v1.2.0 

func (l *CustomLogger) Close()

Close closes the CustomLogger and its underlying BufferedRateLimitedWriter.

func (*CustomLogger) Flush added in v1.6.0 

func (l *CustomLogger) Flush()

Flush ensures all buffered messages are written to the output. This is useful when you want to force immediate output without closing the logger.

func (*CustomLogger) SetZerologLogger added in v1.6.0 

func (l *CustomLogger) SetZerologLogger(logger zerolog.Logger)

SetZerologLogger replaces the underlying zerolog.Logger instance in the CustomLogger.

type GoLoggingV1Backend added in v1.1.0 

type GoLoggingV1Backend struct{}

go-logging compatibility GoLoggingV1Backend implements the logging.Backend interface to bridge go-logging.v1 with this log package.

func (*GoLoggingV1Backend) Log added in v1.1.0 

func (b *GoLoggingV1Backend) Log(level go_logging_v1.Level, calldepth int, rec *go_logging_v1.Record) error

Log implements the logging.Backend interface for go-logging.v1. It maps go-logging levels to the corresponding log functions in this package.

type LogFormat 

type LogFormat int

LogFormat defines the available log output formats. 

const (
	// LOG_FORMAT_CONSOLE represents a human-readable console log format.
	LOG_FORMAT_CONSOLE LogFormat = iota
	// LOG_FORMAT_JSON represents a machine-readable JSON log format.
	LOG_FORMAT_JSON
)

func ParseLogFormat 

func ParseLogFormat(s string) (LogFormat, error)

ParseLogFormat converts a string representation of a log format into a LogFormat type. It returns LOG_FORMAT_CONSOLE if the string is empty or "console", LOG_FORMAT_JSON if the string is "json". It returns an error for any other invalid input.

func (LogFormat) String 

func (f LogFormat) String() string

String implements fmt.Stringer interface

type LoggerBuilder added in v1.6.0 

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

LoggerBuilder provides a fluent interface for configuring and building CustomLogger instances.

func GlobalLoggerBuilder added in v1.6.0 

func GlobalLoggerBuilder() *LoggerBuilder

GlobalLoggerBuilder returns the global logger builder instance. This allows users to access the current configuration and modify it if needed.

func NewLogger 

func NewLogger() *LoggerBuilder

NewLogger creates a new LoggerBuilder with default configuration. This is the only constructor function - all other configurations are done through the builder pattern.

func (*LoggerBuilder) AsJSON added in v1.6.0 

func (lb *LoggerBuilder) AsJSON() *LoggerBuilder

AsJSON forces JSON output format regardless of environment settings.

func (*LoggerBuilder) Build added in v1.6.0 

func (lb *LoggerBuilder) Build() *CustomLogger

Build creates and returns the configured CustomLogger instance.

func (*LoggerBuilder) WithBufferSize added in v1.6.0 

func (lb *LoggerBuilder) WithBufferSize(size int) *LoggerBuilder

WithBufferSize sets the buffer size for the logger.

func (*LoggerBuilder) WithDropReportInterval added in v1.6.2 

func (lb *LoggerBuilder) WithDropReportInterval(interval time.Duration) *LoggerBuilder

WithDropReportInterval sets the interval for reporting dropped messages. Use 0 for default from environment, negative values to disable drop reporting.

func (*LoggerBuilder) WithGroupWindow added in v1.6.0 

func (lb *LoggerBuilder) WithGroupWindow(window time.Duration) *LoggerBuilder

WithGroupWindow sets the event grouping window duration. Use 0 for default from environment, negative values to disable grouping.

func (*LoggerBuilder) WithLogLevel added in v1.6.0 

func (lb *LoggerBuilder) WithLogLevel(level zerolog.Level) *LoggerBuilder

WithLogLevel sets the log level.

func (*LoggerBuilder) WithLogLevelString added in v1.6.0 

func (lb *LoggerBuilder) WithLogLevelString(level string) *LoggerBuilder

WithLogLevelString sets the log level from a string.

func (*LoggerBuilder) WithOutput added in v1.6.0 

func (lb *LoggerBuilder) WithOutput(output io.Writer) *LoggerBuilder

WithOutput sets the output writer for the logger.

func (*LoggerBuilder) WithRateBurst added in v1.6.0 

func (lb *LoggerBuilder) WithRateBurst(burst int) *LoggerBuilder

WithRateBurst sets the rate burst size for the logger.

func (*LoggerBuilder) WithRateLimit added in v1.6.0 

func (lb *LoggerBuilder) WithRateLimit(limit int) *LoggerBuilder

WithRateLimit sets the rate limit (messages per second) for the logger.

func (*LoggerBuilder) WithoutBuffering added in v1.6.0 

func (lb *LoggerBuilder) WithoutBuffering() *LoggerBuilder

WithoutBuffering disables buffering for the logger.

func (*LoggerBuilder) WithoutGrouping added in v1.6.0 

func (lb *LoggerBuilder) WithoutGrouping() *LoggerBuilder

WithoutGrouping disables event grouping for the logger.

Source Files

View all Source files

Directories

Path Synopsis
cmd
close
demo
unbuffered-test

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.