v1.0.0

code.nochebuena.dev/go/logz

Overview

logz v1.0.0 commits the structured logging API as stable. All v0.9.0 roadmap
items are resolved. The module ships a minimal six-method Logger interface
backed by stdlib log/slog, with zero external dependencies, owned context keys
for request correlation, and a duck-typed xerrors enrichment bridge validated
under concurrent production load.

What Changed Since v0.9.0

New: `Options.Writer io.Writer`

type Options struct {
    Level      slog.Level
    JSON       bool
    StaticArgs []any
    Writer     io.Writer // nil → os.Stdout
}

The output destination is now configurable. When Writer is nil the behavior is
identical to v0.9.0 (writes to os.Stdout). Any io.Writer implementation is
accepted:

// Test log capture
var buf bytes.Buffer
l := logz.New(logz.Options{Writer: &buf})

// File-based audit trail
f, _ := os.OpenFile("audit.log", os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
l := logz.New(logz.Options{Writer: f, JSON: true})

// Both stdout and file
l := logz.New(logz.Options{Writer: io.MultiWriter(os.Stdout, f), JSON: true})

Roadmap items resolved

Item	Resolution
`io.Writer` configurable	✅ `Options.Writer` — nil defaults to `os.Stdout`
Log sampling	❌ No — belongs in `slog.Handler` wrappers or the observability layer
Concurrent xerrors enrichment	✅ Validated — `ErrorContext()` is read-only post-construction
`Logger` interface is final	✅ Committed — 6 methods; `Fatal`/`Panic` intentionally excluded
`WithFields` merge concurrency	✅ Validated — `context.WithValue` immutability guarantees safety

Full API (stable)

Logger — interface: Debug, Info, Warn, Error(msg, err, args...),
With(args...) Logger, WithContext(ctx) Logger.

Options — Level slog.Level, JSON bool, StaticArgs []any,
Writer io.Writer (nil → os.Stdout). Zero value is valid.

New(opts Options) Logger — constructor; returns Logger, never the concrete type.

WithRequestID(ctx, id) context.Context — stores a correlation ID under this
package's private context key.

GetRequestID(ctx) string — retrieves the ID; returns "" if absent or ctx nil.

WithField(ctx, key, value) context.Context — adds a single field to the context.

WithFields(ctx, fields) context.Context — merges multiple fields; does not
overwrite existing keys.

Logger.WithContext(ctx) Logger — child logger pre-enriched with request_id
and any extra fields from the context; returns the same logger if ctx carries no
relevant values.

Automatic error enrichment — Logger.Error inspects err for ErrorCode()
and ErrorContext() duck-type methods (satisfied by *xerrors.Err) and appends
error_code and context fields automatically. No import between logz and
xerrors is required in either direction.

Migration from v0.9.0

No breaking changes. Options{} continues to write to os.Stdout.

go get code.nochebuena.dev/go/logz@v1.0.0

Downloads

2 Releases 3 Tags

Release v1.0.0 Stable