README.md

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