add deprecation notice to Logger and LegacyLogLevel, change default log level to None, rename AdvancedLogger to StructuredLogger

Author: joao-r-reis

cluster.go

@@ -259,19 +259,32 @@ type ClusterConfig struct {
 	// If not provided, Dialer will be used instead.
 	HostDialer HostDialer
 
+	// Deprecated: use StructuredLogger instead, Logger and LegacyLogLevel will be removed in the future.
+	//
 	// Logger for this ClusterConfig.
 	// If not specified, defaults to the gocql.defaultLogger.
 	Logger StdLogger
 
 	// StructuredLogger for this ClusterConfig.
-	// If not specified, Logger will be used instead.
-	StructuredLogger AdvancedLogger
+	// If not specified, Logger will be used instead (note that Logger is deprecated).
+	//
+	// There are 3 built in implementations of StructuredLogger:
+	//  - std library "log" package: gocql.NewLogger
+	//  - zerolog: gocqlzerolog.NewZerologLogger
+	//  - zap: gocqlzap.NewZapLogger
+	//
+	// The logger created by gocql.NewLogger behaves in a similar way as the legacy default logger, but you can set a log level.
+	//
+	// You can also provide your own logger implementation of the StructuredLogger interface.
+	StructuredLogger StructuredLogger
 
+	// Deprecated: use StructuredLogger instead, Logger and LegacyLogLevel will be removed in the future.
+	//
 	// LegacyLogLevel for this ClusterConfig, this is only applied for legacy loggers (field Logger).
 	// This log level is not applied to StructuredLogger because the log level is already a part of the interface
 	// so the implementation can decide when not to log something.
 	//
-	// If not specified, LogLevelWarn will be used as the default.
+	// If not specified, LogLevelNone will be used as the default.
 	LegacyLogLevel LogLevel
 
 	// internal config for testing
@@ -309,7 +322,7 @@ func NewCluster(hosts ...string) *ClusterConfig {
 		ConvictionPolicy:       &SimpleConvictionPolicy{},
 		ReconnectionPolicy:     &ConstantReconnectionPolicy{MaxRetries: 3, Interval: 1 * time.Second},
 		WriteCoalesceWaitTime:  200 * time.Microsecond,
-		LegacyLogLevel:         LogLevelWarn,
+		LegacyLogLevel:         LogLevelNone,
 	}
 	return cfg
 }

conn.go

@@ -145,7 +145,7 @@ type ConnConfig struct {
 	AuthProvider     func(h *HostInfo) (Authenticator, error)
 	Keepalive        time.Duration
 	Logger           StdLogger
-	StructuredLogger AdvancedLogger
+	StructuredLogger StructuredLogger
 	LegacyLogLevel   LogLevel
 
 	tlsConfig       *tls.Config

extensions/gocqlzap/zap.go

@@ -8,7 +8,7 @@ import (
 const DefaultName = "gocql"
 
 type Logger interface {
-	gocql.AdvancedLogger
+	gocql.StructuredLogger
 	ZapLogger() *zap.Logger
 }
 

extensions/gocqlzerolog/zerolog.go

@@ -9,7 +9,7 @@ const DefaultName = "gocql"
 const DefaultNameField = "logger"
 
 type Logger interface {
-	gocql.AdvancedLogger
+	gocql.StructuredLogger
 	ZerologLogger() zerolog.Logger
 }
 

logger.go

@@ -87,14 +87,19 @@ func (l *testLogger) String() string {
 
 type defaultLogger struct{}
 
+// NewLogger creates an StructuredLogger that uses the standard library "log" package.
+func NewLogger(logLevel LogLevel) StructuredLogger {
+	return newInternalLoggerFromStdLogger(&defaultLogger{}, logLevel)
+}
+
 func (l *defaultLogger) Print(v ...interface{})                 { log.Print(v...) }
 func (l *defaultLogger) Printf(format string, v ...interface{}) { log.Printf(format, v...) }
 func (l *defaultLogger) Println(v ...interface{})               { log.Println(v...) }
 
 var nilInternalLogger internalLogger = loggerAdapter{
-	legacyLogLevel: LogLevelNone,
-	advLogger:      nopLogger{},
-	legacyLogger:   nil,
+	logLevel:     LogLevelNone,
+	advLogger:    nopLogger{},
+	legacyLogger: nil,
 }
 
 type LogLevel int
@@ -174,21 +179,21 @@ func newLogFieldBool(name string, value bool) LogField {
 	return newLogField(name, logFieldValueBool(value))
 }
 
-type AdvancedLogger interface {
+type StructuredLogger interface {
 	Error(msg string, fields ...LogField)
 	Warning(msg string, fields ...LogField)
 	Info(msg string, fields ...LogField)
 	Debug(msg string, fields ...LogField)
 }
 
 type internalLogger interface {
-	AdvancedLogger
+	StructuredLogger
 }
 
 type loggerAdapter struct {
-	legacyLogLevel LogLevel
-	advLogger      AdvancedLogger
-	legacyLogger   StdLogger
+	logLevel     LogLevel
+	advLogger    StructuredLogger
+	legacyLogger StdLogger
 }
 
 func (recv loggerAdapter) logLegacy(msg string, fields ...LogField) {
@@ -211,36 +216,36 @@ func (recv loggerAdapter) logLegacy(msg string, fields ...LogField) {
 func (recv loggerAdapter) Error(msg string, fields ...LogField) {
 	if recv.advLogger != nil {
 		recv.advLogger.Error(msg, fields...)
-	} else if LogLevelError <= recv.legacyLogLevel {
+	} else if LogLevelError <= recv.logLevel {
 		recv.logLegacy(msg, fields...)
 	}
 }
 
 func (recv loggerAdapter) Warning(msg string, fields ...LogField) {
 	if recv.advLogger != nil {
 		recv.advLogger.Warning(msg, fields...)
-	} else if LogLevelWarn <= recv.legacyLogLevel {
+	} else if LogLevelWarn <= recv.logLevel {
 		recv.logLegacy(msg, fields...)
 	}
 }
 
 func (recv loggerAdapter) Info(msg string, fields ...LogField) {
 	if recv.advLogger != nil {
 		recv.advLogger.Info(msg, fields...)
-	} else if LogLevelInfo <= recv.legacyLogLevel {
+	} else if LogLevelInfo <= recv.logLevel {
 		recv.logLegacy(msg, fields...)
 	}
 }
 
 func (recv loggerAdapter) Debug(msg string, fields ...LogField) {
 	if recv.advLogger != nil {
 		recv.advLogger.Debug(msg, fields...)
-	} else if LogLevelDebug <= recv.legacyLogLevel {
+	} else if LogLevelDebug <= recv.logLevel {
 		recv.logLegacy(msg, fields...)
 	}
 }
 
-func newInternalLoggerFromAdvancedLogger(logger AdvancedLogger) loggerAdapter {
+func newInternalLoggerFromAdvancedLogger(logger StructuredLogger) loggerAdapter {
 	return loggerAdapter{
 		advLogger:    logger,
 		legacyLogger: nil,
@@ -249,9 +254,9 @@ func newInternalLoggerFromAdvancedLogger(logger AdvancedLogger) loggerAdapter {
 
 func newInternalLoggerFromStdLogger(logger StdLogger, level LogLevel) loggerAdapter {
 	return loggerAdapter{
-		legacyLogLevel: level,
-		advLogger:      nil,
-		legacyLogger:   logger,
+		logLevel:     level,
+		advLogger:    nil,
+		legacyLogger: logger,
 	}
 }