mirrors/bitcoin
1
0
Fork 0
mirror of https://github.com/bitcoin/bitcoin.git synced 2025-02-20 14:05:23 +01:00
Code Issues Projects Releases Wiki Activity
bitcoin/doc
History
merge-script 19f277711e
Merge bitcoin/bitcoin#26593: tracing: Only prepare tracepoint arguments when actually tracing 
0de3e96e33 tracing: use bitcoind pid in bcc tracing examples (0xb10c)
411c6cfc6c tracing: only prepare tracepoint args if attached (0xb10c)
d524c1ec06 tracing: dedup TRACE macros & rename to TRACEPOINT (0xb10c)

Pull request description:

  Currently, if the tracepoints are compiled (e.g. in depends and release builds), we always prepare the tracepoint arguments regardless of the tracepoints being used or not. We made sure that the argument preparation is as cheap as possible, but we can almost completely eliminate any overhead for users not interested in the tracepoints (the vast majority), by gating the tracepoint argument preparation with an `if(something is attached to this tracepoint)`. To achieve this, we use the optional semaphore feature provided by SystemTap.

  The first commit simplifies and deduplicates our tracepoint macros from 13 TRACEx macros to a single TRACEPOINT macro. This makes them easier to use and also avoids more duplicate macro definitions in the second commit.

  The Linux tracing tools I'm aware of (bcc, bpftrace, libbpf, and systemtap) all support the semaphore gating feature. Thus, all existing tracepoints and their argument preparation is gated in the second commit. For details, please refer to the commit messages and the updated documentation in `doc/tracing.md`.

  Also adding unit tests that include all tracepoint macros to make sure there are no compiler problems with them (e.g. some varadiac extension not supported).

  Reviewers might want to check:
  - Do the tracepoints still work for you? Do the examples in `contrib/tracing/` run on your system (as bpftrace frequently breaks on every new version, please test master too if it should't work for you)? Do the CI interface tests still pass?
  - Is the new documentation clear?
  - The `TRACEPOINT_SEMAPHORE(event, context)` macros places global variables in our global namespace. Is this something we strictly want to avoid or maybe move to all `TRACEPOINT_SEMAPHORE`s to a separate .cpp file or even namespace? I like having the `TRACEPOINT_SEMAPHORE()` in same file as the `TRACEPOINT()`, but open for suggestion on alternative approaches.
  - Are newly added tracepoints in the unit tests visible when using `readelf -n build/src/test/test_bitcoin`? You can run the new unit tests with `./build/src/test/test_bitcoin --run_test=util_trace_tests* --log_level=all`.
  <details><summary>Two of the added unit tests demonstrate that we are only processing the tracepoint arguments when attached by having a test-failure condition in the tracepoint argument preparation. The following bpftrace script can be used to demonstrate that the tests do indeed fail when attached to the tracepoints.</summary>

  `fail_tests.bt`:

  ```c
  #!/usr/bin/env bpftrace

  usdt:./build/src/test/test_bitcoin:test:check_if_attached {
    printf("the 'check_if_attached' test should have failed\n");
  }

  usdt:./build/src/test/test_bitcoin:test:expensive_section {
    printf("the 'expensive_section' test should have failed\n");
  }
  ```

  Run the unit tests with `./build/src/test/test_bitcoin` and start `bpftrace fail_tests.bt -p $(pidof test_bitcoin)` in a separate terminal. The unit tests should fail with:

  ```
  Running 594 test cases...
  test/util_trace_tests.cpp(31): error: in "util_trace_tests/test_tracepoint_check_if_attached": check false has failed
  test/util_trace_tests.cpp(51): error: in "util_trace_tests/test_tracepoint_manual_tracepoint_active_check": check false has failed

  *** 2 failures are detected in the test module "Bitcoin Core Test Suite"
  ```

  </details>

  These links might provide more contextual information for reviewers:
  - [How SystemTap Userspace Probes Work by eklitzke](https://eklitzke.org/how-sytemtap-userspace-probes-work) (actually an example on Bitcoin Core; mentions that with semaphores "the overhead for an untraced process is effectively zero.")
  - [libbpf comment on USDT semaphore handling](1596a09b5d/src/usdt.c (L83-L92)) (can recommend the whole comment for background on how the tracepoints and tracing tools work together)
  - https://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation#Semaphore_Handling

ACKs for top commit:
  willcl-ark:
    utACK 0de3e96e33
  laanwj:
    re-ACK 0de3e96e33
  jb55:
    utACK 0de3e96e33
  vasild:
    ACK 0de3e96e33

Tree-SHA512: 0e5e0dc5e0353beaf5c446e4be03d447e64228b1be71ee9972fde1d6fac3fac71a9d73c6ce4fa68975f87db2b2bf6eee2009921a2a145e24d83a475d007a559b
2024-11-11 10:33:28 +00:00
..
design doc: multiprocess documentation improvements 2024-09-23 15:03:04 -05:00
man build: Remove Autotools-based build system 2024-08-30 21:31:39 +01:00
policy docs: remove requirement to signal bip125 2024-10-31 13:19:31 -04:00
release-notes doc: archive release notes for v27.2 2024-11-04 11:19:54 +00:00
assets-attribution.md [doc] Merge doc/assets-attribution.md into contrib/debian/copyright 2015-09-18 18:14:42 +02:00
assumeutxo.md doc: fix assumeutxo design doc link 2024-09-04 22:53:34 +01:00
benchmarking.md doc: replace -? with -h for bench_bitcoin help 2024-10-19 18:44:22 +02:00
bips.md docs: remove requirement to signal bip125 2024-10-31 13:19:31 -04:00
bitcoin-conf.md doc: add testnet4 section header for config file 2024-10-01 15:18:12 +02:00
bitcoin_logo_doxygen.png Lossless image optimization 2013-12-02 10:10:22 +01:00
build-freebsd.md doc: remove mentions of UPnP 2024-10-25 09:27:29 -04:00
build-netbsd.md doc: Update for CMake-based build system 2024-08-16 21:24:08 +01:00
build-openbsd.md doc: remove mentions of UPnP 2024-10-25 09:27:29 -04:00
build-osx.md doc: remove mentions of UPnP 2024-10-25 09:27:29 -04:00
build-unix.md doc: remove mentions of UPnP 2024-10-25 09:27:29 -04:00
build-windows-msvc.md build, msvc: Enable libqrencode vcpkg package 2024-11-05 16:38:56 +00:00
build-windows.md doc: remove dependency install instructions from win docs 2024-10-16 14:47:11 +01:00
cjdns.md doc: update getnodeaddresses for CJDNS, I2P and Tor and rm link 2023-06-01 15:52:51 +02:00
CMakeLists.txt cmake: add USE_SOURCE_PERMISSIONS to all configure_file usage 2024-09-06 10:52:19 +01:00
dependencies.md doc: remove mentions of UPnP 2024-10-25 09:27:29 -04:00
descriptors.md Merge bitcoin/bitcoin#22838: descriptors: Be able to specify change and receiving in a single descriptor string 2024-08-28 15:56:15 +01:00
developer-notes.md doc: Fix word order in developer-notes.md 2024-11-04 20:05:14 -08:00
dnsseed-policy.md Update the developer mailing list address. 2024-04-02 15:38:40 -03:00
Doxyfile.in build: Rename PACKAGE_* variables to CLIENT_* 2024-10-28 12:35:55 +00:00
external-signer.md wallet: compare address returned by displayaddress 2024-04-16 17:47:43 +02:00
files.md Merge bitcoin/bitcoin#29775: Testnet4 including PoW difficulty adjustment fix 2024-08-07 13:05:04 -04:00
fuzzing.md doc: fuzz: remove Honggfuzz NetDriver instructions 2024-10-15 07:46:54 -03:00
guix.md docs: Point to contrib/guix/README.md in doc/guix.md 2021-01-08 11:40:01 -05:00
i2p.md doc: i2p: improve -i2pacceptincoming mention 2024-04-04 18:32:39 -03:00
init.md Merge bitcoin/bitcoin#28167: init: Add option for rpccookie permissions (replace 26088) 2024-06-27 17:35:08 -04:00
JSON-RPC-interface.md minor: remove unnecessary semicolons from RPC content type examples 2024-06-07 10:47:24 -04:00
managing-wallets.md Merge bitcoin/bitcoin#27064: system: use %LOCALAPPDATA% as default datadir on windows 2024-05-23 12:11:55 -04:00
multiprocess.md doc: multiprocess documentation improvements 2024-09-23 15:03:04 -05:00
multisig-tutorial.md doc: Prepend 'build/' to binary paths under 'src/' in docs 2024-08-29 15:23:12 +02:00
offline-signing-tutorial.md doc: Prepend 'build/' to binary paths under 'src/' in docs 2024-08-29 15:23:12 +02:00
p2p-bad-ports.md init, doc: improve -onlynet help and tor/i2p documentation 2022-03-03 16:14:01 +01:00
productivity.md doc: Update for CMake-based build system 2024-08-16 21:24:08 +01:00
psbt.md doc: M-of-N multisig using descriptor wallets and PSBTs, as well as a signing flow 2021-08-16 10:43:07 +05:00
README.md doc: update IBD requirements in doc/README.md 2024-10-02 17:46:11 +02:00
README_doxygen.md doc: Improve doxygen readme navigation section 2019-09-23 19:22:06 -04:00
README_windows.txt doc: Remove version numbers from READMEs 2017-04-05 09:40:48 +02:00
reduce-memory.md doc: Be vague instead of wrong about MALLOC_ARENA_MAX 2023-09-20 17:12:24 +00:00
reduce-traffic.md doc: update/clarify max outbound connection count 2023-12-11 20:05:25 +01:00
release-notes-28358.md validation: drop maximum -dbcache 2024-05-28 08:36:28 +02:00
release-notes-30592.md doc: release note for mempoolrullrbf removal 2024-10-31 13:19:31 -04:00
release-notes-31130.md doc: add release note for #31130 2024-10-25 09:27:30 -04:00
release-notes-31156.md doc: add release note for 31156 2024-10-28 11:38:38 -04:00
release-notes-empty-template.md build: Bump minimum supported macOS to 13.0 2024-10-15 10:18:48 +01:00
release-process.md doc: Use relative hyperlinks in release-process.md 2024-11-03 10:45:31 +00:00
REST-interface.md testnet: Introduce Testnet4 2024-08-06 01:38:10 +02:00
tor.md doc: remove mentions of UPnP 2024-10-25 09:27:29 -04:00
tracing.md tracing: only prepare tracepoint args if attached 2024-10-28 14:27:47 +01:00
translation_process.md doc: Updating docs from autotools to cmake 2024-09-18 11:04:52 -04:00
translation_strings_policy.md doc: Updating docs from autotools to cmake 2024-09-18 11:04:52 -04:00
zmq.md doc: correct the zmq automatic build info 2024-09-25 07:07:04 -04:00

README.md

Bitcoin Core

Setup

Bitcoin Core is the original Bitcoin client and it builds the backbone of the network. It downloads and, by default, stores the entire history of Bitcoin transactions, which requires several hundred gigabytes or more of disk space. Depending on the speed of your computer and network connection, the synchronization process can take anywhere from a few hours to several days or more.

To download Bitcoin Core, visit bitcoincore.org.

Running

The following are some helpful notes on how to run Bitcoin Core on your native platform.

Unix

Unpack the files into a directory and run:

  • bin/bitcoin-qt (GUI) or
  • bin/bitcoind (headless)

Windows

Unpack the files into a directory, and then run bitcoin-qt.exe.

macOS

Drag Bitcoin Core to your applications folder, and then run Bitcoin Core.

Need Help?

Building

The following are developer notes on how to build Bitcoin Core on your native platform. They are not complete guides, but include notes on the necessary libraries, compile flags, etc.

Development

The Bitcoin repo's root README contains relevant information on the development process and automated testing.

Resources

Miscellaneous

License

Distributed under the MIT software license.