logging

Documentation

Index

• Constants
• Variables
• func CurrentLogLevel() string
• func Indent(s string) string
• func IsDebugOrHigher() bool
• func LogOutput() (logOutput io.Writer, err error)
• func NewTransport(name string, t http.RoundTripper) *transport
• func SetOutput()
• type LevelFilter
  • func (f *LevelFilter) Check(line []byte) bool
  • func (f *LevelFilter) SetMinLevel(min LogLevel)
  • func (f *LevelFilter) Write(p []byte) (n int, err error)
• type LogLevel

Constants

const (
	EnvLog     = "TF_LOG"      // Set to True
	EnvLogFile = "TF_LOG_PATH" // Set to a file
)

These are the environmental variables that determine if we log, and if we log whether or not the log should go to a file.

Variables

var ValidLevels = []LogLevel{"TRACE", "DEBUG", "INFO", "WARN", "ERROR"}

ValidLevels are the log level names that Terraform recognizes.

Functions

func CurrentLogLevel

func CurrentLogLevel() string

CurrentLogLevel returns the current log level string based the environment vars

func Indent

func Indent(s string) string

Indent adds two spaces to the beginning of each line of the given string, with the goal of making the log level filter understand it as a line continuation rather than possibly as new log lines.

func IsDebugOrHigher

func IsDebugOrHigher() bool

IsDebugOrHigher returns whether or not the current log level is debug or trace

func LogOutput

func LogOutput() (logOutput io.Writer, err error)

LogOutput determines where we should send logs (if anywhere) and the log level.

func NewTransport

func NewTransport(name string, t http.RoundTripper) *transport

func SetOutput

func SetOutput()

SetOutput checks for a log destination with LogOutput, and calls log.SetOutput with the result. If LogOutput returns nil, SetOutput uses ioutil.Discard. Any error from LogOutout is fatal.

Types

type LevelFilter

type LevelFilter struct {
	// Levels is the list of log levels, in increasing order of
	// severity. Example might be: {"DEBUG", "WARN", "ERROR"}.
	Levels []LogLevel

	// MinLevel is the minimum level allowed through
	MinLevel LogLevel

	// The underlying io.Writer where log messages that pass the filter
	// will be set.
	Writer io.Writer
	// contains filtered or unexported fields
}

LevelFilter is an io.Writer that can be used with a logger that will attempt to filter out log messages that aren't at least a certain level.

This filtering is HEURISTIC-BASED, and so will not be 100% reliable. The assumptions it makes are:

• Individual log messages are never split across multiple calls to the Write method.

• Messages that carry levels are marked by a sequence starting with "[", then the level name string, and then "]". Any message without a sequence like this is an un-levelled message, and is not subject to filtering.

• Each \n-delimited line in a write is a separate log message, unless a line starts with at least one space in which case it is interpreted as a continuation of the previous line.

• If a log line starts with a non-whitespace character that isn't a digit then it's recognized as a degenerate continuation, because "real" log lines should start with a date/time and thus always have a leading digit. (This also cleans up after some situations where the assumptuion that messages arrive atomically aren't met, which is sadly sometimes true for longer messages that trip over some buffering behavior in panicwrap.)

Because logging is a cross-cutting concern and not fully under the control of Terraform itself, there will certainly be cases where the above heuristics will fail. For example, it is likely that LevelFilter will occasionally misinterpret a continuation line as a new message because the code generating it doesn't know about our indentation convention.

Our goal here is just to make a best effort to reduce the log volume, accepting that the results will not be 100% correct.

Logging calls within Terraform Core should follow the above conventions so that the log output is broadly correct, however.

Once the filter is in use somewhere, it is not safe to modify the structure.

func (*LevelFilter) Check

func (f *LevelFilter) Check(line []byte) bool

Check will check a given line if it would be included in the level filter.

func (*LevelFilter) SetMinLevel

func (f *LevelFilter) SetMinLevel(min LogLevel)

SetMinLevel is used to update the minimum log level

func (*LevelFilter) Write

func (f *LevelFilter) Write(p []byte) (n int, err error)

Write is a specialized implementation of io.Writer suitable for being the output of a logger from the "log" package.

This Writer implementation assumes that it will only recieve byte slices containing one or more entire lines of log output, each one terminated by a newline. This is compatible with the behavior of the "log" package directly, and is also tolerant of intermediaries that might buffer multiple separate writes together, as long as no individual log line is ever split into multiple slices.

Behavior is undefined if any log line is split across multiple writes or written without a trailing '\n' delimiter.

type LogLevel

type LogLevel string

LogLevel is a special string, conventionally written all in uppercase, that can be used to mark a log line for filtering and to specify filtering levels in the LevelFilter type.