initial code repo

[stor4nfv.git] / src / ceph / src / tracing / README.md

diff --git a/src/ceph/src/tracing/README.md b/src/ceph/src/tracing/README.md
new file mode 100644 (file)
index 0000000..32ec17f
--- /dev/null
+++ b/src/ceph/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).
+