{
 "number": 35368,
 "repo": "bitcoin/bitcoin",
 "url": "https://github.com/bitcoin/bitcoin/pull/35368",
 "title": "tracing: add block header and compact block tracepoints",
 "author": "w0xlt",
 "author_association": "CONTRIBUTOR",
 "created_at": "2026-05-23T21:04:39Z",
 "updated_at": "2026-08-27T11:20:25Z",
 "age_days": 116,
 "draft": false,
 "labels": [
  "Needs rebase"
 ],
 "milestone": null,
 "base": "master",
 "head_sha": "fbfeb8859cae0d05af71b826d0957395d26bfd20",
 "head_ref": "tracing-compact-block-usdt",
 "head_repo": "w0xlt/bitcoin",
 "head_history": [
  {
   "t": "2026-05-23T21:47:02Z",
   "sha": "c96e7d77b11e4a25ae66ef6c0fe067808f297aae"
  },
  {
   "t": "2026-05-23T21:49:24Z",
   "sha": "fbfeb8859cae0d05af71b826d0957395d26bfd20"
  }
 ],
 "additions": 369,
 "deletions": 6,
 "changed_files": 6,
 "commit_count": 2,
 "size_bucket": "M",
 "mergeable_state": "dirty",
 "bot": {
  "drahtbot": {
   "present": true,
   "reviews": {
    "concept_ack": [
     {
      "login": "0xB10C",
      "url": "https://github.com/bitcoin/bitcoin/pull/35368#issuecomment-4528980947"
     },
     {
      "login": "m4ycon",
      "url": "https://github.com/bitcoin/bitcoin/pull/35368#pullrequestreview-4353399369"
     }
    ]
   },
   "conflicts": [
    {
     "number": 35727,
     "title": "blockencodings: fix extra transaction count",
     "author": "instagibbs"
    },
    {
     "number": 35724,
     "title": "cmpctblock: Improve logging of `cmpctblock` message reconstruction statistics [part of prefill series]",
     "author": "davidgumberg"
    },
    {
     "number": 35558,
     "title": "p2p: Prefill compact blocks",
     "author": "davidgumberg"
    },
    {
     "number": 34565,
     "title": "refactor: extract BlockDownloadManager from PeerManagerImpl",
     "author": "w0xlt"
    }
   ]
  }
 },
 "acks_parsed": {
  "m4ycon": {
   "kind": "concept_ack",
   "hash": null,
   "t": "2026-05-24T21:08:38Z",
   "stale": false
  }
 },
 "acks_tally": {
  "ack": 0,
  "stale_ack": 0,
  "concept_ack": 1,
  "approach_ack": 0,
  "nack": 0,
  "concept_nack": 0,
  "approach_nack": 0
 },
 "reviews": {
  "approved": 0,
  "changes_requested": 0,
  "distinct_reviewers": [
   "0xB10C",
   "m4ycon",
   "sedited",
   "stickies-v"
  ]
 },
 "signals": {
  "needs_rebase": true,
  "ci_failed": false,
  "mergeable_state": "dirty",
  "last_author_activity": "2026-05-27T03:46:45Z",
  "last_reviewer_activity": "2026-08-27T11:20:21Z",
  "last_reviewer": "sedited",
  "author_silent_days": 113,
  "waiting_on_author_days": 21,
  "days_since_update": 21
 },
 "refs": {
  "mentioned": [
   35142
  ],
  "depends_on": [],
  "fixes": [],
  "linked_issues": [],
  "references": [
   {
    "number": 35142,
    "type": "issue",
    "state": "open",
    "merged": false,
    "merged_at": null,
    "title": "RFC: IPC based tracing interface (alternative to eBPF/USDT)"
   }
  ],
  "conflicts": [
   35727,
   35724,
   35558,
   34565
  ]
 },
 "stack": {
  "shares_commits_with": [],
  "based_on": [],
  "base_for": []
 },
 "review_paths": [
  "src/net_processing.cpp"
 ],
 "body": "This PR adds two USDT tracepoints for compact block relay:\n\n- `net:block_header`: fires when a new valid header is received from a peer (via `headers` or `cmpctblock`).\n- `net:compact_block_reconstructed`: fires when a compact block is successfully reconstructed, just before validation.\n\nThe motivation is to expose structured, low-overhead observability for compact block relay behavior.\n\nCompact block relay is performance-sensitive: whether a node reconstructs a block without round trips depends on mempool overlap, extra transaction pool usefulness, and peer behavior.\n\nToday this information is mostly available only through debug logs, which are string-based, less precise for tooling, and not ideal for continuous measurement.\n\nWhat they enable measuring:\n- Which peers announce new headers first, and whether headers arrived via compact block announcements.\n- Per-peer compact block reconstruction success.\n- Where each transaction came from \u2014 prefilled, mempool, extra pool, or a `getblocktxn` round trip.\n- How often compact blocks reconstruct with no round trip, and the bandwidth cost when they don't.\n- Whether high-bandwidth compact block peers actually improve relay, and how mempool divergence affects reconstruction quality.\n\nDesign notes.\n- All data is already available at the reconstruction point; nothing new is computed in the hot path. USDT tracepoints stay inactive unless a tracing tool is attached.\n- Mempool and extra-pool counts are reported as disjoint fields, so consumers can aggregate without double-counting. The reconstruction tracepoint includes the peer ID, making metrics attributable to the peer that supplied the compact block data.",
 "commits": [
  {
   "sha": "c45092fcd6c8173fcf63139c42b9753d1f0e10cf",
   "date": "2026-05-23T21:49:01Z",
   "message": "tracing: add block header tracepoint"
  },
  {
   "sha": "fbfeb8859cae0d05af71b826d0957395d26bfd20",
   "date": "2026-05-23T21:49:01Z",
   "message": "tracing: add compact block reconstruction tracepoint"
  }
 ],
 "timeline": [
  {
   "t": "2026-05-23T21:47:02Z",
   "kind": "force_push",
   "who": "w0xlt",
   "commit": "c96e7d77b11e4a25ae66ef6c0fe067808f297aae"
  },
  {
   "t": "2026-05-23T21:49:24Z",
   "kind": "force_push",
   "who": "w0xlt",
   "commit": "fbfeb8859cae0d05af71b826d0957395d26bfd20"
  },
  {
   "t": "2026-05-23T22:49:15Z",
   "kind": "comment",
   "who": "w0xlt",
   "assoc": "CONTRIBUTOR",
   "text": "CI error unrelated. See https://github.com/bitcoin/bitcoin/issues/34731."
  },
  {
   "t": "2026-05-24T14:14:30Z",
   "kind": "comment",
   "who": "0xB10C",
   "assoc": "CONTRIBUTOR",
   "text": "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. Concept ACK on exposing this data.\n\nIn https://github.com/peer-observer/peer-observer/pull/420, @m4ycon has been working on reading very similar information for the debug log. My understanding is that this works well, but is obviously brittle.\n\nThere's also the question about adding more tracepoints now, or investing time into seeing if #35142 is feasible..."
  },
  {
   "t": "2026-05-24T14:19:19Z",
   "kind": "review_comment",
   "who": "0xB10C",
   "assoc": "CONTRIBUTOR",
   "path": "src/net_processing.cpp",
   "commit": "fbfeb8859cae0d05af71b826d0957395d26bfd20",
   "in_reply_to": null,
   "text": "With tracepoints essentially matching the log statements, I wonder if there's some way of combine the two - but that's obviously out of scope for this PR."
  },
  {
   "t": "2026-05-24T21:05:48Z",
   "kind": "review_comment",
   "who": "m4ycon",
   "assoc": "NONE",
   "path": "src/net_processing.cpp",
   "commit": "fbfeb8859cae0d05af71b826d0957395d26bfd20",
   "in_reply_to": null,
   "text": "While monitoring dashboards from https://github.com/peer-observer/peer-observer/pull/420, my node had a pretty weird period where it was always requesting txs from other nodes (`stats.requested_txn_count > 0`). The image below, this panels measures time taken to reconstruct a block, left panel shows reconstructions that didn't need to request txs, and the right one shows more than zero requested transactions.\n\nOne of the things that people suggested to me, it was that I look at what kind of transactions were being requested, if there was some pattern or things like that. Unfortunately, I didn't have `-debug=net` enabled which probably would have helped me to answer it.\n\nBut with your PR, it makes me think if this isn't an interesting information to pass through tracepoints: all the txids from `vtx_missing`. What do you guys think? Maybe this is too much data to send? As a real sample from my node, the highest \"transactions requested\" was 2041 in the last 30 days."
  },
  {
   "t": "2026-05-24T21:08:38Z",
   "kind": "review",
   "who": "m4ycon",
   "assoc": "NONE",
   "state": "COMMENTED",
   "commit": "fbfeb8859cae0d05af71b826d0957395d26bfd20",
   "text": "Concept ACK\n\nAlso a suggestion on additional info."
  },
  {
   "t": "2026-05-25T09:52:51Z",
   "kind": "review_comment",
   "who": "0xB10C",
   "assoc": "CONTRIBUTOR",
   "path": "src/net_processing.cpp",
   "commit": "fbfeb8859cae0d05af71b826d0957395d26bfd20",
   "in_reply_to": 3294791659,
   "text": "I think a structured logging interface as discussed in https://github.com/bitcoin/bitcoin/issues/35369 would be a good solution avoiding duplication between logging statements and tracepoints. We'd get the same information about compact block reconstructions in a machine-to-machine interface."
  },
  {
   "t": "2026-05-25T10:04:59Z",
   "kind": "review_comment",
   "who": "0xB10C",
   "assoc": "CONTRIBUTOR",
   "path": "src/net_processing.cpp",
   "commit": "fbfeb8859cae0d05af71b826d0957395d26bfd20",
   "in_reply_to": 3295303201,
   "text": "It's rather impractical to pass lists or sets via tracaepoints, they don't really support it. While it might work by concatenating the txids and passing the length and passing the concatenated bytes, I don't think we should do these kind of hacks if we can avoid it.\n\n[quoted text omitted]\nNote that you only need compact block logging enabled. However, we only print the txids if there were less than 5 transactions missing. I've in the past ran a patched bitcoind that removed this limitation and logged all missing txids. To look up why your node didn't know about a certain transaction, you probably want to have `-debug=net` enabled. It might tell you that a transaction was replaced, evicted from orphanage, you never got an inv for it, ...\n\nhttps://github.com/bitcoin/bitcoin/blob/de925455c8025fc1f75d65d981c28b9dfa20e9f7/src/blockencodings.cpp#L222-L232"
  },
  {
   "t": "2026-05-26T11:13:53Z",
   "kind": "comment",
   "who": "stickies-v",
   "assoc": "CONTRIBUTOR",
   "text": "[quoted text omitted]\n\nI agree it would make more sense to clarify that first before adding more tracepoints."
  },
  {
   "t": "2026-05-27T03:46:45Z",
   "kind": "comment",
   "who": "w0xlt",
   "assoc": "CONTRIBUTOR",
   "text": "I don't think the IPC tracing discussion should block this functionality, assuming there is demand for it.\n\nMy understanding is that IPC tracing is a promising direction, but not a drop-in replacement for USDT today.\nWith the current libmultiprocess-generated C++ proxy interfaces, calls are synchronous by default, so a naive tracing implementation where an instrumentation site directly invokes subscriber callbacks would block the Bitcoin Core thread until the subscriber replies.\n\nThat callback model is a poor fit for high-frequency tracing, especially for events like raw P2P messages or per-UTXO cache events, unless it is designed with non-blocking buffering, batching, filtering, and backpressure/drop handling.\n\nSo I see IPC tracing as a longer-term project with its own tradeoffs, while this PR is a small addition to the existing USDT tracing interface."
  },
  {
   "t": "2026-08-27T11:20:21Z",
   "kind": "comment",
   "who": "sedited",
   "assoc": "CONTRIBUTOR",
   "text": "@w0xlt can you rebase this?"
  }
 ],
 "labels_log": [
  {
   "t": "2026-05-23T21:47:28Z",
   "action": "labeled",
   "label": "CI failed",
   "who": "DrahtBot"
  },
  {
   "t": "2026-05-28T08:35:23Z",
   "action": "unlabeled",
   "label": "CI failed",
   "who": "DrahtBot"
  },
  {
   "t": "2026-07-21T21:21:52Z",
   "action": "labeled",
   "label": "Needs rebase",
   "who": "DrahtBot"
  }
 ],
 "state_log": [],
 "text_chars": 5802,
 "text_tokens_estimate": 1450,
 "changed_paths": [
  "doc/tracing.md",
  "src/blockencodings.cpp",
  "src/blockencodings.h",
  "src/net_processing.cpp",
  "src/test/blockencodings_tests.cpp",
  "test/functional/interface_usdt_net.py"
 ],
 "files": [
  {
   "path": "doc/tracing.md",
   "add": 30,
   "del": 0
  },
  {
   "path": "src/blockencodings.cpp",
   "add": 15,
   "del": 3
  },
  {
   "path": "src/blockencodings.h",
   "add": 12,
   "del": 0
  },
  {
   "path": "src/net_processing.cpp",
   "add": 42,
   "del": 1
  },
  {
   "path": "src/test/blockencodings_tests.cpp",
   "add": 13,
   "del": 0
  },
  {
   "path": "test/functional/interface_usdt_net.py",
   "add": 257,
   "del": 2
  }
 ],
 "test_lines": 272,
 "git": {
  "head": "fbfeb8859cae0d05af71b826d0957395d26bfd20",
  "head_matches_backup": true,
  "base": "735b1cf4311de81cc6877a9c2efc082e861ef8d5",
  "commits": [
   {
    "sha": "c45092fcd6",
    "subject": "tracing: add block header tracepoint",
    "files": 3,
    "add": 120,
    "del": 2
   },
   {
    "sha": "fbfeb8859c",
    "subject": "tracing: add compact block reconstruction tracepoint",
    "files": 6,
    "add": 250,
    "del": 5
   }
  ],
  "patch_truncated": false
 },
 "input_hash": "eb998a9019eb7ac2",
 "extracted_at": "2026-09-17T16:15:31+00:00"
}