[lttng-ust.git] / README.md

LTTng-UST
=========

The LTTng User Space Tracing (LTTng-UST) library allows any C/C++
application to be instrumented for and traced by
[LTTng](http://lttng.org/). LTTng-UST also includes a logging
back-end for Java applications and various dynamically loadable
user space tracing helpers for any application.


Prerequisites
-------------

LTTng-UST depends on **[liburcu](http://liburcu.org/) >= 0.11** at build and
run times. It also optionally depends on libnuma.


Building
--------

### Prerequisites

This source tree is based on the Autotools suite from GNU to simplify
portability. Here are some things you should have on your system in order to
compile the Git repository tree:

  - [GNU Autotools](http://www.gnu.org/software/autoconf/)
    (**Automake >= 1.10**, **Autoconf >= 2.50**,
    **Autoheader >= 2.50**;
    make sure your system-wide `automake` points to a recent version!)
  - **[GNU Libtool](https://www.gnu.org/software/libtool/) >= 2.2**


### Optional dependencies

Optional packages to build LTTng-ust man pages:

  - **[AsciiDoc](http://www.methods.co.nz/asciidoc/) >= 8.4.5**
    (previous versions may work, but were not tested)
  - **[xmlto](https://fedorahosted.org/xmlto/) >= 0.0.21** (previous
    versions may work, but were not tested)

Note that the man pages are already built in a distribution tarball.
In this case, you only need AsciiDoc and xmlto if you indend to modify
the AsciiDoc man page sources.

Needed for `make check` and tests:

  - **[Perl](https://www.perl.org/)**


### Building steps

If you get the tree from the Git repository, you will need to run

    ./bootstrap

in its root. It calls all the GNU tools needed to prepare the tree
configuration.

To build LTTng-UST, do:

    ./configure
    make
    sudo make install
    sudo ldconfig

**Note:** the `configure` script sets `/usr/local` as the default prefix for
files it installs. However, this path is not part of most distributions'
default library path, which will cause builds depending on `liblttng-ust`
to fail unless `-L/usr/local/lib` is added to `LDFLAGS`. You may provide a
custom prefix to `configure` by using the `--prefix` switch
(e.g., `--prefix=/usr`). LTTng-UST needs to be a shared library, _even if_
the tracepoint probe provider is statically linked into the application.


Using
-----

First of all, create an instrumentation header following the
[tracepoint examples](doc/examples).

There are two ways to compile the tracepoint provider and link it with
your application: statically or dynamically. Please follow carefully one
or the other method.


### Static linking

This method links the tracepoint provider with the application,
either directly or through a static library (`.a`):

  1. Into exactly one unit (C/C++ source file) of your _application_,
     define `TRACEPOINT_DEFINE` and include the tracepoint provider
     header.
  2. Include the tracepoint provider header into all C/C++ files using
     the provider and insert tracepoints using the `tracepoint()` macro.
  3. Use `-I.` when compiling the unit defining `TRACEPOINT_DEFINE`
     (e.g., `tp.c`).
  4. Link the application with `-ldl` on Linux, or with `-lc` on BSD,
     and with `-llttng-ust`.

Example:

    gcc -c -I. tp.c
    gcc -c some-source.c
    gcc -c other-source.c
    gcc -o my-app tp.o some-source.o other-source.o -ldl -llttng-ust

Run the application directly:

    ./my-app

Other relevant examples:

  - [`doc/examples/easy-ust`](doc/examples/easy-ust)
  - [`doc/examples/hello-static-lib`](doc/examples/hello-static-lib)


### Dynamic loading

This method decouples the tracepoint provider from the application,
making it dynamically loadable.

  1. Into exactly one unit of your _application_, define
     `TRACEPOINT_DEFINE` _and_ `TRACEPOINT_PROBE_DYNAMIC_LINKAGE`,
     then include the tracepoint provider header.
  2. Include the tracepoint provider header into all C/C++ files using
     the provider and insert tracepoints using the `tracepoint()` macro.
  3. Use `-I.` and `-fpic` when compiling the tracepoint provider
     (e.g., `tp.c`).
  4. Link the tracepoint provider with `-llttng-ust` and make it a
     shared object with `-shared`.
  5. Link the application with `-ldl` on Linux, or with `-lc` on BSD.

Example:

    gcc -c -I. -fpic tp.c
    gcc -o tp.so -shared tp.o -llttng-ust
    gcc -o my-app some-source.c other-source.c -ldl

To run _without_ LTTng-UST support:

    ./my-app

To run with LTTng-UST support (register your tracepoint provider,
`tp.so`):

    LD_PRELOAD=./tp.so ./my-app

You could also use `libdl` directly in your application and `dlopen()`
your tracepoint provider shared object (`tp.so`) to make LTTng-UST
tracing possible.

Other relevant examples:

  - [`doc/examples/demo`](doc/examples/demo)


### Controlling tracing and viewing traces

Use [LTTng-tools](https://lttng.org/download) to control the tracer.
Use [Babeltrace](https://lttng.org/babeltrace) to print traces as a
human-readable text log.


### Environment variables and compile flags

  - `liblttng-ust` debug can be activated by setting the environment
    variable `LTTNG_UST_DEBUG` when launching the user application. It
    can also be enabled at build time by compiling LTTng-UST with
    `-DLTTNG_UST_DEBUG`.
  - The environment variable `LTTNG_UST_REGISTER_TIMEOUT` can be used to
    specify how long the applications should wait for the session
    daemon  _registration done_ command before proceeding to execute the
    main program. The default is 3000 ms (3 seconds). The timeout value
    is specified in milliseconds. The value 0 means _don't wait_. The
    value -1 means _wait forever_. Setting this environment variable to 0
    is recommended for applications with time constraints on the process
    startup time.
  - The compilation flag `-DLTTNG_UST_DEBUG_VALGRIND` should be enabled
    at build time to allow `liblttng-ust` to be used with Valgrind
    (side-effect: disables per-CPU buffering).


### Notes

#### C++ support

Since LTTng-UST 2.3, both tracepoints and tracepoint providers can be
compiled in C++. To compile tracepoint probes in C++, you need
G++ >= 4.7 or Clang.


Contact
-------

Maintainer: [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com)

Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)


Package contents
----------------

This package contains the following elements:

  - `doc`: LTTng-UST documentation and examples.
  - `include`: the public header files that will be installed on the
    system.
  - `liblttng-ust`: the actual userspace tracing library that must be
    linked to the instrumented programs.
  - `liblttng-ust-comm`: a static library shared between `liblttng-ust`
    and LTTng-tools, that provides functions that allow these components
    to communicate together.
  - `liblttng-ust-ctl`: a library to control tracing in other processes;
     used by LTTng-tools.
  - `liblttng-ust-cyg-profile`: a library that can be preloaded (using
    `LD_PRELOAD`) to instrument function entries and exits when the target
    application is built with the GCC flag `-finstrument-functions`.
  - `liblttng-ust-dl`: a library that can be preloaded to instrument
    calls to `dlopen()` and `dlclose()`.
  - `liblttng-ust-fork`: a library that is preloaded and that hijacks
    calls to several system calls in order to trace across these calls.
    It _has_ to be preloaded in order to hijack calls. In contrast,
    `liblttng-ust` may be linked at build time.
  - `liblttng-ust-java`: a simple library that uses JNI to allow tracing
    in Java programs. (Configure with `--enable-jni-interface`).
  - `liblttng-ust-java-agent`: a package that includes a JNI library and a
    JAR library to provide an LTTng-UST logging back-end for Java
    applications using Java Util Logging or Log4j. (Configure with
    `--enable-java-agent-jul` or `--enable-java-agent-log4j` or
    `--enable-java-agent-all`).
  - `liblttng-ust-libc-wrapper`: an example library that can be
    preloaded to instrument some calls to libc (currently `malloc()` and
    `free()`) and to POSIX threads (mutexes currently instrumented) in
    any program without need to recompile it.
  - `liblttng-ust-python-agent`: a library used by python-lttngust to allow
    tracing in Python applications. (Configure with `--enable-python-agent`)
  - `libringbuffer`: the ring buffer implementation used within LTTng-UST.
  - `python-lttngust`: a package to provide an LTTng-UST logging back-end
    for Python applications using the standard logging framework.
  - `snprintf`: an asynchronous signal-safe version of `snprintf()`.
  - `tests`: various test programs.
  - `tools`: home of `lttng-gen-tp`.
Commit	Line	Data
28ed9628 PP	1	LTTng-UST
	2	=========
	3
	4	The LTTng User Space Tracing (LTTng-UST) library allows any C/C++
	5	application to be instrumented for and traced by
	6	[LTTng](http://lttng.org/). LTTng-UST also includes a logging
	7	back-end for Java applications and various dynamically loadable
	8	user space tracing helpers for any application.
	9
	10
	11	Prerequisites
	12	-------------
	13
e3097de3	14	LTTng-UST depends on [liburcu](http://liburcu.org/) >= 0.11 at build and
915faa3d	15	run times. It also optionally depends on libnuma.
28ed9628 PP	16
	17
	18	Building
	19	--------
	20
	21	### Prerequisites
	22
	23	This source tree is based on the Autotools suite from GNU to simplify
	24	portability. Here are some things you should have on your system in order to
	25	compile the Git repository tree:
	26
6f9466c5 PP	27	- [GNU Autotools](http://www.gnu.org/software/autoconf/)
	28	(Automake >= 1.10, Autoconf >= 2.50,
	29	Autoheader >= 2.50;
28ed9628	30	make sure your system-wide `automake` points to a recent version!)
6f9466c5	31	- [GNU Libtool](https://www.gnu.org/software/libtool/) >= 2.2
c5123a13 PP	32
	33
	34	### Optional dependencies
28ed9628	35
b49b04f4	36	Optional packages to build LTTng-ust man pages:
4ddbd0b7 PP	37
	38	- [AsciiDoc](http://www.methods.co.nz/asciidoc/) >= 8.4.5
	39	(previous versions may work, but were not tested)
	40	- [xmlto](https://fedorahosted.org/xmlto/) >= 0.0.21 (previous
	41	versions may work, but were not tested)
	42
	43	Note that the man pages are already built in a distribution tarball.
	44	In this case, you only need AsciiDoc and xmlto if you indend to modify
	45	the AsciiDoc man page sources.
	46
c5123a13 PP	47	Needed for `make check` and tests:
	48
	49	- [Perl](https://www.perl.org/)
	50
	51
	52	### Building steps
	53
28ed9628 PP	54	If you get the tree from the Git repository, you will need to run
	55
	56	./bootstrap
	57
	58	in its root. It calls all the GNU tools needed to prepare the tree
	59	configuration.
	60
	61	To build LTTng-UST, do:
	62
	63	./configure
	64	make
	65	sudo make install
	66	sudo ldconfig
	67
	68	Note: the `configure` script sets `/usr/local` as the default prefix for
	69	files it installs. However, this path is not part of most distributions'
	70	default library path, which will cause builds depending on `liblttng-ust`
	71	to fail unless `-L/usr/local/lib` is added to `LDFLAGS`. You may provide a
	72	custom prefix to `configure` by using the `--prefix` switch
	73	(e.g., `--prefix=/usr`). LTTng-UST needs to be a shared library, _even if_
	74	the tracepoint probe provider is statically linked into the application.
	75
	76
	77	Using
	78	-----
	79
	80	First of all, create an instrumentation header following the
	81	[tracepoint examples](doc/examples).
	82
	83	There are two ways to compile the tracepoint provider and link it with
	84	your application: statically or dynamically. Please follow carefully one
	85	or the other method.
	86
	87
	88	### Static linking
	89
	90	This method links the tracepoint provider with the application,
	91	either directly or through a static library (`.a`):
	92
	93	1. Into exactly one unit (C/C++ source file) of your _application_,
	94	define `TRACEPOINT_DEFINE` and include the tracepoint provider
	95	header.
	96	2. Include the tracepoint provider header into all C/C++ files using
	97	the provider and insert tracepoints using the `tracepoint()` macro.
	98	3. Use `-I.` when compiling the unit defining `TRACEPOINT_DEFINE`
	99	(e.g., `tp.c`).
	100	4. Link the application with `-ldl` on Linux, or with `-lc` on BSD,
	101	and with `-llttng-ust`.
	102
	103	Example:
	104
	105	gcc -c -I. tp.c
	106	gcc -c some-source.c
	107	gcc -c other-source.c
	108	gcc -o my-app tp.o some-source.o other-source.o -ldl -llttng-ust
	109
	110	Run the application directly:
	111
	112	./my-app
	113
	114	Other relevant examples:
	115
	116	- [`doc/examples/easy-ust`](doc/examples/easy-ust)
	117	- [`doc/examples/hello-static-lib`](doc/examples/hello-static-lib)
118
119
120	### Dynamic loading
121
122	This method decouples the tracepoint provider from the application,
123	making it dynamically loadable.
124
125	1. Into exactly one unit of your _application_, define
126	`TRACEPOINT_DEFINE` _and_ `TRACEPOINT_PROBE_DYNAMIC_LINKAGE`,
127	then include the tracepoint provider header.
128	2. Include the tracepoint provider header into all C/C++ files using
129	the provider and insert tracepoints using the `tracepoint()` macro.
130	3. Use `-I.` and `-fpic` when compiling the tracepoint provider
131	(e.g., `tp.c`).
132	4. Link the tracepoint provider with `-llttng-ust` and make it a
133	shared object with `-shared`.
134	5. Link the application with `-ldl` on Linux, or with `-lc` on BSD.
135
136	Example:
137
138	gcc -c -I. -fpic tp.c
139	gcc -o tp.so -shared tp.o -llttng-ust
140	gcc -o my-app some-source.c other-source.c -ldl
141
142	To run _without_ LTTng-UST support:
143
144	./my-app
145
146	To run with LTTng-UST support (register your tracepoint provider,
147	`tp.so`):
148
149	LD_PRELOAD=./tp.so ./my-app
150
151	You could also use `libdl` directly in your application and `dlopen()`
152	your tracepoint provider shared object (`tp.so`) to make LTTng-UST
153	tracing possible.
154
155	Other relevant examples:
156
157	- [`doc/examples/demo`](doc/examples/demo)
158
159
160	### Controlling tracing and viewing traces
161
162	Use [LTTng-tools](https://lttng.org/download) to control the tracer.
163	Use [Babeltrace](https://lttng.org/babeltrace) to print traces as a
164	human-readable text log.
165
166
167	### Environment variables and compile flags
168
169	- `liblttng-ust` debug can be activated by setting the environment
170	variable `LTTNG_UST_DEBUG` when launching the user application. It
171	can also be enabled at build time by compiling LTTng-UST with
172	`-DLTTNG_UST_DEBUG`.
173	- The environment variable `LTTNG_UST_REGISTER_TIMEOUT` can be used to
174	specify how long the applications should wait for the session
175	daemon _registration done_ command before proceeding to execute the
176	main program. The default is 3000 ms (3 seconds). The timeout value
177	is specified in milliseconds. The value 0 means _don't wait_. The
178	value -1 means _wait forever_. Setting this environment variable to 0
179	is recommended for applications with time constraints on the process
180	startup time.
181	- The compilation flag `-DLTTNG_UST_DEBUG_VALGRIND` should be enabled
182	at build time to allow `liblttng-ust` to be used with Valgrind
183	(side-effect: disables per-CPU buffering).
184
185
186	### Notes
187
188	#### C++ support
189
190	Since LTTng-UST 2.3, both tracepoints and tracepoint providers can be
191	compiled in C++. To compile tracepoint probes in C++, you need
192	G++ >= 4.7 or Clang.
193
194
195	Contact
196	-------
197
198	Maintainer: [Mathieu Desnoyers](mailto:mathieu.desnoyers@efficios.com)
199
200	Mailing list: [`lttng-dev@lists.lttng.org`](https://lttng.org/cgi-bin/mailman/listinfo/lttng-dev)
201
202
203	Package contents
204	----------------
205
206	This package contains the following elements:
207
208	- `doc`: LTTng-UST documentation and examples.
209	- `include`: the public header files that will be installed on the
210	system.
211	- `liblttng-ust`: the actual userspace tracing library that must be
212	linked to the instrumented programs.
213	- `liblttng-ust-comm`: a static library shared between `liblttng-ust`
214	and LTTng-tools, that provides functions that allow these components
215	to communicate together.
216	- `liblttng-ust-ctl`: a library to control tracing in other processes;
217	used by LTTng-tools.
218	- `liblttng-ust-cyg-profile`: a library that can be preloaded (using
219	`LD_PRELOAD`) to instrument function entries and exits when the target
220	application is built with the GCC flag `-finstrument-functions`.
221	- `liblttng-ust-dl`: a library that can be preloaded to instrument
222	calls to `dlopen()` and `dlclose()`.
223	- `liblttng-ust-fork`: a library that is preloaded and that hijacks
224	calls to several system calls in order to trace across these calls.
225	It _has_ to be preloaded in order to hijack calls. In contrast,
226	`liblttng-ust` may be linked at build time.
227	- `liblttng-ust-java`: a simple library that uses JNI to allow tracing
380a81f4	228	in Java programs. (Configure with `--enable-jni-interface`).
b49b04f4 MJ	229	- `liblttng-ust-java-agent`: a package that includes a JNI library and a
b49b04f4 MJ	230	JAR library to provide an LTTng-UST logging back-end for Java
380a81f4 GB	231	applications using Java Util Logging or Log4j. (Configure with
	232	`--enable-java-agent-jul` or `--enable-java-agent-log4j` or
	233	`--enable-java-agent-all`).
28ed9628 PP	234	- `liblttng-ust-libc-wrapper`: an example library that can be
	235	preloaded to instrument some calls to libc (currently `malloc()` and
	236	`free()`) and to POSIX threads (mutexes currently instrumented) in
	237	any program without need to recompile it.
b49b04f4	238	- `liblttng-ust-python-agent`: a library used by python-lttngust to allow
380a81f4	239	tracing in Python applications. (Configure with `--enable-python-agent`)
28ed9628	240	- `libringbuffer`: the ring buffer implementation used within LTTng-UST.
b49b04f4 MJ	241	- `python-lttngust`: a package to provide an LTTng-UST logging back-end
b49b04f4 MJ	242	for Python applications using the standard logging framework.
28ed9628 PP	243	- `snprintf`: an asynchronous signal-safe version of `snprintf()`.
	244	- `tests`: various test programs.
	245	- `tools`: home of `lttng-gen-tp`.