logging

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 31, 2023 License: MPL-2.0 Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	// DefaultProviderRootLoggerName is the default provider root logger name.
	DefaultProviderRootLoggerName string = "provider"

	// DefaultSDKRootLoggerName is the default SDK root logger name.
	DefaultSDKRootLoggerName string = "sdk"
)
View Source 
const (
	// ProviderRootLoggerKey is the loggerKey that will hold the root
	// logger for writing logs from within provider code.
	ProviderRootLoggerKey loggerKey = "provider"

	// ProviderRootLoggerOptionsKey is the loggerKey that will hold the root
	// logger options when the root provider logger is created. This is to
	// assist creating subsystem loggers, as most options cannot be fetched and
	// a logger does not provide set methods for these options.
	ProviderRootLoggerOptionsKey loggerKey = "provider-options"

	// SDKRootLoggerKey is the loggerKey that will hold the root logger for
	// writing logs from with SDKs.
	SDKRootLoggerKey loggerKey = "sdk"

	// SDKRootLoggerOptionsKey is the loggerKey that will hold the root
	// logger options when the SDK provider logger is created. This is to
	// assist creating subsystem loggers, as most options cannot be fetched and
	// a logger does not provide set methods for these options.
	SDKRootLoggerOptionsKey loggerKey = "sdk-options"

	// SinkKey is the loggerKey that will hold the logging sink used for
	// test frameworks.
	SinkKey loggerKey = ""

	// SinkOptionsKey is the loggerKey that will hold the sink
	// logger options when the SDK provider logger is created. This is to
	// assist creating subsystem loggers, as most options cannot be fetched and
	// a logger does not provide set methods for these options.
	SinkOptionsKey loggerKey = "sink-options"

	// TFLoggerOpts is the loggerKey that will hold the LoggerOpts associated
	// with the provider root logger (at `provider.tf-logger-opts`), and the
	// provider sub-system logger (at `provider.SUBSYSTEM.tf-logger-opts`),
	// in the context.Context.
	// Note that only some LoggerOpts require to be stored this way,
	// while others use the underlying *hclog.LoggerOptions of hclog.Logger.
	TFLoggerOpts loggerKey = "tf-logger-opts"
)
View Source 
const NewProviderSubsystemLoggerWarning = "" /* 147-byte string literal not displayed */

NewProviderSubsystemLoggerWarning is the text included in log output when a subsystem is auto-generated by terraform-plugin-log because it was used before the provider instantiated it.

View Source 
const NewSDKSubsystemLoggerWarning = "" /* 152-byte string literal not displayed */

NewSDKSubsystemLoggerWarning is the text included in log output when a subsystem is auto-generated by terraform-plugin-log because it was used before the SDK instantiated it.

Variables

View Source 
var (
	// Stderr caches the original os.Stderr when the process is started.
	//
	// When go-plugin.Serve is called, it overwrites our os.Stderr with a
	// gRPC stream which Terraform ignores. This tends to be before our
	// loggers get set up, as go-plugin has no way to pass in a base
	// context, and our loggers are passed around via contexts. This leaves
	// our loggers writing to an output that is never read by anything,
	// meaning the logs get blackholed. This isn't ideal, for log output,
	// so this is our workaround: we copy stderr on init, before Serve can
	// be called, and offer an option to write to that instead of the
	// os.Stderr available at runtime.
	//
	// Ideally, this is a short-term fix until Terraform starts reading
	// from go-plugin's gRPC-streamed stderr channel, but for the moment it
	// works.
	Stderr io.Writer
)

Functions

func GetProviderRootLogger 

func GetProviderRootLogger(ctx context.Context) hclog.Logger

GetProviderRootLogger returns the root logger used for writing logs from a provider. If no root logger has been created, it will return nil.

func GetProviderRootLoggerOptions added in v0.3.0 

func GetProviderRootLoggerOptions(ctx context.Context) *hclog.LoggerOptions

GetProviderRootLoggerOptions returns the root logger options used for creating the root provider logger. If the root logger has not been created or the options are not present, it will return nil.

func GetProviderSubsystemLogger 

func GetProviderSubsystemLogger(ctx context.Context, subsystem string) hclog.Logger

GetProviderSubsystemLogger returns the subsystem logger for the named subsystem in provider space. If no such subsystem logger has been created, it will return nil.

func GetSDKRootLogger 

func GetSDKRootLogger(ctx context.Context) hclog.Logger

