bdk icon indicating copy to clipboard operation
bdk copied to clipboard

feat: add optional `tracing` instrumentation

Open LagginTimes opened this issue 5 months ago • 0 comments

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_common with macros log_trace!, log_debug!, log_info!, log_warn!, log_error!, and log_span!
  • Unified feature: log (disabled by default) pulls in tracing = "0.1" for all chain-sync crates
  • Macro-gated logging: swaps out #[cfg(feature = "tracing-logs")] use tracing… and trace!/debug! calls for log_trace!/log_span! invocations with structured fields
  • Zero overhead: with --no-default-features (i.e. no log), all logging macros become no-ops and tracing is 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_common crate with feature-gated logging macros.
  • Introduced workspace-wide log feature in all chain crates to enable tracing‑based instrumentation.

Checklists

All Submissions:

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

LagginTimes avatar Jul 18 '25 18:07 LagginTimes