src/ceph/src/tracing/README.md

   1 Installation
   2 ============
   3
   4 The LTTng libraries that ship with Ubuntu 12.04 have been very buggy, and the
   5 generated header files using `lttng-gen-tp` have needed to be fixed just to
   6 compile in the Ceph tree. The packages available in Ubuntu 14.04 seem to work
   7 alright, and for older versions please install LTTng from the LTTng PPA.
   8
   9     https://launchpad.net/~lttng/+archive/ppa
  10
  11 Then install as normal
  12
  13     apt-get install lttng-tools liblttng-ust-dev
  14
  15 Add/Update Provider
  16 ===================
  17
  18 ## Create tracepoint definition file
  19
  20 Add tracepoint definitions for the provider into a `.tp` file. Documentation
  21 on defining a tracepoint can be found in `man lttng-ust`. By convention files
  22 are named according to the logical sub-system they correspond to (e.g.
  23 `mutex.tp`, `pg.tp`). And add a C source file to be compiled into the tracepoint
  24 provider shared object, in which `TRACEPOINT_DEFINE` should be defined. See
  25 [LTTng document](http://lttng.org/docs/#doc-dynamic-linking) for details.
  26 Place the `.tp` and the `.c` files into the `src/tracing` directory
  27 and modify the CMake file `src/tracing/CMakeLists.txt` accordingly.
  28
  29 Function Instrumentation
  30 ========================
  31 Ceph supports instrumentation using GCC's `-finstrument-functions` flag.
  32 Supported CMake flags are:
  33
  34 *   `-DWITH_OSD_INSTRUMENT_FUNCTIONS=ON`: instrument OSD code
  35
  36 Note that this instrumentation adds an extra function call on each function entry
  37 and exit of Ceph code. This option is currently only supported with GCC. Using it
  38 with Clang has no effect.
  39
  40 The only function tracing implementation at the moment is done using LTTng UST.
  41 In order to use it, Ceph needs to be configured with LTTng using `-DWITH_LTTNG=ON`.
  42 [TraceCompass](http://www.tracecompass.org) can be used to generate flame
  43 charts/graphs and other metrics.
  44
  45 It is also possible to use [libbabeltrace](http://diamon.org/babeltrace/#docs)
  46 to write custom analysis. The entry and exit tracepoints are called
  47 `lttng_ust_cyg_profile:func_enter` and `lttng_ust_cyg_profile:func_exit`
  48 respectively. The payload variable `addr` holds the address of the function
  49 called and the payload variable `call_site` holds the address where it is called.
  50 `nm` can be used to resolve function addresses (`addr` to function name).
  51