GetSDKRootLogger returns the root logger used for writing logs from an SDK. If no root logger has been created, it will return nil.

func GetSDKRootLoggerOptions added in v0.3.0 

func GetSDKRootLoggerOptions(ctx context.Context) *hclog.LoggerOptions

GetSDKRootLoggerOptions returns the root logger options used for creating the root SDK logger. If the root logger has not been created or the options are not present, it will return nil.

func GetSDKSubsystemLogger 

func GetSDKSubsystemLogger(ctx context.Context, subsystem string) hclog.Logger

GetSDKSubsystemLogger returns the subsystem logger for the named subsystem in SDK space. If no such subsystem logger has been created, it will return nil.

func GetSink added in v0.4.0 

func GetSink(ctx context.Context) hclog.Logger

GetSink returns the sink logger used for writing logs. If no sink logger has been created, it will return nil.

func GetSinkOptions added in v0.4.0 

func GetSinkOptions(ctx context.Context) *hclog.LoggerOptions

GetSinkOptions returns the root logger options used for creating the root SDK logger. If the root logger has not been created or the options are not present, it will return nil.

func OmitOrMask added in v0.6.0 

func OmitOrMask(tfLoggerOpts LoggerOpts, msg *string, additionalFields []map[string]interface{}) ([]interface{}, bool)

func SetProviderRootLogger 

func SetProviderRootLogger(ctx context.Context, logger hclog.Logger) context.Context

SetProviderRootLogger sets `logger` as the root logger used for writing logs from a provider.

func SetProviderRootLoggerOptions added in v0.3.0 

func SetProviderRootLoggerOptions(ctx context.Context, loggerOptions *hclog.LoggerOptions) context.Context

SetProviderRootLoggerOptions sets `loggerOptions` as the root logger options used for creating the provider root logger.

func SetProviderRootTFLoggerOpts added in v0.5.0 

func SetProviderRootTFLoggerOpts(ctx context.Context, lOpts LoggerOpts) context.Context

SetProviderRootTFLoggerOpts sets the LoggerOpts of the provider root logger, in the context.

func SetProviderSubsystemLogger 

func SetProviderSubsystemLogger(ctx context.Context, subsystem string, logger hclog.Logger) context.Context

SetProviderSubsystemLogger sets `logger` as the logger for the named subsystem in provider space.

func SetProviderSubsystemTFLoggerOpts added in v0.5.0 

func SetProviderSubsystemTFLoggerOpts(ctx context.Context, subsystem string, lOpts LoggerOpts) context.Context

SetProviderSubsystemTFLoggerOpts sets the LoggerOpts of the logger for the named provider subsystem, in the context.

func SetSDKRootLogger 

func SetSDKRootLogger(ctx context.Context, logger hclog.Logger) context.Context

SetSDKRootLogger sets `logger` as the root logger used for writing logs from an SDK.

func SetSDKRootLoggerOptions added in v0.3.0 

func SetSDKRootLoggerOptions(ctx context.Context, loggerOptions *hclog.LoggerOptions) context.Context

SetSDKRootLoggerOptions sets `loggerOptions` as the root logger options used for creating the SDK root logger.

func SetSDKRootTFLoggerOpts added in v0.5.0 

func SetSDKRootTFLoggerOpts(ctx context.Context, lOpts LoggerOpts) context.Context

SetSDKRootTFLoggerOpts sets the LoggerOpts of the SDK root logger, in the context.

func SetSDKSubsystemLogger 

func SetSDKSubsystemLogger(ctx context.Context, subsystem string, logger hclog.Logger) context.Context

SetSDKSubsystemLogger sets `logger` as the logger for the named subsystem in SDK space.

func SetSDKSubsystemTFLoggerOpts added in v0.5.0 

func SetSDKSubsystemTFLoggerOpts(ctx context.Context, subsystem string, lOpts LoggerOpts) context.Context

SetSDKSubsystemTFLoggerOpts sets the LoggerOpts of the logger for the named SDK subsystem, in the context.

func SetSink added in v0.4.0 

func SetSink(ctx context.Context, logger hclog.Logger) context.Context

SetSink sets `logger` as the sink logger used for writing logs.

func SetSinkOptions added in v0.4.0 

func SetSinkOptions(ctx context.Context, loggerOptions *hclog.LoggerOptions) context.Context

SetSinkOptions sets `loggerOptions` as the root logger options used for creating the SDK root logger.

