build: add context-based logging infrastructure

AGENTS.md

@@ -16,6 +16,7 @@
 
 ### Testing Commands
 - Single package: `make unit pkg=<package> case=<test> timeout=5m`
+- Debug with logs: `make unit log="stdlog trace" pkg=<package> case=<test>`
 - Integration test: `make itest icase=$icase`
 
 ## Code Style Quick Reference
@@ -101,11 +102,12 @@ Strive for **near 90% test coverage** where practical.
 **YOU MUST** run tests before every commit:
 
 1. Run unit tests: `make unit pkg=$pkg case=$case timeout=5m`
-2. **Check logs carefully**:
+2. Run with debug logs: `make unit log="stdlog trace" pkg=$pkg case=$case`
+3. **Check logs carefully**:
    - Verify structured logging format is correct
    - Ensure no log spam
    - **No `[ERR]` lines should appear** unless testing error paths
-3. Run affected integration tests: `make itest icase=$icase`
+4. Run affected integration tests: `make itest icase=$icase`
 
 ## Development Workflow
 

CLAUDE.md

@@ -16,6 +16,7 @@
 
 ### Testing Commands
 - Single package: `make unit pkg=<package> case=<test> timeout=5m`
+- Debug with logs: `make unit log="stdlog trace" pkg=<package> case=<test>`
 - Integration test: `make itest icase=$icase`
 
 ## Code Style Quick Reference
@@ -101,11 +102,12 @@ Strive for **near 90% test coverage** where practical.
 **YOU MUST** run tests before every commit:
 
 1. Run unit tests: `make unit pkg=$pkg case=$case timeout=5m`
-2. **Check logs carefully**:
+2. Run with debug logs: `make unit log="stdlog trace" pkg=$pkg case=$case`
+3. **Check logs carefully**:
    - Verify structured logging format is correct
    - Ensure no log spam
    - **No `[ERR]` lines should appear** unless testing error paths
-3. Run affected integration tests: `make itest icase=$icase`
+4. Run affected integration tests: `make itest icase=$icase`
 
 ## Development Workflow
 

Makefile

@@ -57,6 +57,13 @@ ifneq ($(tags),)
 DEV_TAGS += ${tags}
 endif
 
+# Logging tags - can be overridden with log= parameter.
+# Examples: make unit log="stdlog trace"
+# This enables stdout logging with trace level for debugging tests.
+ifneq ($(log),)
+LOG_TAGS := $(log)
+endif
+
 # Coverage settings.
 COVER_PKG = $$($(GOCC) list -deps -tags="$(DEV_TAGS)" ./... | grep '$(PKG)')
 COVER_FLAGS = -coverprofile=coverage.txt -covermode=atomic -coverpkg=$(PKG)/...

build/context_logger.go

@@ -0,0 +1,43 @@
+package build
+
+import (
+	"context"
+
+	"github.com/btcsuite/btclog/v2"
+)
+
+// loggerKey is the context key for storing a logger. Using an empty struct as
+// the key type ensures that only this package can create keys of this type,
+// preventing key collisions with other packages.
+type loggerKey struct{}
+
+// ContextWithLogger returns a new context with the given logger attached. This
+// allows loggers to be propagated through the call stack via context, reducing
+// the need to pass loggers as explicit function parameters.
+func ContextWithLogger(ctx context.Context, log btclog.Logger) context.Context {
+	return context.WithValue(ctx, loggerKey{}, log)
+}
+
+// LoggerFromContext extracts a logger from the context. If no logger is
+// present in the context, it returns btclog.Disabled which safely no-ops all
+// log calls. This makes it safe to use in any context without nil checks.
+func LoggerFromContext(ctx context.Context) btclog.Logger {
+	log, ok := ctx.Value(loggerKey{}).(btclog.Logger)
+	if !ok || log == nil {
+		return btclog.Disabled
+	}
+
+	return log
+}
+
+// MustLoggerFromContext extracts a logger from the context. If no logger is
+// present, it panics. Use this only in code paths where you're certain a logger
+// should have been added to the context earlier in the call chain.
+func MustLoggerFromContext(ctx context.Context) btclog.Logger {
+	log, ok := ctx.Value(loggerKey{}).(btclog.Logger)
+	if !ok || log == nil {
+		panic("no logger in context")
+	}
+
+	return log
+}

build/context_logger_test.go

