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

@@ -119,6 +119,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 {
@@ -254,7 +257,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)
 					}
 				}()
 
@@ -416,7 +419,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", attempt, lastErr)
+	p.logger().Errorf(ctx, "redis: connection pool: failed to dial after %d attempts: %v", attempt, lastErr)
 	// All retries failed - handle error tracking
 	p.setLastDialError(lastErr)
 	if atomic.AddUint32(&p.dialErrorsNum, 1) == uint32(p.cfg.PoolSize) {
@@ -510,10 +513,10 @@ func (p *ConnPool) getConn(ctx context.Context) (*Conn, error) {
 			acceptConn, err := hookManager.ProcessOnGet(ctx, cn, false)
 			if err != nil || !acceptConn {
 				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)
 				} else {
-					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())
 					// Return connection to pool without freeing the turn that this Get() call holds.
 					// We use putConnWithoutTurn() to run all the Put hooks and logic without freeing a turn.
 					p.putConnWithoutTurn(ctx, cn)
@@ -541,7 +544,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
 		}
@@ -583,7 +586,7 @@ func (p *ConnPool) queuedNewConn(ctx context.Context) (*Conn, error) {
 				if !freeTurnCalled {
 					p.freeTurn()
 				}
-				internal.Logger.Printf(context.Background(), "queuedNewConn panic: %+v", err)
+				p.logger().Errorf(ctx, "queuedNewConn panic: %+v", err)
 			}
 		}()
 
@@ -736,7 +739,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
 	}
 
@@ -765,7 +768,7 @@ func (p *ConnPool) putConn(ctx context.Context, cn *Conn, freeTurn bool) {
 		// 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.removeConnInternal(ctx, cn, err, freeTurn)
 			return
 		}
@@ -778,7 +781,7 @@ func (p *ConnPool) putConn(ctx context.Context, cn *Conn, freeTurn bool) {
 	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.removeConnInternal(ctx, cn, err, freeTurn)
 			return
 		}
@@ -811,12 +814,12 @@ func (p *ConnPool) putConn(ctx context.Context, cn *Conn, freeTurn bool) {
 			case StateUnusable:
 				// expected state, don't log it
 			case StateClosed:
-				internal.Logger.Printf(ctx, "Unexpected conn[%d] state changed by hook to %v, closing it", cn.GetID(), currentState)
+				p.logger().Errorf(ctx, "Unexpected conn[%d] state changed by hook to %v, closing it", cn.GetID(), currentState)
 				shouldCloseConn = true
 				p.removeConnWithLock(cn)
 			default:
 				// Pool as-is
-				internal.Logger.Printf(ctx, "Unexpected conn[%d] state changed by hook to %v, pooling as-is", cn.GetID(), currentState)
+				p.logger().Warnf(ctx, "Unexpected conn[%d] state changed by hook to %v, pooling as-is", cn.GetID(), currentState)
 			}
 		}
 
@@ -1030,7 +1033,7 @@ func (p *ConnPool) isHealthyConn(cn *Conn, nowNs int64) 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(
+				p.logger().Infof(
 					context.Background(),
 					"push: conn[%d] has buffered data, likely push notifications - will be processed by client",
 					cn.GetID(),
@@ -1053,3 +1056,11 @@ func (p *ConnPool) isHealthyConn(cn *Conn, nowNs int64) bool {
 	cn.SetUsedAtNs(nowNs)
 	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.
 //