Types

type LoggerOpts 

type LoggerOpts struct {
	// Name is the name or "@module" of a logger.
	Name string

	// Level is the most verbose level that a logger will write logs for.
	Level hclog.Level

	// IncludeLocation indicates whether logs should include the location
	// of the logging statement or not.
	IncludeLocation bool

	// AdditionalLocationOffset is the number of additional stack levels to
	// skip when finding the file and line information for the log line.
	// Defaults to 1 to account for the tflog and tfsdklog logging functions.
	AdditionalLocationOffset int

	// Output dictates where logs are written to. Output should only ever
	// be set by tflog or tfsdklog, never by SDK authors or provider
	// developers. Where logs get written to is complex and delicate and
	// requires a deep understanding of Terraform's architecture, and it's
	// easy to mess up on accident.
	Output io.Writer

	// IncludeTime indicates whether logs should include the time they were
	// written or not. It should only be set to true when testing tflog or
	// tfsdklog; providers and SDKs should always include the time logs
	// were written as part of the log.
	IncludeTime bool

	// Fields indicates the key/value pairs to be added to each of its log output.
	Fields map[string]interface{}

	// IncludeRootFields indicates whether a new subsystem logger should
	// copy existing fields from the root logger. This is only performed
	// at the time of new subsystem creation.
	IncludeRootFields bool

	// OmitLogWithFieldKeys indicates that the logger should omit to write
	// any log when any of the given keys is found within the fields.
	//
	// Example:
	//
	//   OmitLogWithFieldKeys = `['foo', 'baz']`
	//
	//   log1 = `{ msg = "...", fields = { 'foo': '...', 'bar': '...' }`  -> omitted
	//   log2 = `{ msg = "...", fields = { 'bar': '...' }`                -> printed
	//   log3 = `{ msg = "...", fields = { 'baz': '...', 'boo': '...' }`  -> omitted
	//
	OmitLogWithFieldKeys []string

	// OmitLogWithMessageRegexes indicates that the logger should omit to write
	// any log that matches any of the given *regexp.Regexp.
	//
	// Example:
	//
	//   OmitLogWithMessageRegexes = `[regexp.MustCompile("(foo|bar)")]`
	//
	//   log1 = `{ msg = "banana apple foo", fields = {...}`     -> omitted
	//   log2 = `{ msg = "pineapple mango", fields = {...}`      -> printed
	//   log3 = `{ msg = "pineapple mango bar", fields = {...}`  -> omitted
	//
	OmitLogWithMessageRegexes []*regexp.Regexp

	// OmitLogWithMessageStrings indicates that the logger should omit to write
	// any log that matches any of the given string.
	//
	// Example:
	//
	//   OmitLogWithMessageStrings = `['foo', 'bar']`
	//
	//   log1 = `{ msg = "banana apple foo", fields = {...}`     -> omitted
	//   log2 = `{ msg = "pineapple mango", fields = {...}`      -> printed
	//   log3 = `{ msg = "pineapple mango bar", fields = {...}`  -> omitted
	//
	OmitLogWithMessageStrings []string

	// MaskFieldValuesWithFieldKeys indicates that the logger should mask with asterisks (`*`)
	// any field value where the key matches one of the given keys.
	//
	// Example:
	//
	//   MaskFieldValuesWithFieldKeys = `['foo', 'baz']`
	//
	//   log1 = `{ msg = "...", fields = { 'foo': '***', 'bar': '...' }`  -> masked value
	//   log2 = `{ msg = "...", fields = { 'bar': '...' }`                -> as-is value
	//   log3 = `{ msg = "...", fields = { 'baz': '***', 'boo': '...' }`  -> masked value
	//
	MaskFieldValuesWithFieldKeys []string

	// MaskAllFieldValuesRegexes indicates that the logger should replace, within
	// all the log field values, the portion matching one of the given *regexp.Regexp.
	//
	// Note that the replacement will happen, only for field values that are of type string.
	//
	// Example:
	//
	//   MaskAllFieldValuesRegexes = `[regexp.MustCompile("(foo|bar)")]`
	//
	//   log1 = `{ msg = "...", fields = { 'k1': '***', 'k2': '***', 'k3': 'baz' }`  -> masked value
	//   log2 = `{ msg = "...", fields = { 'k1': 'boo', 'k2': 'far', 'k3': 'baz' }`  -> as-is value
	//   log2 = `{ msg = "...", fields = { 'k1': '*** *** baz' }`                    -> masked value
	//
	MaskAllFieldValuesRegexes []*regexp.Regexp

	// MaskAllFieldValuesStrings indicates that the logger should replace, within
	// all the log field values, the portion equal to one of the given strings.
	//
	// Note that the replacement will happen, only for field values that are of type string.
	//
	// Example:
	//
	//   MaskAllFieldValuesStrings = `['foo', 'baz']`
	//
	//   log1 = `{ msg = "...", fields = { 'k1': '***', 'k2': 'bar', 'k3': '***' }`  -> masked value
	//   log2 = `{ msg = "...", fields = { 'k1': 'boo', 'k2': 'far', 'k3': '***' }`  -> as-is value
	//   log2 = `{ msg = "...", fields = { 'k1': '*** bar ***' }`                    -> masked value
	MaskAllFieldValuesStrings []string

	// MaskMessageRegexes indicates that the logger should replace, within
	// a log message, the portion matching one of the given *regexp.Regexp.
	//
	// Example:
	//
	//   MaskMessageRegexes = `[regexp.MustCompile("(foo|bar)")]`
	//
	//   log1 = `{ msg = "banana apple ***", fields = {...}`     -> masked portion
	//   log2 = `{ msg = "pineapple mango", fields = {...}`      -> as-is
	//   log3 = `{ msg = "pineapple mango ***", fields = {...}`  -> masked portion
	//
	MaskMessageRegexes []*regexp.Regexp

	// MaskMessageStrings indicates that the logger should replace, within
	// a log message, the portion equal to one of the given strings.
	//
	// Example:
	//
	//   MaskMessageStrings = `['foo', 'bar']`
	//
	//   log1 = `{ msg = "banana apple ***", fields = {...}`     -> masked portion
	//   log2 = `{ msg = "pineapple mango", fields = {...}`      -> as-is
	//   log3 = `{ msg = "pineapple mango ***", fields = {...}`  -> masked portion
	//
	MaskMessageStrings []string
}

