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