go.bigb.es/auxilia

v0.2.0
Doc Versions Source

Index

Functions

f func DefaultLevelColors

src 
func DefaultLevelColors() map[slog.Level]Color

DefaultLevelColors returns sensible default colors for log levels.

f func Err

src 
func Err(err error) slog.Attr

Err wraps an error for logging with red color highlighting. Use this when logging errors to make them visually distinct: 

logger.Error("failed", scribe.Err(err))

If the error is a culpa error, its details (hint, code, etc.) and stacktrace will be extracted and formatted.

f func ErrAttr

src 
func ErrAttr(key string, err error) slog.Attr

ErrAttr is like Err but allows specifying a custom key. 

logger.Error("failed", scribe.ErrAttr("cause", err))

f func NewJSONHandler

src 
func NewJSONHandler(opts ...Option) slog.Handler

NewJSONHandler creates a JSON handler with the scribe options API. This is a convenience wrapper around slog.JSONHandler for consistency.

f func NewTextHandler

src 
func NewTextHandler(opts ...Option) slog.Handler

NewTextHandler creates a text handler with the scribe options API. This is a convenience wrapper around slog.TextHandler for consistency.

Types

T type BufferHandler

src 
type BufferHandler struct {
	// contains filtered or unexported fields
}

BufferHandler wraps another handler and stores all records in a ring buffer. Records are stored regardless of level filtering applied by the inner handler.

f func NewBufferHandler

src 
func NewBufferHandler(inner slog.Handler, opts ...Option) *BufferHandler

NewBufferHandler creates a buffering wrapper around another handler.

m func (*BufferHandler) Buffer

src 
func (h *BufferHandler) Buffer() *RingBuffer[StoredRecord]

Buffer returns the underlying ring buffer for direct access.

m func (*BufferHandler) Enabled

src 
func (h *BufferHandler) Enabled(_ context.Context, _ slog.Level) bool

Enabled implements slog.Handler. Always returns true to capture all records in the buffer.

m func (*BufferHandler) Handle

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

Handle implements slog.Handler.

m func (*BufferHandler) Records

src 
func (h *BufferHandler) Records() []StoredRecord

Records returns all stored records.

m func (*BufferHandler) RecordsByLevel

src 
func (h *BufferHandler) RecordsByLevel(level slog.Level) []StoredRecord

RecordsByLevel returns records matching the given level.

m func (*BufferHandler) RecordsSince

src 
func (h *BufferHandler) RecordsSince(t time.Time) []StoredRecord

RecordsSince returns records from the given time onwards.

m func (*BufferHandler) Replay

src 
func (h *BufferHandler) Replay(ctx context.Context, target slog.Handler) error

Replay sends all buffered records to another handler.

m func (*BufferHandler) WithAttrs

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

WithAttrs implements slog.Handler.

m func (*BufferHandler) WithGroup

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

WithGroup implements slog.Handler.

T type Color

src 
type Color string

Color represents an ANSI color code. 

const (
	Reset   Color = "\033[0m"
	Bold    Color = "\033[1m"
	Faint   Color = "\033[2m"
	Italic  Color = "\033[3m"
	Black   Color = "\033[30m"
	Red     Color = "\033[31m"
	Green   Color = "\033[32m"
	Yellow  Color = "\033[33m"
	Blue    Color = "\033[34m"
	Magenta Color = "\033[35m"
	Cyan    Color = "\033[36m"
	White   Color = "\033[37m"
	Gray    Color = "\033[90m"

	// Bright variants
	BrightRed     Color = "\033[91m"
	BrightGreen   Color = "\033[92m"
	BrightYellow  Color = "\033[93m"
	BrightBlue    Color = "\033[94m"
	BrightMagenta Color = "\033[95m"
	BrightCyan    Color = "\033[96m"
	BrightWhite   Color = "\033[97m"
)

ANSI color codes.

m func (Color) String

src 
func (c Color) String() string

String returns the ANSI escape sequence.

m func (Color) Wrap

src 
func (c Color) Wrap(s string) string

Wrap wraps a string with this color and resets at the end.

T type MaskRule

src 
type MaskRule struct {
	Pattern     *regexp.Regexp
	Replacement string
	KeepPrefix  int // If > 0, keep first N chars and append Replacement
}

MaskRule defines a pattern for masking sensitive values.

T type MultiHandler

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

MultiHandler fans out log records to multiple handlers.

f func NewMultiHandler

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

NewMultiHandler creates a handler that writes to all given handlers.

m func (*MultiHandler) Enabled

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

Enabled implements slog.Handler. Returns true if any inner handler is enabled for the level.

m func (*MultiHandler) Handle

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

Handle implements slog.Handler. Writes to all enabled handlers, collecting any errors.

m func (*MultiHandler) WithAttrs

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

WithAttrs implements slog.Handler.

m func (*MultiHandler) WithGroup

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

WithGroup implements slog.Handler.

T type Option

src 
type Option func(*options)

Option configures a Handler.

f func WithBufferSize

src 
func WithBufferSize(size int) Option

WithBufferSize sets the circular buffer capacity (number of records).

f func WithExpandErrors

src 
func WithExpandErrors(expand bool) Option

WithExpandErrors controls whether error details are expanded into separate fields (err.msg, err.code, etc.) or kept as a single group. Default is true (expanded).