LoggerOpts is a collection of configuration settings for loggers.

func ApplyLoggerOpts 

func ApplyLoggerOpts(opts ...Option) LoggerOpts

ApplyLoggerOpts generates a LoggerOpts out of a list of Option implementations. By default, AdditionalLocationOffset is 1, IncludeLocation is true, IncludeTime is true, and Output is os.Stderr.

func GetProviderRootTFLoggerOpts added in v0.5.0 

func GetProviderRootTFLoggerOpts(ctx context.Context) LoggerOpts

GetProviderRootTFLoggerOpts retrieves the LoggerOpts of the provider root logger. The value is stored in the context.Context: if none is found, a new one will be created.

func GetProviderSubsystemTFLoggerOpts added in v0.5.0 

func GetProviderSubsystemTFLoggerOpts(ctx context.Context, subsystem string) LoggerOpts

GetProviderSubsystemTFLoggerOpts retrieves the LoggerOpts of the logger for the named provider subsystem. The value is stored in the context.Context: if none is found, a new one will be created.

func GetSDKRootTFLoggerOpts added in v0.5.0 

func GetSDKRootTFLoggerOpts(ctx context.Context) LoggerOpts

GetSDKRootTFLoggerOpts retrieves the LoggerOpts of the SDK root logger. The value is stored in the context.Context: if none is found, a new one will be created.

func GetSDKSubsystemTFLoggerOpts added in v0.5.0 

func GetSDKSubsystemTFLoggerOpts(ctx context.Context, subsystem string) LoggerOpts

GetSDKSubsystemTFLoggerOpts retrieves the LoggerOpts of the logger for the named SDK subsystem. The value is stored in the context.Context: if none is found, a new one will be created.

func (LoggerOpts) ApplyMask added in v0.5.0 

func (lo LoggerOpts) ApplyMask(msg *string, fieldMaps ...map[string]interface{})

ApplyMask takes a log's *string message and slices of fields, and applies masking to fields keys' values and/or to log message, based on the LoggerOpts configuration.

Note that the given input is changed-in-place by this method.

func (LoggerOpts) Copy added in v0.8.0 

func (o LoggerOpts) Copy() LoggerOpts

Copy creates a duplicate LoggerOpts. This should be used to ensure safe LoggerOpts modification when the LoggerOpts could be saved into a new context.Context.

