bdk
bdk copied to clipboard
feat: add optional `tracing` instrumentation
Resolves #1934.
Description
This PR refactors BDK’s tracing instrumentation by introducing a new internal crate, bdk_common, and replacing the old tracing-logs feature with a workspace-wide log feature:
- New crate:
bdk_commonwith macroslog_trace!,log_debug!,log_info!,log_warn!,log_error!, andlog_span! - Unified feature:
log(disabled by default) pulls intracing = "0.1"for all chain-sync crates - Macro-gated logging: swaps out
#[cfg(feature = "tracing-logs")] use tracing…andtrace!/debug!calls forlog_trace!/log_span!invocations with structured fields - Zero overhead: with
--no-default-features(i.e. nolog), all logging macros become no-ops andtracingis not included
Coverage remains broad—entry points like full_scan, sync, mempool_at, next_block, etc., now use structured field records via the new macros.
Notes to the reviewers
Example code on the tracing_example branch:
https://github.com/LagginTimes/bdk/tree/tracing_example
Sample trace excerpt:
2025-08-06T09:23:18.244470Z TRACE bdk_electrum::full_scan{event="enter_full_scan" stop_gap=5 batch_size=25 fetch_prev=false}: …
2025-08-06T09:23:18.342270Z TRACE bdk_electrum::full_scan{…}: bdk_electrum::bdk_electrum_client: event="script_history_batch" batch_size=25
2025-08-06T09:23:18.505782Z TRACE bdk_electrum::full_scan{…}: bdk_electrum::bdk_electrum_client: event="tx_cache_hit" txid=5d1128104e7fd239b…
2025-08-06T09:23:18.758598Z TRACE bdk_electrum::full_scan{…}: bdk_electrum::bdk_electrum_client: event="anchor_cache_miss" txid=5d1128104e7fd239b… height=255638
2025-08-06T09:23:18.885780Z TRACE bdk_electrum::full_scan{…}: bdk_electrum::bdk_electrum_client: event="anchor_inserted" txid=5d1128104e7fd239b… height=255638 hash=00000006c93e9f…
2025-08-06T09:23:19.012345Z TRACE bdk_electrum::full_scan{…}: electrum_client::raw_client: ==> {"jsonrpc":"2.0","method":"blockchain.transaction.get_merkle",…}
2025-08-06T09:23:19.080123Z TRACE bdk_electrum::full_scan{…}: bdk_electrum::bdk_electrum_client: event="merkle_cache_hit" txid=5d1128104e7fd239b… height=255638
Changelog notice
- Added
bdk_commoncrate with feature-gated logging macros. - Introduced workspace-wide
logfeature in all chain crates to enabletracing‑based instrumentation.
Checklists
All Submissions:
- [x] I followed the contribution guidelines
New Features:
- [ ] I've added tests for the new feature
- [ ] I've added docs for the new feature
Bugfixes:
- [ ] This pull request breaks the existing API
- [ ] I've added tests to reproduce the issue which are now passing
- [x] I'm linking the issue being fixed by this PR