README.md

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