go-log/docs/index.md

title	description
go-log	Structured logging and error handling for Core applications

go-log

dappco.re/go/core/log provides structured logging and contextual error handling for Go applications built on the Core framework. It is a small, zero-dependency library (only testify at test time) that replaces ad-hoc fmt.Println / log.Printf calls with level-filtered, key-value structured output and a rich error type that carries operation context through the call stack.

Quick Start

import "dappco.re/go/core/log"

// Use the package-level default logger straight away
log.SetLevel(log.LevelDebug)
log.Info("server started", "port", 8080)
log.Warn("high latency", "ms", 320)
log.Error("request failed", "err", err)

// Security events are always visible at Error level
log.Security("brute force detected", "ip", "10.0.0.1", "attempts", 47)

Creating a Custom Logger

logger := log.New(log.Options{
    Level:      log.LevelInfo,
    Output:     os.Stdout,
    RedactKeys: []string{"password", "token", "secret"},
})

logger.Info("login", "user", "admin", "password", "hunter2")
// Output: 14:32:01 [INF] login user="admin" password="[REDACTED]"

Structured Errors

// Create an error with operational context
err := log.E("db.Connect", "connection refused", underlyingErr)

// Wrap errors as they bubble up through layers
err = log.Wrap(err, "user.Save", "failed to persist user")

// Inspect the chain
log.Op(err)             // "user.Save"
log.Root(err)           // the original underlyingErr
log.StackTrace(err)     // ["user.Save", "db.Connect"]
log.FormatStackTrace(err) // "user.Save -> db.Connect"

// Recovery hints are also available when the error carries them
log.IsRetryable(err)    // false unless a wrapped Err marks it retryable
log.RecoveryAction(err) // "retry with backoff" when provided

Combined Log-and-Return

if err != nil {
    return log.LogError(err, "handler.Process", "request failed")
    // Logs at Error level AND returns a wrapped error -- one line instead of three
}

Package Layout

File	Purpose
log.go	Logger type, log levels, key-value formatting, redaction, default logger, Username() helper
errors.go	Err structured error type, creation helpers (E, Wrap, WrapCode, NewCode, and recovery-aware variants), introspection (Op, ErrCode, Root, StackTrace, recovery hints), combined log-and-return helpers (LogError, LogWarn, Must)
log_test.go	Tests for the Logger: level filtering, key-value output, redaction, injection prevention, security logging
errors_test.go	Tests for structured errors: creation, wrapping, code propagation, introspection, stack traces, log-and-return helpers

Dependencies

Module	Purpose
Go standard library only	Runtime -- no external dependencies
github.com/stretchr/testify	Test assertions (test-only)

The package deliberately avoids external runtime dependencies. Log rotation is supported through an optional RotationWriterFactory hook that can be wired up by core/go-io or any other provider -- go-log itself carries no file-rotation code.

Module Path

dappco.re/go/core/log

Requires Go 1.26+ (uses iter.Seq from the standard library).

Licence

EUPL-1.2