From: Mohamad Gebai <mgebai@suse.com>
Date: Thu, 11 May 2017 13:33:40 +0000 (-0400)
Subject: tracing: add documentation for function instrumentation
X-Git-Tag: v12.1.0~57^2~15^2~1
X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=021dcf7bfb31c8f3297a569c50e8e1cd195821bc;p=ceph.git

tracing: add documentation for function instrumentation

Signed-off-by: Mohamad Gebai <mgebai@suse.com>
---

diff --git a/src/tracing/README.md b/src/tracing/README.md
index dea1d20a2c5f..32ec17f4d9ff 100644
--- a/src/tracing/README.md
+++ b/src/tracing/README.md
@@ -26,4 +26,26 @@ provider shared object, in which `TRACEPOINT_DEFINE` should be defined. See
 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).