@@ -0,0 +1,102 @@
+package build
+
+import (
+	"os"
+	"testing"
+
+	"github.com/btcsuite/btclog/v2"
+	"github.com/stretchr/testify/require"
+)
+
+// TestContextWithLoggerRoundTrip tests that a logger can be stored in a context
+// and retrieved successfully.
+func TestContextWithLoggerRoundTrip(t *testing.T) {
+	t.Parallel()
+
+	// Create a real logger for testing.
+	backend := btclog.NewDefaultHandler(os.Stdout)
+	logger := btclog.NewSLogger(backend.SubSystem("TEST"))
+
+	// Store the logger in a context.
+	ctx := ContextWithLogger(t.Context(), logger)
+
+	// Retrieve the logger from the context.
+	retrieved := LoggerFromContext(ctx)
+
+	// Verify we got the same logger back.
+	require.Equal(t, logger, retrieved)
+}
+
+// TestLoggerFromContextReturnsDisabledWhenMissing tests that LoggerFromContext
+// returns btclog.Disabled when no logger is present in the context.
+func TestLoggerFromContextReturnsDisabledWhenMissing(t *testing.T) {
+	t.Parallel()
+
+	// Use an empty context with no logger.
+	ctx := t.Context()
+
+	// LoggerFromContext should return the disabled logger.
+	logger := LoggerFromContext(ctx)
+
+	require.Equal(t, btclog.Disabled, logger)
+}
+
+// TestLoggerFromContextReturnsDisabledWhenNil tests that LoggerFromContext
+// returns btclog.Disabled when a nil logger was stored in the context.
+func TestLoggerFromContextReturnsDisabledWhenNil(t *testing.T) {
+	t.Parallel()
+
+	// Store a nil logger in the context.
+	ctx := ContextWithLogger(t.Context(), nil)
+
+	// LoggerFromContext should return the disabled logger.
+	logger := LoggerFromContext(ctx)
+
+	require.Equal(t, btclog.Disabled, logger)
+}
+
+// TestMustLoggerFromContextPanicsWhenMissing tests that MustLoggerFromContext
+// panics when no logger is present in the context.
+func TestMustLoggerFromContextPanicsWhenMissing(t *testing.T) {
+	t.Parallel()
+
+	// Use an empty context with no logger.
+	ctx := t.Context()
+
+	// MustLoggerFromContext should panic.
+	require.Panics(t, func() {
+		MustLoggerFromContext(ctx)
+	})
+}
+
+// TestMustLoggerFromContextPanicsWhenNil tests that MustLoggerFromContext
+// panics when a nil logger was stored in the context.
+func TestMustLoggerFromContextPanicsWhenNil(t *testing.T) {
+	t.Parallel()
+
+	// Store a nil logger in the context.
+	ctx := ContextWithLogger(t.Context(), nil)
+
+	// MustLoggerFromContext should panic.
+	require.Panics(t, func() {
+		MustLoggerFromContext(ctx)
+	})
+}
+
+// TestMustLoggerFromContextSucceeds tests that MustLoggerFromContext returns
+// the logger when one is present.
+func TestMustLoggerFromContextSucceeds(t *testing.T) {
+	t.Parallel()
+
+	// Create a real logger for testing.
+	backend := btclog.NewDefaultHandler(os.Stdout)
+	logger := btclog.NewSLogger(backend.SubSystem("TEST"))
+
+	// Store the logger in a context.
+	ctx := ContextWithLogger(t.Context(), logger)
+
+	// MustLoggerFromContext should return the logger without panicking.
+	retrieved := MustLoggerFromContext(ctx)
+
+	require.Equal(t, logger, retrieved)
+}

build/log.go

