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