Adds log level guard functions (#299)

* Adds `loggertest.ProviderRootWithLevel`

* Adds guard functions to provider root logger

* Adds guard functions to provider subsystem logger

* Adds `loggertest.SDKRootWithLevel`

* Adds guard functions to SDK root logger

* Adds guard functions to SDK subsystem logger

* Adds example tests

* Fixes linter errors in SDK logging tests

Author: gdavison

internal/loggertest/provider.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"io"
 
+	"github.com/hashicorp/go-hclog"
 	"github.com/hashicorp/terraform-plugin-log/internal/logging"
 	"github.com/hashicorp/terraform-plugin-log/tfsdklog"
 )
@@ -20,6 +21,30 @@ func ProviderRoot(ctx context.Context, output io.Writer) context.Context {
 	)
 }
 
+// SDKRootWithLevel creates an SDK root logger at the given level.
+// Use this in tests that need to verify behaviour at a specific log level.
+func SDKRootWithLevel(ctx context.Context, output io.Writer, level hclog.Level) context.Context {
+	return tfsdklog.NewRootSDKLogger(
+		ctx,
+		logging.WithoutLocation(),
+		logging.WithoutTimestamp(),
+		logging.WithOutput(output),
+		tfsdklog.WithLevel(level),
+	)
+}
+
+// ProviderRootWithLevel creates a provider root logger at the given level.
+// Use this in tests that need to verify behaviour at a specific log level.
+func ProviderRootWithLevel(ctx context.Context, output io.Writer, level hclog.Level) context.Context {
+	return tfsdklog.NewRootProviderLogger(
+		ctx,
+		logging.WithoutLocation(),
+		logging.WithoutTimestamp(),
+		logging.WithOutput(output),
+		tfsdklog.WithLevel(level),
+	)
+}
+
 // ProviderRootWithLocation is for testing code that affects go-hclog's caller
 // information (location offset). Most testing code should avoid this, since
 // correctly checking differences including the location is extra effort

tflog/provider.go

@@ -140,6 +140,51 @@ func Error(ctx context.Context, msg string, additionalFields ...map[string]inter
 	logger.Error(msg, additionalArgs...)
 }
 
+// IsTrace returns true if the logger in ctx would emit a trace-level log.
+func IsTrace(ctx context.Context) bool {
+	logger := logging.GetProviderRootLogger(ctx)
+	if logger == nil {
+		return false
+	}
+	return logger.IsTrace()
+}
+
+// IsDebug returns true if the logger in ctx would emit a debug-level log.
+func IsDebug(ctx context.Context) bool {
+	logger := logging.GetProviderRootLogger(ctx)
+	if logger == nil {
+		return false
+	}
+	return logger.IsDebug()
+}
+
+// IsInfo returns true if the logger in ctx would emit an info-level log.
+func IsInfo(ctx context.Context) bool {
+	logger := logging.GetProviderRootLogger(ctx)
+	if logger == nil {
+		return false
+	}
+	return logger.IsInfo()
+}
+
+// IsWarn returns true if the logger in ctx would emit a warn-level log.
+func IsWarn(ctx context.Context) bool {
+	logger := logging.GetProviderRootLogger(ctx)
+	if logger == nil {
+		return false
+	}
+	return logger.IsWarn()
+}
+
+// IsError returns true if the logger in ctx would emit an error-level log.
+func IsError(ctx context.Context) bool {
+	logger := logging.GetProviderRootLogger(ctx)
+	if logger == nil {
+		return false
+	}
+	return logger.IsError()
+}
+
 // OmitLogWithFieldKeys returns a new context.Context that has a modified logger
 // that will omit to write any log when any of the given keys is found
 // within its fields.

tflog/provider_example_test.go

@@ -365,3 +365,27 @@ func ExampleMaskLogStrings() {
 	// Output:
 	// {"@level":"trace","@message":"example log ***","@module":"provider","k1":"*** plus some text","k2":"*** plus more text"}
 }
