feat: add optional logger wherever possible

This commit introduces an optional logger parameter to various structs.
This enhancement allows users to provide custom logging implementations.

Author: ccoVeille

internal/log.go

@@ -77,3 +77,66 @@ func (l LogLevelT) InfoOrAbove() bool {
 func (l LogLevelT) DebugOrAbove() bool {
 	return l >= LogLevelDebug
 }
+
+// LoggerWithLevel is a logger interface with leveled logging methods.
+//
+// This interface can be implemented by custom loggers to provide leveled logging.
+type LoggerWithLevel interface {
+	// Infof logs an info level message
+	Infof(ctx context.Context, format string, v ...interface{})
+
+	// Warnf logs a warning level message
+	Warnf(ctx context.Context, format string, v ...interface{})
+
+	// Debugf logs a debug level message
+	Debugf(ctx context.Context, format string, v ...interface{})
+
+	// Errorf logs an error level message
+	Errorf(ctx context.Context, format string, v ...interface{})
+
+	// Enabled reports whether the given log level is enabled in the logger
+	Enabled(ctx context.Context, level LogLevelT) bool
+}
+
+// legacyLoggerAdapter is a logger that implements LoggerWithLevel interface
+// using the global [Logger] and [LogLevel] variables.
+type legacyLoggerAdapter struct{}
+
+func (l *legacyLoggerAdapter) Infof(ctx context.Context, format string, v ...interface{}) {
+	if LogLevel.InfoOrAbove() {
+		Logger.Printf(ctx, format, v...)
+	}
+}
+
+func (l *legacyLoggerAdapter) Warnf(ctx context.Context, format string, v ...interface{}) {
+	if LogLevel.WarnOrAbove() {
+		Logger.Printf(ctx, format, v...)
+	}
+}
+
+func (l *legacyLoggerAdapter) Debugf(ctx context.Context, format string, v ...interface{}) {
+	if LogLevel.DebugOrAbove() {
+		Logger.Printf(ctx, format, v...)
+	}
+}
+
+func (l legacyLoggerAdapter) Errorf(ctx context.Context, format string, v ...interface{}) {
+	Logger.Printf(ctx, format, v...)
+}
+
+func (l legacyLoggerAdapter) Enabled(_ context.Context, level LogLevelT) bool {
+	switch level {
+	case LogLevelWarn:
+		return LogLevel.WarnOrAbove()
+	case LogLevelInfo:
+		return LogLevel.InfoOrAbove()
+	case LogLevelDebug:
+		return LogLevel.DebugOrAbove()
+	case LogLevelError:
+		fallthrough
+	default:
+		return true
+	}
+}
+
+var LegacyLoggerWithLevel LoggerWithLevel = &legacyLoggerAdapter{}

internal/pool/pool.go

@@ -115,6 +115,9 @@ type Options struct {
 	// DialerRetryTimeout is the backoff duration between retry attempts.
 	// Default: 100ms
 	DialerRetryTimeout time.Duration
+
+	// Optional logger for connection pool operations.
+	Logger internal.LoggerWithLevel
 }
 
 type lastDialErrorWrap struct {
@@ -223,7 +226,7 @@ func (p *ConnPool) checkMinIdleConns() {
 						p.idleConnsLen.Add(-1)
 
 						p.freeTurn()
-						internal.Logger.Printf(context.Background(), "addIdleConn panic: %+v", err)
+						p.logger().Errorf(context.Background(), "addIdleConn panic: %+v", err)
 					}
 				}()
 
@@ -379,7 +382,7 @@ func (p *ConnPool) dialConn(ctx context.Context, pooled bool) (*Conn, error) {
 		return cn, nil
 	}
 
-	internal.Logger.Printf(ctx, "redis: connection pool: failed to dial after %d attempts: %v", maxRetries, lastErr)
+	p.logger().Errorf(ctx, "redis: connection pool: failed to dial after %d attempts: %v", maxRetries, lastErr)
 	// All retries failed - handle error tracking
 	p.setLastDialError(lastErr)
 	if atomic.AddUint32(&p.dialErrorsNum, 1) == uint32(p.cfg.PoolSize) {
@@ -452,7 +455,7 @@ func (p *ConnPool) getConn(ctx context.Context) (*Conn, error) {
 
 	for {
 		if attempts >= getAttempts {
-			internal.Logger.Printf(ctx, "redis: connection pool: was not able to get a healthy connection after %d attempts", attempts)
+			p.logger().Errorf(ctx, "redis: connection pool: was not able to get a healthy connection after %d attempts", attempts)
 			break
 		}
 		attempts++
@@ -479,12 +482,12 @@ func (p *ConnPool) getConn(ctx context.Context) (*Conn, error) {
 		if hookManager != nil {
 			acceptConn, err := hookManager.ProcessOnGet(ctx, cn, false)
 			if err != nil {
-				internal.Logger.Printf(ctx, "redis: connection pool: failed to process idle connection by hook: %v", err)
+				p.logger().Errorf(ctx, "redis: connection pool: failed to process idle connection by hook: %v", err)
 				_ = p.CloseConn(cn)
 				continue
 			}
 			if !acceptConn {
-				internal.Logger.Printf(ctx, "redis: connection pool: conn[%d] rejected by hook, returning to pool", cn.GetID())
+				p.logger().Errorf(ctx, "redis: connection pool: conn[%d] rejected by hook, returning to pool", cn.GetID())
 				p.Put(ctx, cn)
 				cn = nil
 				continue
@@ -509,7 +512,7 @@ func (p *ConnPool) getConn(ctx context.Context) (*Conn, error) {
 		// this should not happen with a new connection, but we handle it gracefully
 		if err != nil || !acceptConn {
 			// Failed to process connection, discard it
-			internal.Logger.Printf(ctx, "redis: connection pool: failed to process new connection conn[%d] by hook: accept=%v, err=%v", newcn.GetID(), acceptConn, err)
+			p.logger().Errorf(ctx, "redis: connection pool: failed to process new connection conn[%d] by hook: accept=%v, err=%v", newcn.GetID(), acceptConn, err)
 			_ = p.CloseConn(newcn)
 			return nil, err
 		}
@@ -703,7 +706,7 @@ func (p *ConnPool) popIdle() (*Conn, error) {
 
 	// If we exhausted all attempts without finding a usable connection, return nil
 	if attempts > 1 && attempts >= maxAttempts && int32(attempts) >= p.poolSize.Load() {
-		internal.Logger.Printf(context.Background(), "redis: connection pool: failed to get a usable connection after %d attempts", attempts)
+		p.logger().Errorf(context.Background(), "redis: connection pool: failed to get a usable connection after %d attempts", attempts)
 		return nil, nil
 	}
 
@@ -720,7 +723,7 @@ func (p *ConnPool) Put(ctx context.Context, cn *Conn) {
 		// Peek at the reply type to check if it's a push notification
 		if replyType, err := cn.PeekReplyTypeSafe(); err != nil || replyType != proto.RespPush {
 			// Not a push notification or error peeking, remove connection
-			internal.Logger.Printf(ctx, "Conn has unread data (not push notification), removing it")
+			p.logger().Errorf(ctx, "Conn has unread data (not push notification), removing it")
 			p.Remove(ctx, cn, err)
 		}
 		// It's a push notification, allow pooling (client will handle it)
@@ -733,7 +736,7 @@ func (p *ConnPool) Put(ctx context.Context, cn *Conn) {
 	if hookManager != nil {
 		shouldPool, shouldRemove, err = hookManager.ProcessOnPut(ctx, cn)
 		if err != nil {
-			internal.Logger.Printf(ctx, "Connection hook error: %v", err)
+			p.logger().Errorf(ctx, "Connection hook error: %v", err)
 			p.Remove(ctx, cn, err)
 			return
 		}
@@ -835,7 +838,7 @@ func (p *ConnPool) removeConn(cn *Conn) {
 		// this can be idle conn
 		for idx, ic := range p.idleConns {
 			if ic.GetID() == cid {
-				internal.Logger.Printf(context.Background(), "redis: connection pool: removing idle conn[%d]", cid)
+				p.logger().Errorf(context.Background(), "redis: connection pool: removing idle conn[%d]", cid)
 				p.idleConns = append(p.idleConns[:idx], p.idleConns[idx+1:]...)
 				p.idleConnsLen.Add(-1)
 				break
@@ -951,7 +954,7 @@ func (p *ConnPool) isHealthyConn(cn *Conn, now time.Time) bool {
 			if replyType, err := cn.rd.PeekReplyType(); err == nil && replyType == proto.RespPush {
 				// For RESP3 connections with push notifications, we allow some buffered data
 				// The client will process these notifications before using the connection
-				internal.Logger.Printf(context.Background(), "push: conn[%d] has buffered data, likely push notifications - will be processed by client", cn.GetID())
+				p.logger().Infof(context.Background(), "push: conn[%d] has buffered data, likely push notifications - will be processed by client", cn.GetID())
 				return true // Connection is healthy, client will handle notifications
 			}
 			return false // Unexpected data, not push notifications, connection is unhealthy
@@ -961,3 +964,11 @@ func (p *ConnPool) isHealthyConn(cn *Conn, now time.Time) bool {
 	}
 	return true
 }
+
+func (p *ConnPool) logger() internal.LoggerWithLevel {
+	if p.cfg.Logger != nil {
+		return p.cfg.Logger
+	}
+
+	return internal.LegacyLoggerWithLevel
+}

logging/logging.go

@@ -89,3 +89,4 @@ func (l *filterLogger) Printf(ctx context.Context, format string, v ...interface
 		return
 	}
 }
+

maintnotifications/circuit_breaker.go

@@ -102,9 +102,7 @@ func (cb *CircuitBreaker) Execute(fn func() error) error {
 			if cb.state.CompareAndSwap(int32(CircuitBreakerOpen), int32(CircuitBreakerHalfOpen)) {
 				cb.requests.Store(0)
 				cb.successes.Store(0)
-				if internal.LogLevel.InfoOrAbove() {
-					internal.Logger.Printf(context.Background(), logs.CircuitBreakerTransitioningToHalfOpen(cb.endpoint))
-				}
+				cb.logger().Infof(context.Background(), logs.CircuitBreakerTransitioningToHalfOpen(cb.endpoint))
 				// Fall through to half-open logic
 			} else {
 				return ErrCircuitBreakerOpen
@@ -144,17 +142,13 @@ func (cb *CircuitBreaker) recordFailure() {
 	case CircuitBreakerClosed:
 		if failures >= int64(cb.failureThreshold) {
 			if cb.state.CompareAndSwap(int32(CircuitBreakerClosed), int32(CircuitBreakerOpen)) {
-				if internal.LogLevel.WarnOrAbove() {
-					internal.Logger.Printf(context.Background(), logs.CircuitBreakerOpened(cb.endpoint, failures))
-				}
+				cb.logger().Warnf(context.Background(), logs.CircuitBreakerOpened(cb.endpoint, failures))
 			}
 		}
 	case CircuitBreakerHalfOpen:
 		// Any failure in half-open state immediately opens the circuit
 		if cb.state.CompareAndSwap(int32(CircuitBreakerHalfOpen), int32(CircuitBreakerOpen)) {
-			if internal.LogLevel.WarnOrAbove() {
-				internal.Logger.Printf(context.Background(), logs.CircuitBreakerReopened(cb.endpoint))
-			}
+			cb.logger().Warnf(context.Background(), logs.CircuitBreakerReopened(cb.endpoint))
 		}
 	}
 }
@@ -176,9 +170,7 @@ func (cb *CircuitBreaker) recordSuccess() {
 		if successes >= int64(cb.maxRequests) {
 			if cb.state.CompareAndSwap(int32(CircuitBreakerHalfOpen), int32(CircuitBreakerClosed)) {
 				cb.failures.Store(0)
-				if internal.LogLevel.InfoOrAbove() {
-					internal.Logger.Printf(context.Background(), logs.CircuitBreakerClosed(cb.endpoint, successes))
-				}
+				cb.logger().Infof(context.Background(), logs.CircuitBreakerClosed(cb.endpoint, successes))
 			}
 		}
 	}
@@ -202,6 +194,13 @@ func (cb *CircuitBreaker) GetStats() CircuitBreakerStats {
 	}
 }
 
+func (cb *CircuitBreaker) logger() internal.LoggerWithLevel {
+	if cb.config != nil && cb.config.Logger != nil {
+		return cb.config.Logger
+	}
+	return internal.LegacyLoggerWithLevel
+}
+
 // CircuitBreakerStats provides statistics about a circuit breaker
 type CircuitBreakerStats struct {
 	Endpoint        string
@@ -325,8 +324,8 @@ func (cbm *CircuitBreakerManager) cleanup() {
 	}
 
 	// Log cleanup results
-	if len(toDelete) > 0 && internal.LogLevel.InfoOrAbove() {
-		internal.Logger.Printf(context.Background(), logs.CircuitBreakerCleanup(len(toDelete), count))
+	if len(toDelete) > 0 {
+		cbm.logger().Infof(context.Background(), logs.CircuitBreakerCleanup(len(toDelete), count))
 	}
 
 	cbm.lastCleanup.Store(now.Unix())
@@ -351,3 +350,10 @@ func (cbm *CircuitBreakerManager) Reset() {
 		return true
 	})
 }
+
+func (cbm *CircuitBreakerManager) logger() internal.LoggerWithLevel {
+	if cbm.config != nil && cbm.config.Logger != nil {
+		return cbm.config.Logger
+	}
+	return internal.LegacyLoggerWithLevel
+}

maintnotifications/config.go

@@ -128,6 +128,9 @@ type Config struct {
 	// After this many retries, the connection will be removed from the pool.
 	// Default: 3
 	MaxHandoffRetries int
+
+	// Logger is an optional custom logger for maintenance notifications.
+	Logger internal.LoggerWithLevel
 }
 
 func (c *Config) IsEnabled() bool {
@@ -312,10 +315,9 @@ func (c *Config) ApplyDefaultsWithPoolConfig(poolSize int, maxActiveConns int) *
 		result.CircuitBreakerMaxRequests = c.CircuitBreakerMaxRequests
 	}
 
-	if internal.LogLevel.DebugOrAbove() {
-		internal.Logger.Printf(context.Background(), logs.DebugLoggingEnabled())
-		internal.Logger.Printf(context.Background(), logs.ConfigDebug(result))
-	}
+	c.logger().Debugf(context.Background(), logs.DebugLoggingEnabled())
+	c.logger().Debugf(context.Background(), logs.ConfigDebug(result))
+
 	return result
 }
 
@@ -341,6 +343,8 @@ func (c *Config) Clone() *Config {
 
 		// Configuration fields
 		MaxHandoffRetries: c.MaxHandoffRetries,
+
+		Logger: c.Logger,
 	}
 }
 
@@ -365,6 +369,13 @@ func (c *Config) applyWorkerDefaults(poolSize int) {
 	}
 }
 
+func (c *Config) logger() internal.LoggerWithLevel {
+	if c.Logger != nil {
+		return c.Logger
+	}
+	return internal.LegacyLoggerWithLevel
+}
+
 // DetectEndpointType automatically detects the appropriate endpoint type
 // based on the connection address and TLS configuration.
 //