From 395cd98901a2a3094b12fbb037da9d75845f07ea Mon Sep 17 00:00:00 2001
From: Olaoluwa Osuntokun <laolu32@gmail.com>
Date: Mon, 24 Nov 2025 13:05:43 -0800
Subject: [PATCH 1/6] build: add log type enum and NewSubLogger

This commit introduces the core logging infrastructure ported from
lnd's build package. The LogType enum defines the three logging modes
supported: LogTypeNone (no logging), LogTypeStdOut (stdout only), and
LogTypeDefault (stdout plus optional log rotator).

The NewSubLogger function serves as a factory for creating subsystem
loggers. It examines the current deployment mode (Production vs
Development) and logging type to determine how to construct the
logger. For production builds, it delegates to an optional generator
function. For development builds with stdlog enabled, it creates a
stdout logger with the build-tag-configured log level. This design
allows tests to easily enable logging while keeping logs disabled by
default.
---
 build/log.go | 110 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)
 create mode 100644 build/log.go

diff --git a/build/log.go b/build/log.go
new file mode 100644
index 000000000..47ad216a3
--- /dev/null
+++ b/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
+}

From e59566a3bfc4baf8144d6fa217cf4f4f842ac774 Mon Sep 17 00:00:00 2001
From: Olaoluwa Osuntokun <laolu32@gmail.com>
Date: Mon, 24 Nov 2025 13:06:01 -0800
Subject: [PATCH 2/6] build: add log level build tag files

This commit adds eight files that use Go build tags to control the
default log level at compile time. The mechanism allows selecting
different verbosity levels without runtime configuration changes.

The loglevel_default.go file activates when no specific level tag is
set, providing "info" as the default. The remaining files each handle
their respective level: trace, debug, info, warn, error, critical,
and off. Each level-specific file requires both the "dev" tag and its
level tag (e.g., "dev && trace").

This pattern, borrowed from lnd, enables testing with verbose output
by simply adding build tags: "go test -tags='dev stdlog trace' ./..."
will enable trace-level logging to stdout.
---
 build/loglevel_critical.go | 7 +++++++
 build/loglevel_debug.go    | 7 +++++++
 build/loglevel_default.go  | 7 +++++++
 build/loglevel_error.go    | 7 +++++++
 build/loglevel_info.go     | 7 +++++++
 build/loglevel_off.go      | 7 +++++++
 build/loglevel_trace.go    | 7 +++++++
 build/loglevel_warn.go     | 7 +++++++
 8 files changed, 56 insertions(+)
 create mode 100644 build/loglevel_critical.go
 create mode 100644 build/loglevel_debug.go
 create mode 100644 build/loglevel_default.go
 create mode 100644 build/loglevel_error.go
 create mode 100644 build/loglevel_info.go
 create mode 100644 build/loglevel_off.go
 create mode 100644 build/loglevel_trace.go
 create mode 100644 build/loglevel_warn.go

diff --git a/build/loglevel_critical.go b/build/loglevel_critical.go
new file mode 100644
index 000000000..8decb83a0
--- /dev/null
+++ b/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"
diff --git a/build/loglevel_debug.go b/build/loglevel_debug.go
new file mode 100644
index 000000000..c80afec19
--- /dev/null
+++ b/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"
diff --git a/build/loglevel_default.go b/build/loglevel_default.go
new file mode 100644
index 000000000..52fe12243
--- /dev/null
+++ b/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"
diff --git a/build/loglevel_error.go b/build/loglevel_error.go
new file mode 100644
index 000000000..5fbdb999d
--- /dev/null
+++ b/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"
diff --git a/build/loglevel_info.go b/build/loglevel_info.go
new file mode 100644
index 000000000..c367f649d
--- /dev/null
+++ b/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"
diff --git a/build/loglevel_off.go b/build/loglevel_off.go
new file mode 100644
index 000000000..65fbf2c12
--- /dev/null
+++ b/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"
diff --git a/build/loglevel_trace.go b/build/loglevel_trace.go
new file mode 100644
index 000000000..1d9eed671
--- /dev/null
+++ b/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"
diff --git a/build/loglevel_warn.go b/build/loglevel_warn.go
new file mode 100644
index 000000000..868552374
--- /dev/null
+++ b/build/loglevel_warn.go
@@ -0,0 +1,7 @@
+//go:build dev && warn
+// +build dev,warn
+
+package build
+
+// LogLevel specifies a warn log level.
+var LogLevel = "warn"

From a041e4114d70008f0cdbb5350b6992214e1d409a Mon Sep 17 00:00:00 2001
From: Olaoluwa Osuntokun <laolu32@gmail.com>
Date: Mon, 24 Nov 2025 13:07:40 -0800
Subject: [PATCH 3/6] build: add log type build tag files

