README.md

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