logging

Documentation

Overview

Package logging provides structured logging for the aix CLI using slog.

The package supports both text and JSON output formats, configurable log levels, and helpers for testing. All loggers are based on the standard library's log/slog package.

Basic Usage

logger := logging.New(logging.Config{
	Level:  slog.LevelInfo,
	Format: logging.FormatText,
	Output: os.Stderr,
})
logger.Info("starting", "version", "1.0.0")

Testing

For tests, use ForTest to capture log output via the testing framework:

func TestSomething(t *testing.T) {
	logger := logging.ForTest(t)
	// logs appear in test output on failure
}

Quiet Mode

Use NewDiscard when log output should be suppressed entirely:

logger := logging.NewDiscard()

Configuration Precedence

Logging is configured in the following order of precedence:

1. CLI Flags: --verbose/-v, --quiet/-q, --log-format, --log-file.
2. Environment Variables: AIX_DEBUG=1 (Debug), AIX_DEBUG=2 (Trace).
3. Defaults: Warn level, Text format, Output to Stderr.

Note that --log-file always uses JSON format regardless of --log-format. --log-format only controls the primary output (Stderr).

Index

• Constants
• func Default() *slog.Logger
• func ForTest(t *testing.T) *slog.Logger
• func FromContext(ctx context.Context) *slog.Logger
• func IsTTY(w io.Writer) bool
• func LevelFromVerbosity(v int) slog.Level
• func New(cfg Config) *slog.Logger
• func NewContext(ctx context.Context, l *slog.Logger) context.Context
• func NewDiscard() *slog.Logger
• func SupportsColor(w io.Writer) bool
• type Config
• type Format
• type Handler
  • func NewHandler(out io.Writer, opts *slog.HandlerOptions) *Handler
  • func (h *Handler) Enabled(ctx context.Context, level slog.Level) bool
  • func (h *Handler) Handle(ctx context.Context, r slog.Record) error
  • func (h *Handler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (h *Handler) WithGroup(name string) slog.Handler
• type MultiHandler
  • func NewMultiHandler(handlers ...slog.Handler) *MultiHandler
  • func (h *MultiHandler) Enabled(ctx context.Context, level slog.Level) bool
  • func (h *MultiHandler) Handle(ctx context.Context, r slog.Record) error
  • func (h *MultiHandler) WithAttrs(attrs []slog.Attr) slog.Handler
  • func (h *MultiHandler) WithGroup(name string) slog.Handler

Constants

const LevelTrace = slog.LevelDebug - 4

LevelTrace is the log level for trace messages. It is lower than Debug (-4) to allow for very verbose output.

Functions

func Default

func Default() *slog.Logger

Default returns a sensible default logger configured for CLI use. It logs at Warn level in text format to stderr, matching the CLI's default verbosity.

func ForTest

func ForTest(t *testing.T) *slog.Logger

ForTest creates a logger that writes to the test's log output. Log messages appear only when the test fails or when running with -v. The logger is configured at Debug level to capture all messages.

func FromContext

func FromContext(ctx context.Context) *slog.Logger

FromContext returns the logger stored in the context, or the default logger if none is set.

func IsTTY

func IsTTY(w io.Writer) bool

IsTTY returns true if the given writer is a terminal. It supports os.File and any wrapper that provides an Fd() method.

func LevelFromVerbosity

func LevelFromVerbosity(v int) slog.Level

LevelFromVerbosity returns the log level for the given verbosity count. 0 -> Warn 1 -> Info 2 -> Debug 3+ -> Trace

func New

func New(cfg Config) *slog.Logger

New creates a logger with the given configuration. If cfg.Output is nil, it defaults to os.Stderr. If cfg.Format is not recognized, it defaults to FormatText.

func NewContext

func NewContext(ctx context.Context, l *slog.Logger) context.Context

NewContext returns a new context with the given logger attached.

func NewDiscard

func NewDiscard() *slog.Logger

NewDiscard creates a logger that discards all output. Use this for quiet mode or when logging should be suppressed.

func SupportsColor

func SupportsColor(w io.Writer) bool

SupportsColor returns true if the given writer supports ANSI color codes. It returns false if:

• The writer is not a TTY
• The NO_COLOR environment variable is set
• The TERM environment variable is set to "dumb"

Types

type Config

type Config struct {
	// Level sets the minimum log level. Messages below this level are discarded.
	Level slog.Level
	// Format specifies the output format (text or JSON).
	Format Format
	// Output is where log messages are written. Defaults to os.Stderr if nil.
	Output io.Writer
}

Config holds the configuration for creating a new logger.

type Format

type Format string

Format specifies the output format for log messages.

const (
	// FormatText produces human-readable text output.
	FormatText Format = "text"
	// FormatJSON produces machine-readable JSON output.
	FormatJSON Format = "json"
)

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler implements slog.Handler for TTY-optimized text output. It provides colorized output when the writer supports it.

func NewHandler

func NewHandler(out io.Writer, opts *slog.HandlerOptions) *Handler

NewHandler creates a new TTY-optimized text handler.

func (*Handler) Enabled

func (h *Handler) Enabled(ctx context.Context, level slog.Level) bool

Enabled reports whether the handler handles records at the given level.

func (*Handler) Handle

func (h *Handler) Handle(ctx context.Context, r slog.Record) error

Handle handles the Record.

func (*Handler) WithAttrs

func (h *Handler) WithAttrs(attrs []slog.Attr) slog.Handler

WithAttrs returns a new Handler with the given attributes.

func (*Handler) WithGroup

func (h *Handler) WithGroup(name string) slog.Handler

WithGroup returns a new Handler with the given group name. Currently groups are implemented by prefixing keys.

type MultiHandler

type MultiHandler struct {
	// contains filtered or unexported fields
}

MultiHandler dispatches records to multiple handlers.

func NewMultiHandler

func NewMultiHandler(handlers ...slog.Handler) *MultiHandler

NewMultiHandler creates a new MultiHandler that dispatches to all provided handlers.

func (*MultiHandler) Enabled

func (h *MultiHandler) Enabled(ctx context.Context, level slog.Level) bool

Enabled reports whether at least one of the underlying handlers is enabled for the given level.

func (*MultiHandler) Handle

func (h *MultiHandler) Handle(ctx context.Context, r slog.Record) error

Handle dispatches the record to all enabled underlying handlers.

func (*MultiHandler) WithAttrs

func (h *MultiHandler) WithAttrs(attrs []slog.Attr) slog.Handler

WithAttrs returns a new MultiHandler where each underlying handler has the given attributes.

func (*MultiHandler) WithGroup

func (h *MultiHandler) WithGroup(name string) slog.Handler

WithGroup returns a new MultiHandler where each underlying handler has the given group.