Documentation

Overview

    Package plog implements a thin layer over klog to help enforce pinniped's logging convention. Logs are always structured as a constant message with key and value pairs of related metadata.

    The logging levels in order of increasing verbosity are: error, warning, info, debug, trace and all.

    error and warning logs are always emitted (there is no way for the end user to disable them), and thus should be used sparingly. Ideally, logs at these levels should be actionable.

    info should be reserved for "nice to know" information. It should be possible to run a production pinniped server at the info log level with no performance degradation due to high log volume. debug should be used for information targeted at developers and to aid in support cases. Care must be taken at this level to not leak any secrets into the log stream. That is, even though debug may cause performance issues in production, it must not cause security issues in production.

    trace should be used to log information related to timing (i.e. the time it took a controller to sync). Just like debug, trace should not leak secrets into the log stream. trace will likely leak information about the current state of the process, but that, along with performance degradation, is expected.

    all is reserved for the most verbose and security sensitive information. At this level, full request metadata such as headers and parameters along with the body may be logged. This level is completely unfit for production use both from a performance and security standpoint. Using it is generally an act of desperation to determine why the system is broken.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func All

    func All(msg string, keysAndValues ...interface{})

    func Debug

    func Debug(msg string, keysAndValues ...interface{})

    func DebugErr

    func DebugErr(msg string, err error, keysAndValues ...interface{})

      Use DebugErr to issue a Debug message with an error object as part of the message.

      func Enabled

      func Enabled(level LogLevel) bool

        Enabled returns whether the provided plog level is enabled, i.e., whether print statements at the provided level will show up.

        func Error

        func Error(msg string, err error, keysAndValues ...interface{})

          Use Error to log an unexpected system error.

          func Info

          func Info(msg string, keysAndValues ...interface{})

          func InfoErr

          func InfoErr(msg string, err error, keysAndValues ...interface{})

            Use InfoErr to log an expected error, e.g. validation failure of an http parameter.

            func KObj

            func KObj(obj klog.KMetadata) string

              KObj is (mostly) copied from klog - it is a standard way to represent a metav1.Object in logs.

              func KRef

              func KRef(namespace, name string) string

                KRef is (mostly) copied from klog - it is a standard way to represent a a metav1.Object in logs when you only have access to the namespace and name of the object.

                func RemoveKlogGlobalFlags

                func RemoveKlogGlobalFlags()

                  RemoveKlogGlobalFlags attempts to "remove" flags that get unconditionally added by importing klog.

                  func Trace

                  func Trace(msg string, keysAndValues ...interface{})

                  func TraceErr

                  func TraceErr(msg string, err error, keysAndValues ...interface{})

                    Use TraceErr to issue a Trace message with an error object as part of the message.

                    func ValidateAndSetLogLevelGlobally

                    func ValidateAndSetLogLevelGlobally(level LogLevel) error

                    func Warning

                    func Warning(msg string, keysAndValues ...interface{})

                    func WarningErr

                    func WarningErr(msg string, err error, keysAndValues ...interface{})

                      Use WarningErr to issue a Warning message with an error object as part of the message.

                      Types

                      type LogLevel

                      type LogLevel string

                        LogLevel is an enum that controls verbosity of logs. Valid values in order of increasing verbosity are leaving it unset, info, debug, trace and all.

                        const (
                        	// LevelWarning (i.e. leaving the log level unset) maps to klog log level 0.
                        	LevelWarning LogLevel = ""
                        	// LevelInfo maps to klog log level 2.
                        	LevelInfo LogLevel = "info"
                        	// LevelDebug maps to klog log level 4.
                        	LevelDebug LogLevel = "debug"
                        	// LevelTrace maps to klog log level 6.
                        	LevelTrace LogLevel = "trace"
                        	// LevelAll maps to klog log level 100 (conceptually it is log level 8).
                        	LevelAll LogLevel = "all"
                        )