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

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).
Commit	Line	Data
7c673cae FG	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
31f18b77 FG	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).
7c673cae	51