This commit adds three files that control where log output is directed
based on build tags.

The log_default.go file sets LoggingType to LogTypeDefault when neither
stdlog nor nolog tags are present, suitable for production daemon use
where logs go to both stdout and a log file rotator.

The log_stdlog.go file activates with the "stdlog" tag and directs all
output to stdout only, which is ideal for unit tests where you want to
see log output in the test output.

The log_nolog.go file activates with the "nolog" tag and disables all
logging entirely, which is the default for tests to avoid noise.
---
 build/log_default.go | 8 ++++++++
 build/log_nolog.go   | 7 +++++++
 build/log_stdlog.go  | 7 +++++++
 3 files changed, 22 insertions(+)
 create mode 100644 build/log_default.go
 create mode 100644 build/log_nolog.go
 create mode 100644 build/log_stdlog.go

diff --git a/build/log_default.go b/build/log_default.go
new file mode 100644
index 000000000..6e027e0dd
--- /dev/null
+++ b/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
diff --git a/build/log_nolog.go b/build/log_nolog.go
new file mode 100644
index 000000000..75f17bf66
--- /dev/null
+++ b/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
diff --git a/build/log_stdlog.go b/build/log_stdlog.go
new file mode 100644
index 000000000..461474376
--- /dev/null
+++ b/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

From adfab2369938d464f88c82c590f1fb026c5433aa Mon Sep 17 00:00:00 2001
From: Olaoluwa Osuntokun <laolu32@gmail.com>
Date: Mon, 24 Nov 2025 13:07:51 -0800
Subject: [PATCH 4/6] build: add context-based logger utilities

This commit introduces utilities for passing loggers through the call
stack via context.Context, providing a middle ground between global
loggers and explicit parameter passing.

The ContextWithLogger function attaches a logger to a context, while
LoggerFromContext extracts it. If no logger is present, it returns
btclog.Disabled which safely no-ops all log calls, making it safe to
use without nil checks.

A MustLoggerFromContext variant is also provided for code paths where
a logger must be present, panicking if one is not found.

This approach reduces the need to thread loggers through every function
parameter while maintaining explicit control over which logger is used.
The pattern works well with the existing per-instance logging from PR
#7, allowing subsystem loggers to be attached to request contexts.
---
 build/context_logger.go      |  43 +++++++++++++++
 build/context_logger_test.go | 102 +++++++++++++++++++++++++++++++++++
 2 files changed, 145 insertions(+)
 create mode 100644 build/context_logger.go
 create mode 100644 build/context_logger_test.go

diff --git a/build/context_logger.go b/build/context_logger.go
new file mode 100644
index 000000000..f8463a535
--- /dev/null
+++ b/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
+}
diff --git a/build/context_logger_test.go b/build/context_logger_test.go
new file mode 100644
index 000000000..5e06eb69f
--- /dev/null
+++ b/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)
+}

From d05e18a77b5c542af3ef5371c23fd60cd93aff9c Mon Sep 17 00:00:00 2001
From: Olaoluwa Osuntokun <laolu32@gmail.com>
Date: Mon, 24 Nov 2025 13:07:59 -0800
Subject: [PATCH 5/6] build: add log parameter support to Makefile

This commit adds a "log" parameter to the Makefile that allows
overriding the default LOG_TAGS value. By default, tests run with
"nolog" to keep output clean, but developers can enable logging for
debugging with: make unit log="stdlog trace" pkg=db

The parameter accepts any combination of log type and level tags,
making it easy to toggle verbose logging during test development
without modifying the Makefile itself.
---
 Makefile | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/Makefile b/Makefile
index 78d899086..8ad0f45bb 100644
--- a/Makefile
+++ b/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)/...

From d7cf785ae323458eab6e93d1cb547e7b6572f098 Mon Sep 17 00:00:00 2001
From: Olaoluwa Osuntokun <laolu32@gmail.com>
Date: Mon, 24 Nov 2025 13:32:53 -0800
Subject: [PATCH 6/6] docs: update testing commands with log parameter

Update CLAUDE.md and AGENTS.md to document the log= parameter for
enabling debug logging during unit tests. This replaces the previously
documented unit-debug target with the more flexible parameter approach.
---
 AGENTS.md | 6 ++++--
 CLAUDE.md | 6 ++++--
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 5af25296b..32f91f3db 100644
--- a/AGENTS.md
+++ b/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
 
diff --git a/CLAUDE.md b/CLAUDE.md
index 5af25296b..32f91f3db 100644
--- a/CLAUDE.md
+++ b/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