+
+func ExampleIsTrace() {
+	// virtually no plugin developers will need to worry about
+	// instantiating loggers, as the libraries they're using will take care
+	// of that, but we're not using those libraries in these examples. So
+	// we need to do the injection ourselves. Plugin developers will
+	// basically never need to do this, so the next line can safely be
+	// considered setup for the example and ignored. Instead, use the
+	// context passed in by the framework or library you're using.
+	exampleCtx := getExampleContext()
+
+	// non-example-setup code begins here
+
+	// use IsTrace to skip building fields when trace logging is not enabled
+	if IsTrace(exampleCtx) {
+		fields := map[string]interface{}{
+			"computed-key": "computed-value",
+		}
+		Trace(exampleCtx, "hello, world", fields)
+	}
+
+	// Output:
+	// {"@level":"trace","@message":"hello, world","@module":"provider","computed-key":"computed-value"}
+}

tflog/provider_test.go

@@ -10,6 +10,7 @@ import (
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
+	"github.com/hashicorp/go-hclog"
 	"github.com/hashicorp/terraform-plugin-log/internal/loggertest"
 	"github.com/hashicorp/terraform-plugin-log/tflog"
 )
@@ -1858,3 +1859,203 @@ func TestMaskLogStrings(t *testing.T) {
 		})
 	}
 }
+
+func TestIsTrace(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		level    hclog.Level
+		expected bool
+	}{
+		"root-level-trace": {level: hclog.Trace, expected: true},
+		"root-level-debug": {level: hclog.Debug, expected: false},
+		"root-level-info":  {level: hclog.Info, expected: false},
+		"root-level-warn":  {level: hclog.Warn, expected: false},
+		"root-level-error": {level: hclog.Error, expected: false},
+	}
+
+	for name, testCase := range testCases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var outputBuffer bytes.Buffer
+
+			ctx := context.Background()
+			ctx = loggertest.ProviderRootWithLevel(ctx, &outputBuffer, testCase.level)
+
+			got := tflog.IsTrace(ctx)
+
+			if got != testCase.expected {
+				t.Errorf("expected %v, got %v", testCase.expected, got)
+			}
+		})
+	}
+
+	t.Run("no-logger", func(t *testing.T) {
+		t.Parallel()
+
+		if got := tflog.IsTrace(context.Background()); got != false {
+			t.Errorf("expected false with no logger in context, got %v", got)
+		}
+	})
+}
+
+func TestIsDebug(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		level    hclog.Level
+		expected bool
+	}{
+		"root-level-trace": {level: hclog.Trace, expected: true},
+		"root-level-debug": {level: hclog.Debug, expected: true},
+		"root-level-info":  {level: hclog.Info, expected: false},
+		"root-level-warn":  {level: hclog.Warn, expected: false},
+		"root-level-error": {level: hclog.Error, expected: false},
+	}
+
+	for name, testCase := range testCases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var outputBuffer bytes.Buffer
+
+			ctx := context.Background()
+			ctx = loggertest.ProviderRootWithLevel(ctx, &outputBuffer, testCase.level)
+
+			got := tflog.IsDebug(ctx)
+
+			if got != testCase.expected {
+				t.Errorf("expected %v, got %v", testCase.expected, got)
+			}
+		})
+	}
+
+	t.Run("no-logger", func(t *testing.T) {
+		t.Parallel()
+
+		if got := tflog.IsDebug(context.Background()); got != false {
+			t.Errorf("expected false with no logger in context, got %v", got)
+		}
+	})
+}
+
+func TestIsInfo(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		level    hclog.Level
+		expected bool
+	}{
+		"root-level-trace": {level: hclog.Trace, expected: true},
+		"root-level-debug": {level: hclog.Debug, expected: true},
+		"root-level-info":  {level: hclog.Info, expected: true},
+		"root-level-warn":  {level: hclog.Warn, expected: false},
+		"root-level-error": {level: hclog.Error, expected: false},
+	}
+
+	for name, testCase := range testCases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var outputBuffer bytes.Buffer
+
+			ctx := context.Background()
+			ctx = loggertest.ProviderRootWithLevel(ctx, &outputBuffer, testCase.level)
+
+			got := tflog.IsInfo(ctx)
+
+			if got != testCase.expected {
+				t.Errorf("expected %v, got %v", testCase.expected, got)
+			}
+		})
+	}
+
+	t.Run("no-logger", func(t *testing.T) {
+		t.Parallel()
+
+		if got := tflog.IsInfo(context.Background()); got != false {
+			t.Errorf("expected false with no logger in context, got %v", got)
+		}
+	})
+}
+
+func TestIsWarn(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		level    hclog.Level
+		expected bool
+	}{
+		"root-level-trace": {level: hclog.Trace, expected: true},
+		"root-level-debug": {level: hclog.Debug, expected: true},
+		"root-level-info":  {level: hclog.Info, expected: true},
+		"root-level-warn":  {level: hclog.Warn, expected: true},
+		"root-level-error": {level: hclog.Error, expected: false},
+	}
+
+	for name, testCase := range testCases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var outputBuffer bytes.Buffer
+
+			ctx := context.Background()
+			ctx = loggertest.ProviderRootWithLevel(ctx, &outputBuffer, testCase.level)
+
+			got := tflog.IsWarn(ctx)
+
+			if got != testCase.expected {
+				t.Errorf("expected %v, got %v", testCase.expected, got)
+			}
+		})
+	}
+
+	t.Run("no-logger", func(t *testing.T) {
+		t.Parallel()
+
+		if got := tflog.IsWarn(context.Background()); got != false {
+			t.Errorf("expected false with no logger in context, got %v", got)
+		}
+	})
+}
+
+func TestIsError(t *testing.T) {
+	t.Parallel()
+
+	testCases := map[string]struct {
+		level    hclog.Level
+		expected bool
+	}{
+		"root-level-trace": {level: hclog.Trace, expected: true},
+		"root-level-debug": {level: hclog.Debug, expected: true},
+		"root-level-info":  {level: hclog.Info, expected: true},
+		"root-level-warn":  {level: hclog.Warn, expected: true},
+		"root-level-error": {level: hclog.Error, expected: true},
+	}
+
+	for name, testCase := range testCases {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+
+			var outputBuffer bytes.Buffer
+
+			ctx := context.Background()
+			ctx = loggertest.ProviderRootWithLevel(ctx, &outputBuffer, testCase.level)
+
+			got := tflog.IsError(ctx)
+
+			if got != testCase.expected {
+				t.Errorf("expected %v, got %v", testCase.expected, got)
+			}
+		})
+	}
+
+	t.Run("no-logger", func(t *testing.T) {
+		t.Parallel()
+
+		if got := tflog.IsError(context.Background()); got != false {
+			t.Errorf("expected false with no logger in context, got %v", got)
+		}
+	})
+}

