Go Reference

import "github.com/bruceesmith/logger"

Package logger supports logging and tracing based on the standard library package log/slog.

Standard log/slog functions Debug, DebugContext, Error, ErrorContext, Info, InfoContext, Warn and WarnContext can be called as normal however their output format and destination are configurable using the Configure function.

A custom logging level LevelTrace, and an independent Logger, are provided to enable tracing. Tracing can be unconditional when calling Trace / TraceContext, or only enabled for pre-defined identifiers when calling TraceID / TraceIDContext. Identifiers for the trace functions are registered by calling SetTraceIds.

logger supports an ErrorID feature when using the log/slog Context methods, where a string value is set in the supplied context.Context with the key ErrorIDKey. If ErrorID is enabled via Configure, and one of the Context functions is called with a context.Context containing ErrorIDKey, then the resulting log record contains an "error_id" field with the Value from the context.Context.

Configure manages the destination and format of the log records

• the format of log records (JSON or Text),
• their destination (by default normal logs go to Stdout and traces go to Stderr),
• whether context.Context values contain error IDs,
• whether each record contains a timestamp.

When used in cli applications, a cli.Flag representing a LogLevel can be provided using the LogLevelFlag type.

• Constants
• func Configure(setting ...ConfigSetting) error
• func Debug(msg string, args ...any)
• func Error(msg string, args ...any)
• func Info(msg string, args ...any)
• func Level() string
• func RedirectStandard(w io.Writer)
• func RedirectTrace(w io.Writer)
• func SetFormat(f Format)
• func SetLevel(l slog.Level)
• func SetTraceIds(ids ...string)
• func Trace(msg string, args ...any)
• func TraceContext(ctx context.Context, msg string, args ...any)
• func TraceID(id string, msg string, args ...any)
• func TraceIDContext(ctx context.Context, id string, msg string, args ...any)
• func TraceIDs() []string
• func Warn(msg string, args ...any)
• type ConfigSetting
• type ErrorIDKeyType
• type Format
• type LogID
  • func (i LogID) String() string
• type LogLevel
  • func (ll *LogLevel) Set(ls string) (err error)
  • func (ll *LogLevel) String() (s string)
  • func (ll *LogLevel) Type() string
  • func (ll *LogLevel) UnmarshalJSON(jason []byte) (err error)
• type LogLevelFlag
• type SettingKey
  • func (i SettingKey) String() string
• type Traces
  • func (t *Traces) Set(ts string) (err error)
  • func (t *Traces) String() (s string)
  • func (t *Traces) Type() string

const (
 // LevelTrace can be set to enable tracing
 LevelTrace slog.Level = -10
)

func Configure(setting ...ConfigSetting) error

Configure sets or changes attributes of either the normal or trace loggers

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

Debug emits a debug log

Deprecated: Use slog.Debug instead

func Error(msg string, args ...any)

Error emits an error log

Deprecated: Use slog.Error instead

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

Info emits an info log

Deprecated: Use slog.Info instead

func Level() string

Level returns the current logging level as a string

func RedirectStandard(w io.Writer)

RedirectStandard changes the destination for normal (non-trace) logsDestinationSetting argument

Deprecated: RedirectStandard() should be replaced by a call to Configure() with a DestinationSetting argument

func RedirectTrace(w io.Writer)

RedirectTrace changes the destination for normal (non-trace) logs

Deprecated: RedirectTrace() should be replaced by a call to Configure() with a DestinationSetting argument

func SetFormat(f Format)

SetFormat changes the format of log entries

Deprecated: SetFormat() should be replaced by calls to Configure() with a FormatSetting argument. An advantage of Configure() is that the format of the standard logger can be configured differently to that of the Trace logger

func SetLevel(l slog.Level)

SetLevel sets the default level of logging

func SetTraceIds(ids ...string)

SetTraceIds registers identifiers for future tracing

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

Trace emits one log entry if trace level logging is enabled

func TraceContext(ctx context.Context, msg string, args ...any)

TraceContext emits a trace log and if ErrorIDs is configured, and ErrorIDKey is set in ctx, then the log will also have an "error_id" segment

func TraceID(id string, msg string, args ...any)

TraceID emits one JSON-formatted log entry if tracing is enabled for the requested ID

func TraceIDContext(ctx context.Context, id string, msg string, args ...any)

TraceIDContext emits one JSON-formatted log entry if tracing is enabled for the requested ID and if ErrorID is configured, and ErrorIDKey is set in ctx, then the log will also have an "error_id" segment

func TraceIDs() []string

TraceIDs returns the list of enabled trace IDs

func Warn(msg string, args ...any)

Warn emits a warning log

Deprecated: Use slog.Warn instead

ConfigSetting is an argument to Configure()

type ConfigSetting struct {
 AppliesTo LogID // Logger whose setting is set/changed
 Key SettingKey // Attribute of the logger that is set/changed
 Value any // New value for this attribute
}

ErrorIDKeyType is the key type for the Context Value containing an error ID

type ErrorIDKeyType string

const (
 // When the errorID handler is configured, it will look for a context.Value
 // with this key in the context.Context passed to the ***Context() methods
 ErrorIDKey ErrorIDKeyType = "errorID"
)

Format determines the format of each log entry

type Format string

const (
 Text Format = "text" // Text format logs
 JSON Format = "json" // JSON format logs
)

LogID defines the identifier of a logger

type LogID int

const (
 Norm LogID = iota // The normal logger
 Tracy // The trace logger
)

func (i LogID) String() string

LogLevel is the level of logging

type LogLevel int

func (ll *LogLevel) Set(ls string) (err error)

Set is a convenience method for pflag.Value

func (ll *LogLevel) String() (s string)

String is a convenience method for pflag.Value

func (ll *LogLevel) Type() string

Type is a convenience method for pflag.Value

func (ll *LogLevel) UnmarshalJSON(jason []byte) (err error)

UnmarshalJSON is a convenience method for Kong

LogLevelFlag is useful for using a LogLevel as a command-line flag in CLI applications

type LogLevelFlag = cli.FlagBase[LogLevel, cli.NoConfig, logLevelValue]

SettingKey defines a logger setting that can be set or changed via the Configure function

type SettingKey int

const (
 DestinationSetting SettingKey = iota // Output writer / destination for a logger
 ErrorIDSetting // Whether to include an ErrorIDHandler
 FormatSetting // Format of log entries
 OmitTimeSetting // Whether a timestamp is included in log entries
)

func (i SettingKey) String() string

Traces is the list of trace IDs enabled

type Traces []string

func (t *Traces) Set(ts string) (err error)

Set is a convenience method for pflag.Value

func (t *Traces) String() (s string)

String is a convenience method for pflag.Value

func (t *Traces) Type() string

Type is a convenience method for pflag.Value

Generated by gomarkdoc