Praposal for logging support for msal-go

apps/confidential/confidential.go

@@ -24,6 +24,7 @@ import (
 	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/cache"
 	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/internal/base"
 	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/internal/exported"
+	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/internal/logger"
 	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/internal/oauth"
 	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/internal/oauth/ops"
 	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/internal/oauth/ops/accesstokens"
@@ -250,6 +251,7 @@ type clientOptions struct {
 	capabilities                      []string
 	disableInstanceDiscovery, sendX5C bool
 	httpClient                        ops.HTTPClient
+	logger                            logger.LoggerInterface
 }
 
 // Option is an optional argument to New().
@@ -318,12 +320,17 @@ func New(authority, clientID string, cred Credential, options ...Option) (Client
 		return Client{}, err
 	}
 	autoEnabledRegion := os.Getenv("MSAL_FORCE_REGION")
+	defaultLogger, err := logger.New(nil)
+	if err != nil {
+		return Client{}, err
+	}
 	opts := clientOptions{
 		authority: authority,
 		// if the caller specified a token provider, it will handle all details of authentication, using Client only as a token cache
 		disableInstanceDiscovery: cred.tokenProvider != nil,
 		httpClient:               shared.DefaultClient,
 		azureRegion:              autoEnabledRegion,
+		logger:                   defaultLogger,
 	}
 	for _, o := range options {
 		o(&opts)
@@ -345,6 +352,7 @@ func New(authority, clientID string, cred Credential, options ...Option) (Client
 	}
 	base.AuthParams.IsConfidentialClient = true
 
+	opts.logger.Log(logger.Info, "Created confidential client", logger.Field("clientID", clientID))
 	return Client{base: base, cred: internalCred}, nil
 }
 

apps/confidential/confidential_121_plus.go

@@ -0,0 +1,21 @@
+//go:build go1.21
+
+package confidential
+
+import (
+	"fmt"
+
+	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/internal/logger"
+)
+
+//  WithLogger allows for a custom logger to be set.
+func WithLogger(l interface{}) Option {
+	return func(o *clientOptions) {
+		logInstance, err := logger.New(l)
+		if err != nil {
+			fmt.Println("Error creating logger with slog:", err)
+			return
+		}
+		o.logger = logInstance
+	}
+}

apps/design/logging.md

@@ -0,0 +1,36 @@
+# Logging
+
+GO 1.21 introduces enhanced features like structured logging with `log/slog`.
+As part of MSAL GO, we have decided to only support logging using slog from version 1.21.
+The reason for this is `log/slog` greatly enhances the debugging and monitoring capabilities compared to the old SDK. This is especially useful in production environments where accurate, traceable logs are crucial for maintaining application health and troubleshooting issues. For versions older than 1.21, the user can specify *nil* to the *New()* function and a no-op is returned
+
+## **Expected Output**
+
+```plaintext
+time=2024-12-19T01:25:58.730Z level=INFO msg="This is an info message via slog." username=john_doe age=30
+time=2024-12-19T01:25:58.730Z level=ERROR msg="This is an error message via slog." module=user-service retry=3
+time=2024-12-19T01:25:58.730Z level=WARN msg="Disk space is low." free_space_mb=100
+time=2024-12-19T01:25:58.730Z level=INFO msg="Default log message." module=main
+```
+
+## Key Pointers
+
+1. **For Go <= 1.20**:
+   - User should pass *nil* to `logger.New(nil)`
+   - No-op is returned and can be handled by user
+
+2. **Full `slog` Support for Go 1.21+**:
+   - The `logger.go` file leverages the `slog` package, supporting structured logs, multiple log levels (`info`, `error`, `warn`), and fields.
+
+3. **Structured Logging**:
+   - You can pass key-value pairs using `slog.String`, `slog.Int`, etc., for structured logging, which is handled by `slog` in Go 1.21 and later.
+
+### **Sample**
+
+A sample of the logger can be found in the following location:
+
+```plaintext
+microsoft-authentication-library-for-go/apps/devapps
+├── logger/
+│   ├── logger_sample.go
+```

apps/internal/logger/logger.go

@@ -0,0 +1,19 @@
+package logger
+
+type Level string
+
+const (
+	Info  Level = "info"
+	Err   Level = "error"
+	Warn  Level = "warn"
+	Debug Level = "debug"
+)
+
+// LoggerInterface defines the methods that a logger should implement
+type LoggerInterface interface {
+	Log(level Level, message string, fields ...any)
+}
+
+func New(loggerInterface interface{}) (LoggerInterface, error) {
+	return NewLogger(loggerInterface)
+}

apps/internal/logger/logger_121_below.go

@@ -0,0 +1,19 @@
+//go:build go1.18 && !go1.21
+
+package logger
+
+type logger struct{}
+
+func NewLogger(loggerInterface interface{}) (LoggerInterface, error) {
+	return &logger{}, nil
+}
+
+// Log method for Go 1.21+ with full support for structured logging and multiple log levels.
+func (a *logger) Log(level Level, message string, fields ...any) {
+	return
+}
+
+// Field creates a slog field for any value
+func Field(key string, value any) any {
+	return ""
+}

apps/internal/logger/logger_121_plus.go

@@ -0,0 +1,60 @@
+//go:build go1.21
+
+package logger
+
+import (
+	"context"
+	"fmt"
+	"log/slog"
+)
+
+// logger struct for Go 1.21+ with full `slog` logging support.
+type logger struct {
+	logging *slog.Logger
+}
+
+// New creates a new logger instance
+func NewLogger(loggerInterface interface{}) (LoggerInterface, error) {
+	if loggerInterface == nil {
+		return &logger{logging: nil}, nil
+	}
+
+	if loggerInterface, ok := loggerInterface.(*slog.Logger); ok {
+		return &logger{logging: loggerInterface}, nil
+	}
+
+	return nil, fmt.Errorf("invalid input for Go 1.21+; expected *slog.Logger")
+}
+
+// Log method for Go 1.21+ with full support for structured logging and multiple log levels.
+func (a *logger) Log(level Level, message string, fields ...any) {
+	if a == nil || a.logging == nil {
+		return
+	}
+	var slogLevel slog.Level
+	switch level {
+	case Info:
+		slogLevel = slog.LevelInfo
+	case Err:
+		slogLevel = slog.LevelError
+	case Warn:
+		slogLevel = slog.LevelWarn
+	case Debug:
+		slogLevel = slog.LevelDebug
+	default:
+		slogLevel = slog.LevelInfo
+	}
+
+	// Log the entry with the message and fields
+	a.logging.Log(
+		context.Background(),
+		slogLevel,
+		message,
+		fields...,
+	)
+}
+
+// Field creates a slog field for any value
+func Field(key string, value any) any {
+	return slog.Any(key, value)
+}

apps/internal/logger/logger_test.go

@@ -0,0 +1,58 @@
+//go:build go1.21
+
+package logger
+
+import (
+	"bytes"
+	"log/slog"
+	"testing"
+)
+
+func TestLogger_Log_ConsoleOutput(t *testing.T) {
+	// Capture the console output
+	var buf bytes.Buffer
+	handler := slog.NewJSONHandler(&buf, &slog.HandlerOptions{
+		Level: slog.LevelDebug, // Set the log level to Debug to capture all log levels
+	})
+
+	// Create a new logger instance
+	slogLogger := slog.New(handler)
+	logInstance, err := New(slogLogger)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+
+	// Log messages
+	logInstance.Log(Info, "This is an info message via slog.", Field("username", "john_doe"), slog.Int("age", 30))
+	logInstance.Log(Err, "This is an error message via slog.", slog.String("module", "user-service"), slog.Int("retry", 3))
+	logInstance.Log(Warn, "This is a warn message via slog.", slog.Int("free_space_mb", 100))
+	logInstance.Log(Debug, "This is a debug message via slog.", slog.String("module", "main"))
+
+	// Check the output
+	output := buf.String()
+	expectedMessages := []string{
+		"This is an info message via slog.",
+		"This is an error message via slog.",
+		"This is a warn message via slog.",
+		"This is a debug message via slog.",
+	}
+
+	for _, msg := range expectedMessages {
+		if !bytes.Contains([]byte(output), []byte(msg)) {
+			t.Errorf("expected log message %q not found in output", msg)
+		}
+	}
+}
+
+// This test is to emulate what happens if the user has a go version < 1.21
+// In this case, they will not have access to slog and will need to pass nil to the New function
+func TestLogger_New_NilLogger(t *testing.T) {
+	// Attempt to create a new logger instance with nil slog.Logger
+	logInstance, err := New(nil)
+	if err != nil {
+		t.Fatalf("expected no error, got %v", err)
+	}
+	if logInstance == nil {
+		t.Fatalf("expected non-nil logInstance, got nil")
+	}
+}

apps/tests/devapps/logger/logger_sample.go

@@ -0,0 +1,25 @@
+package main
+
+import (
+	"fmt"
+	"log/slog"
+	"os"
+
+	"github.com/AzureAD/microsoft-authentication-library-for-go/apps/internal/logger"
+)
+
+func main() {
+	// Test for Go 1.21+
+	handlerOptions := &slog.HandlerOptions{}
+	slogLogger := slog.New(slog.NewTextHandler(os.Stdout, handlerOptions))
+	logInstance, err := logger.New(slogLogger)
+	if err != nil {
+		fmt.Println("Error creating logger with slog:", err)
+		return
+	}
+
+	logInstance.Log(logger.Info, "This is a info message via slog.", slog.String("username", "john_doe"), slog.Int("age", 30))
+	logInstance.Log(logger.Err, "This is a error message via slog.", slog.String("module", "user-service"), slog.Int("retry", 3))
+	logInstance.Log(logger.Warn, "This is a warn message via slog.", slog.Int("free_space_mb", 100))
+	logInstance.Log(logger.Debug, "This is a debug message via slog.", slog.String("module", "main"))
+}