Skip to content

feat: add optional tracing instrumentation #1995

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

LagginTimes
Copy link
Contributor

@LagginTimes LagginTimes commented Jul 18, 2025

Resolves #1934.

Description

This PR introduces structured tracing instrumentation to BDK’s chain‑sync crates (bdk_electrum, bdk_esplora, bdk_bitcoind_rpc, etc.) in a fully opt‑in, zero‑overhead manner.

  • New feature: tracing-logs (disabled by default) that pulls in tracing = "0.1".
  • Feature‑gated logging: all use tracing::{…} imports and trace!/debug! calls are wrapped in #[cfg(feature = "tracing-logs")].
  • Broad coverage: logs on major operations (full_scan, sync, mempool, next_block) and key internals (batch sizes, cache hits/misses, gap‑limit stops, anchor processing).

With tracing-logs disabled, there should be no runtime impact.

Changelog notice

  • Optional tracing-logs feature in bdk_electrum, bdk_esplora, bdk_bitcoind_rpc, etc., 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
  • I'm linking the issue being fixed by this PR

@LagginTimes LagginTimes self-assigned this Jul 18, 2025
@LagginTimes LagginTimes marked this pull request as draft July 18, 2025 18:41
@@ -115,6 +118,13 @@ where
pub fn mempool(&mut self) -> Result<MempoolEvent, bitcoincore_rpc::Error> {
let client = &*self.client;

#[cfg(feature = "tracing-logs")]
trace!(
"mempool(): entering, start_height={}, last_mempool_tip={:?}",
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would avoid rust string interpolation in favor of field records. A short not interpolated message can hint you directly to the action performed, and the variables in context will give you all the remaining information.
I think this improves the discoverability of issues, and for large enterprise setups, provides a better format for log consumers to digest it (easier to produce json output)

trace!("mempool(): entering", start_height = self.start_height, last_mempool_tip = self.last_mempool_tip);

Also, these fields may be also included for the logging span of the function:

trace_span!(start_height = self.start_height, last_mempool_tip = self.last_mempool_tip)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
Status: No status
Development

Successfully merging this pull request may close these issues.

Consider adding support for tracing
2 participants