#29256 log, refactor: Allow log macros to accept context arguments

Updates Bitcoin Core's logging macros (`LogError`, `LogWarning`, `LogInfo`, `LogDebug`, `LogTrace`) to accept optional context arguments representing target logger instances, custom formatters, and categories. Macro expansion is consolidated under a new `LOG_EMIT` macro that performs compile-time argument checks, enforces category rules per log level, and avoids unnecessary formatting work when logging is disabled. Rate limiting configuration is moved to an `Options` structure passed through logging hooks.

Problem: All log macros write to a single global logger instance, which forces consumers of `libbitcoinkernel` to share global log state and prevents isolated logging across separate contexts. Subsystems needing custom message formatting or prefixes (such as wallet names handled via `WalletLogPrintf`) cannot use standard log level macros.

Evidence of importance:

• PR description: "Having a single global log stream works very well for `bitcoind` and will not change. But it limits functionality of libbitcoinkernel, forcing all potential users of the library, including applications written in different languages and running in different environments (like jupyter notebooks) to use shared global state and not be able to do things like get an isolated log trace from one operation."
• Commit 6292d61b55: "Unnecessary `strprintf` calls are now skipped when logging is disabled... could speed up fuzz tests calling functions which log."
• Commit f5737f0478: adds tests verifying that `Info` and higher severity messages preserve argument side-effect evaluation even if logging is disabled, addressing review feedback from #34374.

Scope: Part of a PR stack based on #34778. The non-base commits are specifically f48f450b1b8, dc9a4f94f3e, and eea210b6420.

Risk of a mistake: low (other). A macro expansion or compile-time check bug in logging utility code would cause compilation errors, formatting failures, or missed log lines, but does not risk consensus, validation state, or node persistence.

Changed since the previous assessment: No substantial conceptual changes; the commits remain based on #34778 and implement context arguments and compile-time macro validation.

Ready · Review #34778 first

Stacked on #34778; the base PR's changes are included in this diff.

Waiting on (from the thread read):

• reviewer: l0rinc to re-review after author simplified commits and addressed comments 2026-03-04
• reviewer: hodlinator to review latest push 2026-03-04
• reviewer: l0rinc to re-review following commit simplifications and push in r:3890020566 2026-03-04
• decision: unresolved Concept NACK from ajtowns against instanced logging and context arguments 2026-03-05

Disputed

objection that needs a change, the objector pushed back after a reply (ajtowns)

Thread notes: ajtowns reiterated Concept NACK in c:4005436980, marking the objection contested. Author addressed review comments from l0rinc and hodlinator, split commits, and pushed updates based on #34778. / Updated ajtowns's objection status to contested following repeated Concept NACK reaffirmations. Recorded author's responses and commit simplifications addressing l0rinc's change request, which is now answered pending re-review.

Objections, suggestions, and questions:

Support:

• vasild (member) (2024-02-16) [read]: separating facility from severity is a step in the right direction
• sedited (member) (Concept ACK, 2024-06-25) [read]: supports instanced logging for kernel use cases such as running two chainstate managers in parallel
• jonatack (member) (Concept ACK, 2024-06-28) [read]: favors simpler and open severity-based logging rather than overly restrictive macro rules

Participants:

• ajtowns (member, objection, 12 statements 2024-01-16 to 2026-03-05): Concept NACK; argues instanced logging in kernel is unnecessary and context arguments add churn and complexity
• vasild (member, support, 1 statements 2024-02-16 to 2024-02-16): favors separating facility from severity
• sedited (member, support, 1 statements 2024-06-25 to 2024-06-25): Concept ACK; cited use cases like running parallel chainstate managers in libbitcoinkernel
• hodlinator (member, objection, 24 statements 2024-06-26 to 2026-03-04): requested changes to preserve #28318 category restrictions and log formatting, which author implemented
• jonatack (member, support, 2 statements 2024-06-28 to 2024-06-28): Concept ACK; favors simpler and consistent severity-based logging
• l0rinc (member, objection, 20 statements 2026-03-02 to 2026-03-04): requested changes to split large commits and address abstraction issues

Depends on: #34778

Enables:

• #30342
• #30343

Based on (shares commits with): #34778

Base for: #30342, #30343

228 lines under test/bench/ci.

• src/util/log.h +185/-62
• src/test/logging_tests.cpp +207/-21
• src/logging.cpp +18/-24
• src/kernel/bitcoinkernel.cpp +7/-13
• src/logging.h +3/-3
• src/validation.cpp +3/-2
• doc/developer-notes.md +1/-2

The short text the ranking pass compares across PRs.

Extends the core logging macros to accept optional context arguments, allowing log messages to specify distinct logger instances, metadata, and custom formatters. This addresses libbitcoinkernel's limitation of requiring a shared global logger stream and provides the infrastructure needed to deprecate subsystem-specific logging wrappers like WalletLogPrintf. Author notes this unblocks independent log stream management in kernel PR 30342 and wallet PR 30343. This PR is based on PR 34778.

P2 · new feature (ranking pass: Moved up five places: it is the macro-level prerequisite for both #33847 and #30342, so it inherits their importance and must be reviewed before them.)

Enables multi-instance and isolated logging streams necessary for libbitcoinkernel consumers. The PR description notes that a single global log stream 'limits functionality of libbitcoinkernel, forcing all potential users of the library... to use shared global state and not be able to do things like get an isolated log trace from one operation.'

Membership: Touches src/kernel/bitcoinkernel.cpp and directly addresses kernel library requirements by removing the reliance on a single global logger instance.

Factors: security/stability 0, bug 0, performance 1, user value 1, leverage 2

P2 · new feature (ranking pass: Placed directly after its base #34778 so the chain is reviewed in order.)

Substantially upgrades node-wide logging infrastructure to support contextual logger targets and custom formatters while optimizing disabled log evaluation. The description highlights consolidating macro expansion under `LOG_EMIT`, performing compile-time argument validation, and skipping unnecessary `strprintf` calls when logging is disabled.

Membership: Carries the Utils/log/libs label and heavily modifies the core logging macro infrastructure in src/util/log.h and src/logging.cpp.

Factors: security/stability 0, bug 0, performance 1, user value 1, leverage 2