func (LoggerOpts) ShouldOmit added in v0.5.0 

func (lo LoggerOpts) ShouldOmit(msg *string, fieldMaps ...map[string]interface{}) bool

ShouldOmit takes a log's *string message and slices of fields, and determines, based on the LoggerOpts configuration, if the log should be omitted (i.e. prevent it to be printed on the final writer).

type Option 

type Option func(LoggerOpts) LoggerOpts

Option defines a modification to the configuration for a logger.

func WithAdditionalLocationOffset added in v0.3.0 

func WithAdditionalLocationOffset(additionalLocationOffset int) Option

WithAdditionalLocationOffset sets the WithAdditionalLocationOffset configuration option, allowing implementations to fix location information when implementing helper functions. The default offset of 1 is automatically added to the provided value to account for the tflog and tfsdk logging functions.

func WithField added in v0.6.0 

func WithField(key string, value interface{}) Option

WithField sets the provided key/value pair, onto the LoggerOpts.Fields field.

Behind the scene, fields are stored in a map[string]interface{}: this means that in case the same key is used multiple times (key collision), the last one set is the one that gets persisted and then outputted with the logs.

func WithFields added in v0.6.0 

func WithFields(fields map[string]interface{}) Option

WithFields sets all the provided key/value pairs, onto the LoggerOpts.Fields field.

Behind the scene, fields are stored in a map[string]interface{}: this means that in case the same key is used multiple times (key collision), the last one set is the one that gets persisted and then outputted with the logs.

func WithMaskAllFieldValuesRegexes added in v0.7.0 

func WithMaskAllFieldValuesRegexes(expressions ...*regexp.Regexp) Option

WithMaskAllFieldValuesRegexes appends keys to the LoggerOpts.MaskAllFieldValuesRegexes field.

func WithMaskAllFieldValuesStrings added in v0.7.0 

func WithMaskAllFieldValuesStrings(matchingStrings ...string) Option

WithMaskAllFieldValuesStrings appends keys to the LoggerOpts.MaskAllFieldValuesStrings field.

func WithMaskFieldValuesWithFieldKeys added in v0.6.0 

func WithMaskFieldValuesWithFieldKeys(keys ...string) Option

WithMaskFieldValuesWithFieldKeys appends keys to the LoggerOpts.MaskFieldValuesWithFieldKeys field.

func WithMaskMessageRegexes added in v0.6.0 

func WithMaskMessageRegexes(expressions ...*regexp.Regexp) Option

WithMaskMessageRegexes appends *regexp.Regexp to the LoggerOpts.MaskMessageRegexes field.

func WithMaskMessageStrings added in v0.5.0 

func WithMaskMessageStrings(matchingStrings ...string) Option

WithMaskMessageStrings appends string to the LoggerOpts.MaskMessageStrings field.

func WithOmitLogWithFieldKeys added in v0.5.0 

func WithOmitLogWithFieldKeys(keys ...string) Option

WithOmitLogWithFieldKeys appends keys to the LoggerOpts.OmitLogWithFieldKeys field.

func WithOmitLogWithMessageRegexes added in v0.6.0 

func WithOmitLogWithMessageRegexes(expressions ...*regexp.Regexp) Option

WithOmitLogWithMessageRegexes appends *regexp.Regexp to the LoggerOpts.OmitLogWithMessageRegexes field.

func WithOmitLogWithMessageStrings added in v0.5.0 

func WithOmitLogWithMessageStrings(matchingStrings ...string) Option

WithOmitLogWithMessageStrings appends string to the LoggerOpts.OmitLogWithMessageStrings field.

func WithOutput 

func WithOutput(output io.Writer) Option

WithOutput sets the Output configuration option, controlling where logs get written to. This is mostly used for testing (to write to os.Stdout, so the test framework can compare it against the example output) and as a helper when implementing safe, specific output strategies in tfsdklog.

func WithRootFields added in v0.4.0 

func WithRootFields() Option

WithRootFields enables the copying of root logger fields to a new subsystem logger during creation.

func WithoutLocation added in v0.3.0 

func WithoutLocation() Option

WithoutLocation disables the location included with logging statements. It should only ever be used to make log output deterministic when testing terraform-plugin-log.

func WithoutTimestamp 

func WithoutTimestamp() Option

WithoutTimestamp disables the timestamp included with logging statements. It should only ever be used to make log output deterministic when testing terraform-plugin-log.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.