f func WithFullStacktrace

src 
func WithFullStacktrace(full bool) Option

WithFullStacktrace controls whether full stacktraces are shown. When false (default), only the first frame (file:line) is shown. When true, the complete stacktrace is displayed.

f func WithLevel

src 
func WithLevel(l slog.Leveler) Option

WithLevel sets the minimum log level.

f func WithLevelColors

src 
func WithLevelColors(colors map[slog.Level]Color) Option

WithLevelColors sets custom colors for log levels.

f func WithMask

src 
func WithMask(pattern string, replacement string) Option

WithMask adds a masking rule for sensitive data. Pattern is a regex that matches against the full key path (e.g., "user.password"). Replacement is the string to show instead of the actual value (default: "***").

Example patterns:

  • `(?i)password` - matches any key containing "password" (case-insensitive)
  • `(?i)(secret|token|key)` - matches keys with secret, token, or key
  • `^user\..*_secret$` - matches user.api_secret, user.client_secret, etc.
  • `\[\d+\]\.apiKey` - matches items[0].apiKey, items[1].apiKey, etc.

f func WithMaskKeys

src 
func WithMaskKeys(keys ...string) Option

WithMaskKeys adds exact key masking (case-insensitive). This is a convenience wrapper around WithMask for simple cases.

Example: 

WithMaskKeys("password", "secret", "token", "apiKey")

f func WithMaskPartial

src 
func WithMaskPartial(pattern string, keepPrefix int) Option

WithMaskPartial adds a partial masking rule that keeps the first N characters. Useful for tokens, IDs, or hashes where you want to see a prefix for debugging.

Example: 

WithMaskPartial(`(?i)token`, 6) // "bearer-abc123xyz" → "bearer***"
WithMaskPartial(`(?i)hash`, 8)  // "0xabcdef123456" → "0xabcdef***"

f func WithNoColor

src 
func WithNoColor(noColor bool) Option

WithNoColor disables colorized output.

f func WithReplaceAttr

src 
func WithReplaceAttr(f func(groups []string, a slog.Attr) slog.Attr) Option

WithReplaceAttr sets the attribute replacement function. This function is called for each attribute before it is formatted.

f func WithSource

src 
func WithSource(enabled bool) Option

WithSource enables source code location in log output.

f func WithTimeFormat

src 
func WithTimeFormat(format string) Option

WithTimeFormat sets the time format for tint output. Uses Go's time format strings (e.g., time.RFC3339, time.Kitchen).

f func WithWriter

src 
func WithWriter(w io.Writer) Option

WithWriter sets the output destination.

T type RingBuffer

src 
type RingBuffer[T any] struct {
	// contains filtered or unexported fields
}

RingBuffer is a generic circular buffer.

f func NewRingBuffer

src 
func NewRingBuffer[T any](capacity int) *RingBuffer[T]

NewRingBuffer creates a new ring buffer with the given capacity.

m func (*RingBuffer[T]) Cap

src 
func (r *RingBuffer[T]) Cap() int

Cap returns the buffer capacity.

m func (*RingBuffer[T]) Clear

src 
func (r *RingBuffer[T]) Clear()

Clear removes all items from the buffer.

m func (*RingBuffer[T]) Filter

src 
func (r *RingBuffer[T]) Filter(pred func(T) bool) []T

Filter returns items matching the predicate.

m func (*RingBuffer[T]) Len

src 
func (r *RingBuffer[T]) Len() int

Len returns the current number of items.

m func (*RingBuffer[T]) Push

src 
func (r *RingBuffer[T]) Push(item T)

Push adds an item to the buffer, evicting the oldest if full.

m func (*RingBuffer[T]) Snapshot

src 
func (r *RingBuffer[T]) Snapshot() []T

Snapshot returns a copy of all items in chronological order.

T type StoredRecord

src 
type StoredRecord struct {
	Time    time.Time
	Level   slog.Level
	Message string
	Attrs   []slog.Attr
	PC      uintptr
	Groups  []string
}

StoredRecord holds a captured log record for later retrieval.

f func FromSlogRecord

src 
func FromSlogRecord(r slog.Record, groups []string) StoredRecord

FromSlogRecord creates a StoredRecord from an slog.Record.

m func (StoredRecord) ToSlogRecord

src 
func (s StoredRecord) ToSlogRecord() slog.Record

ToSlogRecord converts back to an slog.Record (for replay).

T type TintHandler

src 
type TintHandler struct {
	// contains filtered or unexported fields
}

TintHandler is a pretty-printing slog.Handler for terminal output.

f func NewTintHandler

src 
func NewTintHandler(opts ...Option) *TintHandler

NewTintHandler creates a new pretty-printing handler for terminal output.

m func (*TintHandler) Enabled

src 
func (h *TintHandler) Enabled(_ context.Context, level slog.Level) bool

Enabled implements slog.Handler.

m func (*TintHandler) Handle

src 
func (h *TintHandler) Handle(_ context.Context, r slog.Record) error

Handle implements slog.Handler.

m func (*TintHandler) WithAttrs

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

WithAttrs implements slog.Handler.

m func (*TintHandler) WithGroup

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

WithGroup implements slog.Handler.

Source Files