logger

logger

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.

Index

• 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

Constants

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

func Configure

func Configure(setting ...ConfigSetting) error

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

func Debug

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

Debug emits a debug log

Deprecated: Use slog.Debug instead

func Error

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

Error emits an error log

Deprecated: Use slog.Error instead

func Info

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

Info emits an info log

Deprecated: Use slog.Info instead

func Level

func Level() string

Level returns the current logging level as a string

func RedirectStandard

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

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

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

func SetLevel(l slog.Level)

SetLevel sets the default level of logging

func SetTraceIds

func SetTraceIds(ids ...string)

SetTraceIds registers identifiers for future tracing

func Trace

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

Trace emits one log entry if trace level logging is enabled

func TraceContext

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

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

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

func TraceIDs() []string

TraceIDs returns the list of enabled trace IDs

func Warn

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

Warn emits a warning log

Deprecated: Use slog.Warn instead

type ConfigSetting

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
}

type ErrorIDKeyType

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

type Format

Format determines the format of each log entry

type Format string

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

type LogID

LogID defines the identifier of a logger

type LogID int

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

func (LogID) String

func (i LogID) String() string

type LogLevel

LogLevel is the level of logging

type LogLevel int

func (*LogLevel) Set

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

Set is a convenience method for pflag.Value

func (*LogLevel) String

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

String is a convenience method for pflag.Value

func (*LogLevel) Type

func (ll *LogLevel) Type() string

Type is a convenience method for pflag.Value

func (*LogLevel) UnmarshalJSON

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

UnmarshalJSON is a convenience method for Kong

type LogLevelFlag

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

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

type SettingKey

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 (SettingKey) String

func (i SettingKey) String() string

type Traces

Traces is the list of trace IDs enabled

type Traces []string

func (*Traces) Set

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

Set is a convenience method for pflag.Value

func (*Traces) String

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

String is a convenience method for pflag.Value

func (*Traces) Type

func (t *Traces) Type() string

Type is a convenience method for pflag.Value

Generated by gomarkdoc