diff options
Diffstat (limited to 'src/tracing/README.md')
-rw-r--r-- | src/tracing/README.md | 51 |
1 files changed, 51 insertions, 0 deletions
diff --git a/src/tracing/README.md b/src/tracing/README.md new file mode 100644 index 000000000..32ec17f4d --- /dev/null +++ b/src/tracing/README.md @@ -0,0 +1,51 @@ +Installation +============ + +The LTTng libraries that ship with Ubuntu 12.04 have been very buggy, and the +generated header files using `lttng-gen-tp` have needed to be fixed just to +compile in the Ceph tree. The packages available in Ubuntu 14.04 seem to work +alright, and for older versions please install LTTng from the LTTng PPA. + + https://launchpad.net/~lttng/+archive/ppa + +Then install as normal + + apt-get install lttng-tools liblttng-ust-dev + +Add/Update Provider +=================== + +## Create tracepoint definition file + +Add tracepoint definitions for the provider into a `.tp` file. Documentation +on defining a tracepoint can be found in `man lttng-ust`. By convention files +are named according to the logical sub-system they correspond to (e.g. +`mutex.tp`, `pg.tp`). And add a C source file to be compiled into the tracepoint +provider shared object, in which `TRACEPOINT_DEFINE` should be defined. See +[LTTng document](http://lttng.org/docs/#doc-dynamic-linking) for details. +Place the `.tp` and the `.c` files into the `src/tracing` directory +and modify the CMake file `src/tracing/CMakeLists.txt` accordingly. + +Function Instrumentation +======================== +Ceph supports instrumentation using GCC's `-finstrument-functions` flag. +Supported CMake flags are: + +* `-DWITH_OSD_INSTRUMENT_FUNCTIONS=ON`: instrument OSD code + +Note that this instrumentation adds an extra function call on each function entry +and exit of Ceph code. This option is currently only supported with GCC. Using it +with Clang has no effect. + +The only function tracing implementation at the moment is done using LTTng UST. +In order to use it, Ceph needs to be configured with LTTng using `-DWITH_LTTNG=ON`. +[TraceCompass](http://www.tracecompass.org) can be used to generate flame +charts/graphs and other metrics. + +It is also possible to use [libbabeltrace](http://diamon.org/babeltrace/#docs) +to write custom analysis. The entry and exit tracepoints are called +`lttng_ust_cyg_profile:func_enter` and `lttng_ust_cyg_profile:func_exit` +respectively. The payload variable `addr` holds the address of the function +called and the payload variable `call_site` holds the address where it is called. +`nm` can be used to resolve function addresses (`addr` to function name). + |