folly/tracing/README.md

   1 # folly/tracing: Utility for User-level Statically Defined Tracing
   2 ----------------------------------------------------------
   3
   4 ## StaticTracepoint
   5
   6 The `StaticTracepoint.h` header file defines the Macro
   7 ```
   8 FOLLY_SDT(provider, name, arg1, arg2, ...)
   9 ```
  10 Invoking the Macro will add a Static Tracepoint at the calling location. Using a
  11 tracing toolkit ([BCC](https://github.com/iovisor/bcc) is an excellent example),
  12 a probe can be attached to the Tracepoint, consume the provided arguments and
  13 perform other tracing / profiling works.
  14
  15 The Tracepoint defined using `StaticTracepoint.h` is also compatible with any
  16 toolkit designed for consuming [SystemTap](https://sourceware.org/systemtap/)
  17 Tracepoints.
  18
  19 Internally, the Macro emits a `nop` operation at the calling location, along
  20 with an Assembler Instruction with empty template and empty output Operands,
  21 and the provided arguments and their sizes as input Operands.
  22
  23 The Macro then append to the ELF `.note` section, with information including
  24 the provider and name of the Tracepoint, address of the `nop` operation, and
  25 size and location (register name or memory location) of the provided arguments.
  26 This way, the tracing toolkits would be able to parse the information, attach
  27 the probes to the correct address, and consume arguments.
  28
  29 The default constraint for the arguments in the Assembler Instruction as
  30 operands is `"nor"`. It means the argument could be an immediate integer
  31 operand, a register operand or an offsettable memory operand. This is a good
  32 default since tracing arguments tend to be integral, and the number of arguments
  33 is likely to be less than the number of registers.
  34
  35 Otherwise, you may see compiler report errors like
  36 ```
  37 'asm' requires impossible reload
  38 ```
  39 You may want to simplify the Tracepoint (fewer and simpler arguments) in
  40 such case. You may also choose to override the constraint
  41 ```
  42 #define FOLLY_SDT_ARG_CONSTRAINT "g"
  43 ```
  44 which means the arguments can be any memory or register operands.