@@ -0,0 +1,110 @@
+package build
+
+import (
+	"os"
+
+	"github.com/btcsuite/btclog/v2"
+)
+
+// LogType is an indicating the type of logging specified by the build flag.
+type LogType byte
+
+const (
+	// LogTypeNone indicates no logging.
+	LogTypeNone LogType = iota
+
+	// LogTypeStdOut all logging is written directly to stdout.
+	LogTypeStdOut
+
+	// LogTypeDefault logs to both stdout and a given io.PipeWriter.
+	LogTypeDefault
+)
+
+// String returns a human readable identifier for the logging type.
+func (t LogType) String() string {
+	switch t {
+	case LogTypeNone:
+		return "none"
+	case LogTypeStdOut:
+		return "stdout"
+	case LogTypeDefault:
+		return "default"
+	default:
+		return "unknown"
+	}
+}
+
+// Declare the supported log file compressors as exported consts for easier use
+// from other projects.
+const (
+	// Gzip is the default compressor.
+	Gzip = "gzip"
+
+	// Zstd is a modern compressor that compresses better than Gzip, in less
+	// time.
+	Zstd = "zstd"
+)
+
+// logCompressors maps the identifier for each supported compression algorithm
+// to the extension used for the compressed log files.
+var logCompressors = map[string]string{
+	Gzip: "gz",
+	Zstd: "zst",
+}
+
+// SupportedLogCompressor returns whether or not logCompressor is a supported
+// compression algorithm for log files.
+func SupportedLogCompressor(logCompressor string) bool {
+	_, ok := logCompressors[logCompressor]
+
+	return ok
+}
+
+// NewSubLogger constructs a new subsystem log from the current LogWriter
+// implementation. This is primarily intended for use with stdlog, as the actual
+// writer is shared amongst all instantiations.
+func NewSubLogger(subsystem string,
+	genSubLogger func(string) btclog.Logger) btclog.Logger {
+
+	switch Deployment {
+	// For production builds, generate a new subsystem logger from the
+	// primary log backend. If no function is provided, logging will be
+	// disabled.
+	case Production:
+		if genSubLogger != nil {
+			return genSubLogger(subsystem)
+		}
+
+	// For development builds, we must handle two distinct types of logging:
+	// unit tests and running the live daemon, e.g. for integration testing.
+	case Development:
+		switch LoggingType {
+		// Default logging is used when running the standalone daemon.
+		// We'll use the optional sublogger constructor to mimic the
+		// production behavior.
+		case LogTypeDefault:
+			if genSubLogger != nil {
+				return genSubLogger(subsystem)
+			}
+
+		// Logging to stdout is used in unit tests. It is not important
+		// that they share the same backend, since all output is written
+		// to std out.
+		case LogTypeStdOut:
+			backend := btclog.NewDefaultHandler(os.Stdout)
+			logger := btclog.NewSLogger(
+				backend.SubSystem(subsystem),
+			)
+
+			// Set the logging level of the stdout logger to use the
+			// configured logging level specified by build flags.
+			level, _ := btclog.LevelFromString(LogLevel)
+			logger.SetLevel(level)
+
+			return logger
+		}
+	}
+
+	// For any other configurations, we'll disable logging.
+	return btclog.Disabled
+}

build/log_default.go

@@ -0,0 +1,8 @@
+//go:build !stdlog && !nolog
+// +build !stdlog,!nolog
+
+package build
+
+// LoggingType is a log type that writes to both stdout and the log rotator, if
+// present.
+const LoggingType = LogTypeDefault

build/log_nolog.go

@@ -0,0 +1,7 @@
+//go:build nolog
+// +build nolog
+
+package build
+
+// LoggingType is a log type that writes no logs.
+const LoggingType = LogTypeNone

build/log_stdlog.go

@@ -0,0 +1,7 @@
+//go:build stdlog
+// +build stdlog
+
+package build
+
+// LoggingType is a log type that only writes to stdout.
+const LoggingType = LogTypeStdOut

build/loglevel_critical.go

@@ -0,0 +1,7 @@
+//go:build dev && critical
+// +build dev,critical
+
+package build
+
+// LogLevel specifies a critical log level.
+var LogLevel = "critical"

build/loglevel_debug.go

@@ -0,0 +1,7 @@
+//go:build dev && debug
+// +build dev,debug
+
+package build
+
+// LogLevel specifies a debug log level.
+var LogLevel = "debug"

build/loglevel_default.go

@@ -0,0 +1,7 @@
+//go:build !info && !debug && !trace && !warn && !error && !critical && !off
+// +build !info,!debug,!trace,!warn,!error,!critical,!off
+
+package build
+
+// LogLevel specifies a default log level of info.
+var LogLevel = "info"

build/loglevel_error.go

@@ -0,0 +1,7 @@
+//go:build dev && error
+// +build dev,error
+
+package build
+
+// LogLevel specifies an error log level.
+var LogLevel = "error"

build/loglevel_info.go

@@ -0,0 +1,7 @@
+//go:build dev && info
+// +build dev,info
+
+package build
+
+// LogLevel specifies an info log level.
+var LogLevel = "info"

build/loglevel_off.go

@@ -0,0 +1,7 @@
+//go:build dev && off
+// +build dev,off
+
+package build
+
+// LogLevel specifies logging is disabled.
+var LogLevel = "off"

build/loglevel_trace.go

@@ -0,0 +1,7 @@
+//go:build dev && trace
+// +build dev,trace
+
+package build
+
+// LogLevel specifies a trace log level.
+var LogLevel = "trace"