Skip to content

tracing: macOS USDT support

This PR adds macOS support for User-Space, Statically Defined Tracing (USDT) as well as dtrace example scripts based on the existing bpftrace scripts for Linux. This is tested on macOS 10.15.

Overview

The current implementation of USDT only supports Linux as the DTRACE_PROBE*(context, event, ...args) macros are not supported on macOS. As initially referenced in https://github.com/bitcoin/bitcoin/pull/22238, the process of using USDT probes on macOS is slightly different and it's described in the BUILDING CODE CONTAINING USDT PROBES section in the dtrace(1) manpage.

This more involved process includes

  1. Creating the providers description file util/probes.d which defines the providers and specifies their probes.
  2. Use util/probes.d to generate the header file util/probes.h with the neccesary tracepoints macros which are of the format CONTEXT_EVENT(...args).
  3. Add the tracepoints macros to util/trace.h.

Notes

Part of the macOS process is to create the providers description in a .d file. Therefore, types not supported by the D language (specifically bool and std::byte) cannot be used as part of the probe's signature. On those occasions, in lack of a better solution, only supported types are used and then a patch is applied at the generated util/probes.h file to replace the temporary D-supported types with those that we actually need.

You can reproduce the initial header file by running dtrace -h -s src/util/probes.d -o src/util/probes.h (compiling with that results to errors because of not matching types) and then apply the probes-fix.diff patch with git apply probes-fix.diff. Edit: util/probes.h is now generated during build time after changes (see https://github.com/bitcoin/bitcoin/pull/25541#discussion_r913646086 and https://github.com/bitcoin/bitcoin/pull/25541#discussion_r915192574) that removed the need for the non supported types.

Having the bitcoind binary compiled with USDT support, you can then use the dtrace example scripts connectblock_benchmark.d, log_p2p_traffic.d, log_utxos.d (root privileges needed) to test the macOS support. Extra documentation for those can be found at contrib/tracing as they are functionally the same as the existing bpftrace scripts.

Adding tracepoints to Bitcoin Core (extra steps after this PR)

After this PR when a new tracepoint is added, we will need to

Merge request reports

Loading