Commit message · merge-scriptMerge bitcoin/bitcoin#34374: kernel: use struct-based logging and simplify logging interface
eb086540b680cfed42ab7f9498c1ade459828808 kernel: make logging struct-based and simplify configuration (stickies-v)
0c327a34748a3d882d88fe0034187ddee0c7d59a kernel: add KernelLogger (stickies-v)
3d976f464d5a5dbb0b867783c472b31ba871900a kernel: remove API to format and disable logging (stickies-v)
4ec80a5d4fa3ff567356d946d45699a3c407c77f kernel: add log level and category name helpers to wrapper (stickies-v)
2ce6cd3d906da00c2b12c00a9437ed68dc5c4f14 kernel: expose btck_LogEntry (stickies-v)
694eaad2eb287ca8c862d766cde22cb39667fed8 kernel: add missing log levels and categories (stickies-v)
Pull request description:
tl;dr: kernel logging is cumbersome. This PR delivers log entries as a struct instead of a formatted string, and simplifies the kernel logging interface. Closes #34062.
## Motivation
The `bitcoinkernel` library (#27587) [exposes](https://github.com/bitcoin/bitcoin/blob/b26762bdcb941096ccc6f53c3fb5a7786ad735e7/src/kernel/bitcoinkernel.h#L698-L778) functionality to interface with the kernel logging. This includes registering callbacks for log statements, level/category filtering, string formatting options, and more.
Kernel logging has a few problems:
- [callbacks](https://github.com/bitcoin/bitcoin/blob/b26762bdcb941096ccc6f53c3fb5a7786ad735e7/src/kernel/bitcoinkernel.h#L304) operate on formatted strings, so users need to parse the string to get the timestamp, category, level, ... based on which options are set. This is cumbersome, brittle, and inefficient.
- the [filtering interface](https://github.com/bitcoin/bitcoin/blob/b26762bdcb941096ccc6f53c3fb5a7786ad735e7/src/kernel/bitcoinkernel.h#L737) is not really intuitive, requiring users to call combinations of `btck_logging_set_level_category` and `btck_logging_enable_category` when they want to produce `debug` or `trace` logs. The level/category system makes sense for node, because it directly controls what gets written to disk and stdout, and there are quite a lot more categories producing logs. Kernel doesn't really need this - users control what happens to the logs, and can do any filtering/manipulation in the callback they provide.
- the node logging infrastructure has quite a bit more functionality than is necessary for a library, including ratelimiting, log formatting, outputting, buffering, ... This introduces unnecessary code and interface complexity.
## Approach
Log generation (`util/log.h`: macros, `util::log::Entry`, and the `ShouldDebugLog`/`ShouldTraceLog`/`Log` hooks an application must provide) was already separated from log handling (`logging.h`) in #34465 and subsequent PRs. This PR gives `bitcoinkernel` its own implementation of those hooks, so it no longer depends on `logging.cpp`, and upgrades the C API to deliver struct-based entries. Node logging is not changed.
1. **Preparatory work**: expose the missing levels and categories (`WARNING`, `ERROR`, `TXPACKAGES`, `LOCK`) and the `btck_LogEntry` struct, add `Name()` helpers to the C++ wrapper, and remove `btck_logging_set_options` and `btck_logging_disable` (with struct-based entries there is no kernel-side format to configure, and without buffering there is nothing to disable).
2. **Add `KernelLogger`**: a kernel-owned backend that holds the registered callbacks and the minimum level, and converts each `util::log::Entry` into a `btck_LogEntry`. Introduced in a separate commit to keep the scope of the behaviour-changing commit smaller.
3. **Update the bitcoinkernel C API**: `btck_LogCallback` receives a `btck_LogEntry` instead of a string, the `util::log` hooks are implemented on `KernelLogger`, `logging.cpp` is dropped from the kernel build, and the logging configuration interface is reduced to `btck_logging_set_min_level()`.
Behaviour changes for consumers (also described in each commit message):
- Logging callbacks deliver structs instead of formatted strings, and the entire logging interface is simplified.
- Filtering is levels-based only and can also filter `Info` and above. `Debug`/`Trace` apply to all categories, consumers can filter on `btck_LogEntry::category` (but string formatting is done for the entire level, instead of per enabled category).
- Entries logged before the first connection are dropped instead of buffered.
- Messages are delivered unescaped and without a trailing newline.
## Appendix
### `bitcoinkernel` C logging interface
```c
typedef struct {
const char* message; //! Log message text.
size_t message_len;
const char* thread_name; //! Name of the thread that produced the log message.
size_t thread_name_len;
int64_t timestamp_ns; //! Wall-clock time when the entry was logged, in nanoseconds since the Unix epoch.
int64_t mocktime_s; //! Mock time in effect when the entry was logged, in seconds since the Unix epoch, or 0 if no mock time is set (see btck_set_mock_time).
const char* file_name; //! Name of the source file that produced the log statement.
size_t file_name_len;
const char* function_name; //! Name of the function that produced the log message.
size_t function_name_len;
uint32_t line; //! Line number of the source code that produced the log statement.
btck_LogLevel level; //! Log severity level.
btck_LogCategory category; //! Log category.
} btck_LogEntry;
typedef void (*btck_LogCallback)(void* user_data, const btck_LogEntry* entry);
BITCOINKERNEL_API void btck_logging_set_min_level(btck_LogLevel level);
BITCOINKERNEL_API btck_LoggingConnection* BITCOINKERNEL_WARN_UNUSED_RESULT btck_logging_connection_create(
btck_LogCallback log_callback,
void* user_data,
btck_DestroyCallback user_data_destroy_callback) BITCOINKERNEL_ARG_NONNULL(1);
BITCOINKERNEL_API void btck_logging_connection_destroy(btck_LoggingConnection* logging_connection);
```
ACKs for top commit:
w0xlt:
ACK eb086540b680cfed42ab7f9498c1ade459828808
musaHaruna:
Code Review ACK [eb08654](https://github.com/bitcoin/bitcoin/commit/eb086540b680cfed42ab7f9498c1ade459828808)
sedited:
Nice, ACK eb086540b680cfed42ab7f9498c1ade459828808
Tree-SHA512: 301a388253ead2176d75cb69935839a103bc125cac064eba787a643449047bd1f2d32d9dd11828f4ab59ce66976827ab61490b0533705a80b5c86316a1cfadae
93/100 · StrongMessage clarity
✓ Specific, descriptive subject✓ Names a concrete action or component✓ Provides detailed explanatory context✓ Explains rationale or failure mode✓ Links an issue, advisory, or supporting reference
Why it was queuedmerge-commit duplicate discount