#35368 tracing: add block header and compact block tracepoints

ReviewabilityReviewsAgreementSize
#35368 w0xlt tracing: add block header and compact block tracepointsNeeds rebase0Strong99 + 270 tests
  • Expose header arrival and compact block reconstruction events to external diagnostic tools
  • Avoid parsing string-based debug logs for continuous production monitoring and peer attribution
  • Ready to review now because the conflict with master is mechanical
  • Strong support for exposing compact block relay data without log parsing (0xB10C)
  • Concept approval without stated reasons (m4ycon)
  • Questioned adding tracepoints ahead of clarifying the IPC tracing approach (stickies-v, maflcko)
  • All questions on tracepoint approach and scope have author or reviewer replies
  • 99 lines added or modified outside tests
  • 270 lines added or modified in tests
  • 6 lines removed in total
  • 6 files, 2 commits
P2P#57 of 71
P3 · new feature
  • P3 because diagnostic observability for compact block relay efficiency is helpful but non-critical
  • Measuring relay performance without log parsing overhead is deferrable tooling instrumentation
  • Ranking pass: Diagnostic tooling, below the behaviour-changing PRs in the band.
Ranking notes
Reviewability: ReadyStalePaused
Agreement: StrongPositivePositive w/ caveatsNeutralMildDisputedBlockedCrickets
Reviews: current code-review ACKs, then (+stale ACKs) and -NACKs; greener = more ACKs.
Size: lines added or modified outside tests, then in tests; greener = smaller.

Goal

Adds two USDT tracepoints to P2P processing: `net:block_header`, which triggers when a new valid header arrives via a `headers` or `cmpctblock` message, and `net:compact_block_reconstructed`, which fires when a compact block is successfully reconstructed before validation. It encapsulates compact block reconstruction statistics into a helper struct on `PartiallyDownloadedBlock` and adds functional BPF test coverage.

Problem: Compact block relay performance and diagnostics rely on string-based debug logs (`BCLog::CMPCTBLOCK`), which are awkward to parse reliably in external tooling, cannot easily be monitored continuously in production without log parsing overhead, and make attributing relay efficiency to specific peers difficult.

Evidence of importance:

  • PR description notes that whether a node reconstructs a block without round trips depends on mempool overlap, extra transaction pool usefulness, and peer behavior, but today 'this information is mostly available only through debug logs, which are string-based, less precise for tooling, and not ideal for continuous measurement.'

Scope: None.

Risk of a mistake: low (p2p, tooling, tests, docs). USDT tracepoints are inactive when unprobed, and the refactor only reads existing counters when assembling reconstruction statistics.

Changed since the previous assessment: Rebased onto recent master without substantive changes to the tracepoint interface or implementation.

Reviewability

Ready · Needs rebase

Conflicts with master; review the logic now, the rebase is mechanical.

Waiting on (from the thread read):

  • reviewer: maflcko to review the author's response regarding IPC tracing in #35142 2026-10-22

Agreement

Strong

substantive support, no open objection (0xB10C)

Thread notes: Updated maflcko's suggestion (c:6211154559) to answered after author replied pointing to their comment in the IPC tracing issue thread.

Objections, suggestions, and questions:

ReviewerTypeHarm, request, or questionStatusMust beAuthor repliedQuote
m4ycon (none)suggestion, interfacepass all missing txids (vtx_missing) through the tracepointanswered · 0xB10C explained that tracepoints do not easily support passing lists or setsansweredby others2026-05-24: 'it makes me think if this isn't an interesting information to pass through tracepoints: all the txids from vtx_missing.'
Status from: 2026-05-25: 0xB10C: 'It's rather impractical to pass lists or sets via tracaepoints, they don't really support it.'
stickies-v (member)suggestion, approachclarify the IPC tracing approach (#35142) before adding more tracepointsanswered · author explained why USDT tracepoints are useful now and that IPC tracing is not a drop-in replacementansweredyes2026-05-26: 'I agree it would make more sense to clarify that first before adding more tracepoints.'
Status from: 2026-05-27: w0xlt: 'I don't think the IPC tracing discussion should block this functionality, assuming there is demand for it.'
maflcko (member)suggestion, usefulnessexplain why this code should be added if it will be removed soon anyway via #35142, and whether there are active users who want itanswered · author replied directing to their comment on issue #35142answeredyes2026-10-16: 'Not sure about adding code that will be removed soon anyway?'
Status from: 2026-10-22: w0xlt: 'Thanks for the feedback. Added my two cents in the thread: https://github.com/bitcoin/bitcoin/issues/35142#issuecomment-6346952054'

Support:

  • 0xB10C (member) (Concept ACK, 2026-05-24) [read]: Generally in favor of having a way of exposing data about this in a non-logging way. Especially since fast compact block relay and reconstructions seem to be somewhat of a share priority by contributors
  • m4ycon (none) (Concept ACK, 2026-05-24): Concept ACK [not substantive]

Participants:

  • 0xB10C (member, support, 4 statements 2026-05-24 to 2026-05-25): Concept ACK on exposing compact block data via tracepoints instead of brittle debug logs
  • m4ycon (none, support, 2 statements 2026-05-24 to 2026-05-24): Concept ACK and suggested including missing txids in the tracepoint
  • stickies-v (member, neutral, 1 statements 2026-05-26 to 2026-05-26): suggested clarifying the IPC tracing approach (#35142) before adding more tracepoints
  • sedited (member, neutral, 2 statements 2026-08-27 to 2026-10-08): asked for a rebase
  • maflcko (member, neutral, 1 statements 2026-10-16 to 2026-10-16): questioned adding code that might soon be removed for IPC tracing and asked if active users want it

Files

272 lines under test/bench/ci.

  • test/functional/interface_usdt_net.py +257/-2
  • src/net_processing.cpp +42/-1
  • doc/tracing.md +30/-0
  • src/blockencodings.cpp +15/-3
  • src/test/blockencodings_tests.cpp +13/-0
  • src/blockencodings.h +12/-0

Card

The short text the ranking pass compares across PRs.

Adds `net:block_header` and `net:compact_block_reconstructed` USDT tracepoints to Bitcoin Core to emit structured compact block reconstruction and header arrival metrics. This solves an observability limitation for telemetry tools and network researchers who currently must scrape text-based debug logs to measure mempool overlap, peer reconstruction success, and extra transaction pool utility. The tracepoints provide low-overhead, disjoint transaction source counts and peer IDs without adding overhead to the hot path when probes are disabled.

Data

dossier JSON · extract JSON · model ledger, generated 2026-10-23T01:16, confidence high, input hash e588a1e7a2228d8f
thread read through 2026-10-22 (14 statements), head ef3121b6e0
labels: Needs rebase

Categories

P2P

P3 · new feature (ranking pass: Diagnostic tooling, below the behaviour-changing PRs in the band.)

Adds USDT observability for block header arrivals and compact block reconstruction to avoid reliance on string-based debug logs. Reviewers noted value in exposing compact block data in a non-logging way for relay performance measurement, but this is non-critical diagnostic instrumentation that is reasonably deferrable.

Membership: Adds tracepoints in src/net_processing.cpp and blockencodings helper structs to observe header and compact block reconstruction events.

Factors: security/stability 0, bug 0, performance 0, user value 1, leverage 1