logging

Documentation

Index

• Constants
• Variables
• func GetProviderRootLogger(ctx context.Context) hclog.Logger
• func GetProviderRootLoggerOptions(ctx context.Context) *hclog.LoggerOptions
• func GetProviderSubsystemLogger(ctx context.Context, subsystem string) hclog.Logger
• func GetSDKRootLogger(ctx context.Context) hclog.Logger
• func GetSDKRootLoggerOptions(ctx context.Context) *hclog.LoggerOptions
• func GetSDKSubsystemLogger(ctx context.Context, subsystem string) hclog.Logger
• func GetSink(ctx context.Context) hclog.Logger
• func GetSinkOptions(ctx context.Context) *hclog.LoggerOptions
• func SetProviderRootLogger(ctx context.Context, logger hclog.Logger) context.Context
• func SetProviderRootLoggerOptions(ctx context.Context, loggerOptions *hclog.LoggerOptions) context.Context
• func SetProviderSubsystemLogger(ctx context.Context, subsystem string, logger hclog.Logger) context.Context
• func SetSDKRootLogger(ctx context.Context, logger hclog.Logger) context.Context
• func SetSDKRootLoggerOptions(ctx context.Context, loggerOptions *hclog.LoggerOptions) context.Context
• func SetSDKSubsystemLogger(ctx context.Context, subsystem string, logger hclog.Logger) context.Context
• func SetSink(ctx context.Context, logger hclog.Logger) context.Context
• func SetSinkOptions(ctx context.Context, loggerOptions *hclog.LoggerOptions) context.Context
• type LoggerOpts
  • func ApplyLoggerOpts(opts ...Option) LoggerOpts
• type Option
  • func WithAdditionalLocationOffset(additionalLocationOffset int) Option
  • func WithOutput(output io.Writer) Option
  • func WithRootFields() Option
  • func WithoutLocation() Option
  • func WithoutTimestamp() Option

Constants

const (
	// Default provider root logger name.
	DefaultProviderRootLoggerName string = "provider"

	// Default SDK root logger name.
	DefaultSDKRootLoggerName string = "sdk"
)

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"
)

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.

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

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

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

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

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

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 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

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 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 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

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 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 SetSink

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

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

func SetSinkOptions

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 incude 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

	// 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
}

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.

type Option

type Option func(LoggerOpts) LoggerOpts

Option defines a modification to the configuration for a logger.

func WithAdditionalLocationOffset

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 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

func WithRootFields() Option

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

func WithoutLocation

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.