kernel: make logging struct-based #34466

1. 
   stickies-v commented at 6:07 pm on January 30, 2026: contributor

   The bitcoinkernel library (#27587) exposes functionality to interface with kernel logging. This includes registering callbacks for log statements, level/category filtering, string formatting options, and more.

   This PR improves kernel logging by making it struct-based instead of string-based. Rather than adding this functionality onto an already large BCLog::Logger class, the PR first separates log generation (i.e. producing the log message via LogInfo(msg)) from log consumption (i.e. formatting, ratelimiting, printing the message) by moving all log generation code to util/log.h. While not strictly necessary for adding struct-based logging, it better separates concerns and is a prerequisite for follow-up work in #34374 that completely removes kernel’s dependency on logging.cpp.

   Approach:

   1. Separate log generation: Add a minimal util::log::Dispatcher that is used to generate logs, and forwards struct-based log entries to registered callbacks. No formatting, rate-limiting, or output handling - that’s the consumer’s responsibility.

   2. Register BCLog::Logger on Dispatcher: Register a callback on the global Dispatcher to receive entries and handle node-specific concerns (formatting, rate-limiting, file output) without changing most of its logic. Route logging macros through this global dispatcher.

   3. Update bitcoinkernel C API: Replace the string-based callback with btck_LogEntry containing full metadata and remove btck_LoggingOptions and related functions.

   Note: with this change, bitcoinkernel logging callbacks are no longer routed through BCLog::Logger. This means that they are no longer buffered (i.e. log messages produced before a logging callback is registered) are dropped, and there is no longer a need for btck_logging_disable. In practice, this means users can no longer see the log message produced during the static context initialization.

   Carve-out of #34374 to narrow the focus while maintaining tangible benefits (i.e. having struct-based logging).

2. move-only: move SourceLocation to separate header

   This is preparatory work for a future commit so SourceLocation can
   be used without requiring logging.h.

   e88433b1db
3. move-only: move BCLog::Level to util::log::Level

   This is preparatory work for a future commit so Level can
   be used without requiring logging.h.

   856761b8dc
4. util: add log::Dispatcher for struct-based log dispatch

   Add a minimal, callback-based dispatcher that forwards struct-based log
   entries to registered callbacks. This provides the foundation for
   separating log generation from log consumption, enabling different
   consumers (node sink, kernel C API) to receive the same log entries.

   5b01eaef7a
5. logging: add Dispatcher to Logger and introduce global dispatcher

   Preparatory work for a future commit where the logging macros are moved
   to the util library. The macros require a single global entry point to
   dispatch log entries.
   
   Make BCLog::Logger aware of util::log::Dispatcher by giving it ownership
   of a Dispatcher instance which it can register callbacks on.
   
   Currently, only a single sink (i.e. BCLog::Logger) exists, but in future
   commits this will change as kernel removes its dependency on logging.cpp
   and introduces its own global logging sink.

   146ad2492a
6. logging: route log macros through Dispatcher

   Log macros now call util::log::g_dispatcher().Log() directly instead of
   going through LogInstance(). BCLog::Logger registers a callback on its
   Dispatcher to receive entries and handle formatting, rate limiting, and
   output.

   b54139ece1
7. kernel: add log level/category name getters

   Expose btck_log_level_get_name and btck_log_category_get_name to allow
   library users to get string representations of log levels and categories.
   
   Use constexpr lookup tables as a single source of truth for mapping
   btck types to both BCLog equivalents and string names.

   797cb4a912
8. kernel: add missing log levels and categories

   Ensure all levels and categories that may be logged by kernel code
   are well defined. Necessary preparation for future work to move
   from string-based to struct-based logging.

   fb6e9eccff
9. kernel: expose btck_LogEntry

   Preparatory work for a future commit where the btck_LogCallback
   exposes btck_LogEntry instead of a string.
   
   Contains a lot of move-only changes, consider reviewing with
   --color-moved=dimmed-zebra

   38e92d0665
10. kernel: make logging struct-based

    Replace the string-based logging callback with btck_LogEntry containing
    full metadata (message, source location, timestamp, level, category).
    This lets consumers format and filter logs as needed.
    
    Use the global log dispatcher instead of BCLog::Logger's buffered
    callback system. Messages are discarded when no callbacks are registered.

    3f05248952
11. kernel: remove unused logging functions

    As logging is struct-based, there is no more need for the user to
    configure how logs are printed, so simplify the interface and remove
    dead code.

    94699eb1da
12. DrahtBot added the label Validation on Jan 30, 2026
13. 
    DrahtBot commented at 6:08 pm on January 30, 2026: contributor

    The following sections might be updated with supplementary metadata relevant to reviewers and maintainers.

    Reviews

    See the guideline for information on the review process. A summary of reviews will appear here.

14. 
    stickies-v commented at 6:21 pm on January 30, 2026: contributor

    Didn’t see @ryanofsky already opened #34465 just before this, I’ll close this for now since there’s a lot of duplication.
15. stickies-v closed this on Jan 30, 2026

    ---

Contributors
stickies-v DrahtBot

Labels
Validation