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. 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.10**, **Autoconf >= 2.50**,
  29     **Autoheader >= 2.50**;
  30     make sure your system-wide `automake` points to a recent version!)
  31   - **[GNU Libtool](https://www.gnu.org/software/libtool/) >= 2.2**
  32
  33
  34 ### Optional dependencies
  35
  36 Optional packages to build LTTng-ust man pages:
  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
  47 Needed for `make check` and tests:
  48
  49   - **[Perl](https://www.perl.org/)**
  50
  51
  52 ### Building steps
  53
  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
 228     in Java programs. (Configure with `--enable-jni-interface`).
 229   - `liblttng-ust-java-agent`: a package that includes a JNI library and a
 230     JAR library to provide an LTTng-UST logging back-end for Java
 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`).
 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.
 238   - `liblttng-ust-python-agent`: a library used by python-lttngust to allow
 239     tracing in Python applications. (Configure with `--enable-python-agent`)
 240   - `libringbuffer`: the ring buffer implementation used within LTTng-UST.
 241   - `python-lttngust`: a package to provide an LTTng-UST logging back-end
 242     for Python applications using the standard logging framework.
 243   - `snprintf`: an asynchronous signal-safe version of `snprintf()`.
 244   - `tests`: various test programs.
 245   - `tools`: home of `lttng-gen-tp`.