tflog/subsystem.go

@@ -219,6 +219,51 @@ func SubsystemError(ctx context.Context, subsystem, msg string, additionalFields
 	logger.Error(msg, additionalArgs...)
 }
 
+// SubsystemIsTrace returns true if the subsystem logger in ctx would emit a trace-level log.
+func SubsystemIsTrace(ctx context.Context, subsystem string) bool {
+	logger := logging.GetProviderSubsystemLogger(ctx, subsystem)
+	if logger == nil {
+		return false
+	}
+	return logger.IsTrace()
+}
+
+// SubsystemIsDebug returns true if the subsystem logger in ctx would emit a debug-level log.
+func SubsystemIsDebug(ctx context.Context, subsystem string) bool {
+	logger := logging.GetProviderSubsystemLogger(ctx, subsystem)
+	if logger == nil {
+		return false
+	}
+	return logger.IsDebug()
+}
+
+// SubsystemIsInfo returns true if the subsystem logger in ctx would emit an info-level log.
+func SubsystemIsInfo(ctx context.Context, subsystem string) bool {
+	logger := logging.GetProviderSubsystemLogger(ctx, subsystem)
+	if logger == nil {
+		return false
+	}
+	return logger.IsInfo()
+}
+
+// SubsystemIsWarn returns true if the subsystem logger in ctx would emit a warn-level log.
+func SubsystemIsWarn(ctx context.Context, subsystem string) bool {
+	logger := logging.GetProviderSubsystemLogger(ctx, subsystem)
+	if logger == nil {
+		return false
+	}
+	return logger.IsWarn()
+}
+
+// SubsystemIsError returns true if the subsystem logger in ctx would emit an error-level log.
+func SubsystemIsError(ctx context.Context, subsystem string) bool {
+	logger := logging.GetProviderSubsystemLogger(ctx, subsystem)
+	if logger == nil {
+		return false
+	}
+	return logger.IsError()
+}
+
 // SubsystemOmitLogWithFieldKeys returns a new context.Context that has a modified logger
 // that will omit to write any log when any of the given keys is found
 // within its fields.