plog

Documentation

Overview

Package plog implements a thin layer over logr 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
• func AddZapOverridesToContext(ctx context.Context, t *testing.T, w io.Writer, f func(*zap.Config), ...) context.Context
• func All(msg string, keysAndValues ...any)
• func Always(msg string, keysAndValues ...any)
• func Debug(msg string, keysAndValues ...any)
• func DebugErr(msg string, err error, keysAndValues ...any)
• func Enabled(level LogLevel) bool
• func Error(msg string, err error, keysAndValues ...any)
• func Fatal(err error, keysAndValues ...any)
• func Info(msg string, keysAndValues ...any)
• func InfoErr(msg string, err error, keysAndValues ...any)
• func Setup() func()
• func Trace(msg string, keysAndValues ...any)
• func TraceErr(msg string, err error, keysAndValues ...any)
• func ValidateAndSetLogLevelAndFormatGlobally(ctx context.Context, spec LogSpec) error
• func Warning(msg string, keysAndValues ...any)
• func WarningErr(msg string, err error, keysAndValues ...any)
• func ZapClock(c clock.Clock) zapcore.Clock
• type AuditLogConfig
• type AuditLogger
  • func NewAuditLogger(cfg AuditLogConfig) AuditLogger
  • func TestAuditLogger(t *testing.T) (AuditLogger, *bytes.Buffer)
  • func TestAuditLoggerWithConfig(t *testing.T, cfg AuditLogConfig) (AuditLogger, *bytes.Buffer)
• type AuditParams
• type LogFormat
  • func (l *LogFormat) UnmarshalJSON(b []byte) error
• type LogLevel
  • func (l LogLevel) Enabled(_ zapcore.Level) bool
• type LogSpec
• type Logger
  • func New() Logger
  • func TestConsoleLogger(t *testing.T, w io.Writer) Logger
  • func TestLogger(t *testing.T) (Logger, *bytes.Buffer)
  • func WithName(name string) Logger
  • func WithValues(keysAndValues ...any) Logger
• type MinLogger
• type SessionIDGetter

Constants

const (
	KlogLevelInfo
	KlogLevelDebug
	KlogLevelTrace
)

Functions

func AddZapOverridesToContext

func AddZapOverridesToContext(
	ctx context.Context,
	t *testing.T,
	w io.Writer,
	f func(*zap.Config),
	fakeClock *clocktesting.FakeClock,
	opts ...zap.Option,
) context.Context

AddZapOverridesToContext adds Zap (and klog/textlogger) overrides to the context. This is done so that production code can read these values for test overrides. Do not pass zap.WithClock in opts since that will be constructed for you from fakeClock.

func All

func All(msg string, keysAndValues ...any)

func Always

func Always(msg string, keysAndValues ...any)

func Debug

func Debug(msg string, keysAndValues ...any)

func DebugErr

func DebugErr(msg string, err error, keysAndValues ...any)

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 ...any)

func Fatal

func Fatal(err error, keysAndValues ...any)

func Info

func Info(msg string, keysAndValues ...any)

func InfoErr

func InfoErr(msg string, err error, keysAndValues ...any)

func Setup

func Setup() func()

func Trace

func Trace(msg string, keysAndValues ...any)

func TraceErr

func TraceErr(msg string, err error, keysAndValues ...any)

func ValidateAndSetLogLevelAndFormatGlobally

func ValidateAndSetLogLevelAndFormatGlobally(ctx context.Context, spec LogSpec) error

func Warning

func Warning(msg string, keysAndValues ...any)

func WarningErr

func WarningErr(msg string, err error, keysAndValues ...any)

func ZapClock

func ZapClock(c clock.Clock) zapcore.Clock

Types

type AuditLogConfig

type AuditLogConfig struct {
	LogUsernamesAndGroupNames bool
}

type AuditLogger

type AuditLogger interface {
	Audit(msg auditevent.Message, p *AuditParams)
	AuditRequestParams(r *http.Request, reqParamsSafeToLog sets.Set[string]) error
}

AuditLogger is the interface for audit logging. There is no global function for Audit because that would make unit testing of audit logs harder.

func NewAuditLogger

func NewAuditLogger(cfg AuditLogConfig) AuditLogger

func TestAuditLogger

func TestAuditLogger(t *testing.T) (AuditLogger, *bytes.Buffer)

func TestAuditLoggerWithConfig

func TestAuditLoggerWithConfig(t *testing.T, cfg AuditLogConfig) (AuditLogger, *bytes.Buffer)

type AuditParams

type AuditParams struct {
	// ReqCtx may be nil. When possible, pass the http request's context as ReqCtx,
	// so we may read the audit ID from the context.
	ReqCtx context.Context

	// Session may be nil. When possible, pass the fosite.Requester or fosite.Request as the Session,
	// so we can log the session ID.
	Session SessionIDGetter

	// PIIKeysAndValues can optionally be used to pass along more keys are values.
	// Use these when the values might contain personally identifiable information (PII).
	// These values may be redacted by configuration.
	// They must come in alternating pairs of string keys and any values.
	PIIKeysAndValues []any

	// KeysAndValues can optionally be used to pass along more keys are values.
	// These values are never redacted and therefore should never contain PII.
	// They must come in alternating pairs of string keys and any values.
	KeysAndValues []any
}

type LogFormat

type LogFormat string

const (
	FormatJSON LogFormat = "json"
	FormatCLI  LogFormat = "cli" // only used by the pinniped CLI and not the server components

)

func (*LogFormat) UnmarshalJSON

func (l *LogFormat) UnmarshalJSON(b []byte) error

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

func (LogLevel) Enabled

func (l LogLevel) Enabled(_ zapcore.Level) bool

type LogSpec

type LogSpec struct {
	Level  LogLevel  `json:"level,omitempty"`
	Format LogFormat `json:"format,omitempty"`
}

type Logger

type Logger interface {
	Error(msg string, err error, keysAndValues ...any)
	Warning(msg string, keysAndValues ...any)
	WarningErr(msg string, err error, keysAndValues ...any)
	Info(msg string, keysAndValues ...any)
	InfoErr(msg string, err error, keysAndValues ...any)
	Debug(msg string, keysAndValues ...any)
	DebugErr(msg string, err error, keysAndValues ...any)
	Trace(msg string, keysAndValues ...any)
	TraceErr(msg string, err error, keysAndValues ...any)
	All(msg string, keysAndValues ...any)
	Always(msg string, keysAndValues ...any)
	WithValues(keysAndValues ...any) Logger
	WithName(name string) Logger
	// contains filtered or unexported methods
}

Logger implements the plog logging convention described above. The global functions in this package such as Info should be used when one does not intend to write tests assertions for specific log messages. If test assertions are desired, Logger should be passed in as an input. New should be used as the production implementation and TestLogger should be used to write test assertions.

func New

func New() Logger

func TestConsoleLogger

func TestConsoleLogger(t *testing.T, w io.Writer) Logger

func TestLogger

func TestLogger(t *testing.T) (Logger, *bytes.Buffer)

func WithName

func WithName(name string) Logger

func WithValues

func WithValues(keysAndValues ...any) Logger

type MinLogger

type MinLogger interface {
	Info(msg string, keysAndValues ...any)
}

MinLogger is the overlap between Logger and logr.Logger.

type SessionIDGetter

type SessionIDGetter interface {
	GetID() string
}