Introduce log filtering website page and example Go documentation for…

… filtering functions (#79)

Reference: #77

tflog/provider_example_test.go

@@ -3,6 +3,7 @@ package tflog
 import (
 	"context"
 	"os"
+	"regexp"
 
 	"github.com/hashicorp/go-hclog"
 	"github.com/hashicorp/terraform-plugin-log/internal/logging"
@@ -135,3 +136,133 @@ func ExampleError() {
 	// Output:
 	// {"@level":"error","@message":"hello, world","@module":"provider","colors":["red","blue","green"],"foo":123}
 }
+
+func ExampleMaskFieldValuesWithFieldKeys() {
+	// 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
+	exampleCtx = MaskFieldValuesWithFieldKeys(exampleCtx, "field1")
+
+	// all messages logged with exampleCtx will now have field1=***
+	Trace(exampleCtx, "example log message", map[string]interface{}{
+		"field1": 123,
+		"field2": 456,
+	})
+
+	// Output:
+	// {"@level":"trace","@message":"example log message","@module":"provider","field1":"***","field2":456}
+}
+
+func ExampleMaskMessageStrings() {
+	// 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
+	exampleCtx = MaskMessageStrings(exampleCtx, "my-sensitive-data")
+
+	// all messages logged with exampleCtx will now have my-sensitive-data
+	// replaced with ***
+	Trace(exampleCtx, "example log message with my-sensitive-data masked")
+
+	// Output:
+	// {"@level":"trace","@message":"example log message with *** masked","@module":"provider"}
+}
+
+func ExampleMaskMessageRegexes() {
+	// 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
+	exampleCtx = MaskMessageRegexes(exampleCtx, regexp.MustCompile(`[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}`))
+
+	// all messages logged with exampleCtx will now have strings matching the
+	// regular expression replaced with ***
+	Trace(exampleCtx, "example log message with 1234-1234-1234-1234 masked")
+
+	// Output:
+	// {"@level":"trace","@message":"example log message with *** masked","@module":"provider"}
+}
+
+func ExampleOmitLogWithFieldKeys() {
+	// 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
+	exampleCtx = OmitLogWithFieldKeys(exampleCtx, "field1")
+
+	// all messages logged with exampleCtx and using field1 will be omitted
+	Trace(exampleCtx, "example log message", map[string]interface{}{
+		"field1": 123,
+		"field2": 456,
+	})
+
+	// Output:
+	//
+}
+
+func ExampleOmitLogWithMessageStrings() {
+	// 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
+	exampleCtx = OmitLogWithMessageStrings(exampleCtx, "my-sensitive-data")
+
+	// all messages logged with exampleCtx will now have my-sensitive-data
+	// entries omitted
+	Trace(exampleCtx, "example log message with my-sensitive-data masked")
+
+	// Output:
+	//
+}
+
+func ExampleOmitLogWithMessageRegexes() {
+	// 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
+	exampleCtx = OmitLogWithMessageRegexes(exampleCtx, regexp.MustCompile(`[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}`))
+
+	// all messages logged with exampleCtx will be omitted if they have a
+	// string matching the regular expression
+	Trace(exampleCtx, "example log message with 1234-1234-1234-1234 masked")
+
+	// Output:
+	//
+}

tflog/subsystem_example_test.go

@@ -1,6 +1,9 @@
 package tflog
 
-import "os"
+import (
+	"os"
+	"regexp"
+)
 
 func ExampleNewSubsystem() {
 	// virtually no plugin developers will need to worry about
@@ -200,3 +203,139 @@ func ExampleSubsystemError() {
 	// Output:
 	// {"@level":"error","@message":"hello, world","@module":"provider.my-subsystem","colors":["red","blue","green"],"foo":123}
 }
+
+func ExampleSubsystemMaskFieldValuesWithFieldKeys() {
+	// 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
+	exampleCtx = NewSubsystem(exampleCtx, "my-subsystem")
+	exampleCtx = SubsystemMaskFieldValuesWithFieldKeys(exampleCtx, "my-subsystem", "field1")
+
+	// all messages logged with exampleCtx will now have field1=***
+	SubsystemTrace(exampleCtx, "my-subsystem", "example log message", map[string]interface{}{
+		"field1": 123,
+		"field2": 456,
+	})
+
+	// Output:
+	// {"@level":"trace","@message":"example log message","@module":"provider.my-subsystem","field1":"***","field2":456}
+}
+
+func ExampleSubsystemMaskMessageStrings() {
+	// 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
+	exampleCtx = NewSubsystem(exampleCtx, "my-subsystem")
+	exampleCtx = SubsystemMaskMessageStrings(exampleCtx, "my-subsystem", "my-sensitive-data")
+
+	// all messages logged with exampleCtx will now have my-sensitive-data
+	// replaced with ***
+	SubsystemTrace(exampleCtx, "my-subsystem", "example log message with my-sensitive-data masked")
+
+	// Output:
+	// {"@level":"trace","@message":"example log message with *** masked","@module":"provider.my-subsystem"}
+}
+
+func ExampleSubsystemMaskMessageRegexes() {
+	// 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
+	exampleCtx = NewSubsystem(exampleCtx, "my-subsystem")
+	exampleCtx = SubsystemMaskMessageRegexes(exampleCtx, "my-subsystem", regexp.MustCompile(`[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}`))
+
+	// all messages logged with exampleCtx will now have strings matching the
+	// regular expression replaced with ***
+	SubsystemTrace(exampleCtx, "my-subsystem", "example log message with 1234-1234-1234-1234 masked")
+
+	// Output:
+	// {"@level":"trace","@message":"example log message with *** masked","@module":"provider.my-subsystem"}
+}
+
+func ExampleSubsystemOmitLogWithFieldKeys() {
+	// 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
+	exampleCtx = NewSubsystem(exampleCtx, "my-subsystem")
+	exampleCtx = SubsystemOmitLogWithFieldKeys(exampleCtx, "my-subsystem", "field1")
+
+	// all messages logged with exampleCtx and using field1 will be omitted
+	SubsystemTrace(exampleCtx, "my-subsystem", "example log message", map[string]interface{}{
+		"field1": 123,
+		"field2": 456,
+	})
+
+	// Output:
+	//
+}
+
+func ExampleSubsystemOmitLogWithMessageStrings() {
+	// 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
+	exampleCtx = NewSubsystem(exampleCtx, "my-subsystem")
+	exampleCtx = SubsystemOmitLogWithMessageStrings(exampleCtx, "my-subsystem", "my-sensitive-data")
+
+	// all messages logged with exampleCtx will now have my-sensitive-data
+	// entries omitted
+	SubsystemTrace(exampleCtx, "my-subsystem", "example log message with my-sensitive-data masked")
+
+	// Output:
+	//
+}
+
+func ExampleSubsystemOmitLogWithMessageRegexes() {
+	// 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
+	exampleCtx = NewSubsystem(exampleCtx, "my-subsystem")
+	exampleCtx = SubsystemOmitLogWithMessageRegexes(exampleCtx, "my-subsystem", regexp.MustCompile(`[0-9]{4}-[0-9]{4}-[0-9]{4}-[0-9]{4}`))
+
+	// all messages logged with exampleCtx will be omitted if they have a
+	// string matching the regular expression
+	SubsystemTrace(exampleCtx, "my-subsystem", "example log message with 1234-1234-1234-1234 masked")
+
+	// Output:
+	//
+}