Version 2.2.3

[lttng-ust.git] / README

LTTNG USERSPACE TRACER (LTTng-UST)
----------------------------

UST web site: http://lttng.org

Updated versions of this package may be found at:

  * Releases: http://lttng.org/download
  * GitWeb:   http://git.lttng.org (project: lttng-ust)
  * Git:      git://git.lttng.org/lttng-ust.git


PREREQUISITES:

  - liburcu
    Userspace RCU library, by Mathieu Desnoyers and Paul E. McKenney

    -> This release depends on liburcu v0.7.2

      * Debian/Ubuntu package: liburcu-dev
      * Website:  http://lttng.org/urcu
      * Releases: http://lttng.org/files/urcu
      * GitWeb:   http://lttng.org/cgi-bin/gitweb.cgi?p=userspace-rcu.git;a=summary
      * Git:      git://lttng.org/userspace-rcu.git

For developers using the git tree:

This source tree is based on the autotools suite from GNU to simplify
portability. Here are some things you should have on your system in order to
compile the git repository tree :

- GNU autotools (automake >=1.10, autoconf >=2.50, autoheader >=2.50)
  (make sure your system wide "automake" points to a recent version!)
- GNU Libtool >=2.2
  (for more information, go to http://www.gnu.org/software/autoconf/)
- Perl (optional)
  Needed for make check and tests.

If you get the tree from the repository, you will need to use the "bootstrap"
script in the root of the tree. It calls all the GNU tools needed to prepare the
tree configuration.


INSTALLATION INSTRUCTIONS:

  - Download, compile and install liburcu.
  - In this package's tree, run ./configure.
  - Run make.
  - Run make install.
  - Run ldconfig.

  If compiling from the git repository, run ./bootstrap before running
  the configure script, to generate it.

  Note that configure sets '/usr/local' as the default prefix for files it
  installs. However, this path is not part of most distributions' default
  library path which will cause builds depending on liblttng-ust to fail unless
  '-L/usr/local/lib' is added to LDFLAGS. You may provide a custom prefix to
  configure by using the --prefix switch.

USAGE:

  - Create an instrumentation header following the tracepoint examples.
    See lttng/tracepoint.h, and examples.

  There are 2 ways to compile the Tracepoint Provider with the
  application: either statically or dynamically. Please follow
  carefully:

  1.1) Compile the Tracepoint provider with the application, either
       directly or through a static library (.a):
    - Into exactly one object of your application: define
      "TRACEPOINT_DEFINE" and include the tracepoint provider.
    - Use "-I." for the compilation unit containing the tracepoint
      provider include (e.g. tp.c).
    - Link application with "-ldl" on Linux, with "-lc" on BSD.
    - If building the provider directly into the application,
      link the application with "-llttng-ust".
    - If building a static library for the provider, link the static
      library with "-llttng-ust".
    - Include the tracepoint provider header into all C files using
      the provider.
    - Examples:
      - doc/examples/easy-ust/   sample.c sample_component_provider.h
        tp.c Makefile
      - doc/examples/hello-static-lib/   hello.c tp.c ust_test_hello.h
        Makefile

  2) Compile the Tracepoint Provider separately from the application,
     using dynamic linking:
    - Into exactly one object of your application: define
      "TRACEPOINT_DEFINE" _and_ also define
      "TRACEPOINT_PROBE_DYNAMIC_LINKAGE", then include the tracepoint
      provider header.
    - Include the tracepoint provider header into all instrumented C
      files that use the provider.
    - Compile the tracepoint provider with "-I.".
    - Link the tracepoint provider with "-llttng-ust".
    - Link application with "-ldl" on Linux, "-lc" on BSD.
    - Set a LD_PRELOAD environment to preload the tracepoint provider
      shared object before starting the application when tracing is
      needed. Another way is to dlopen the tracepoint probe when needed
      by the application.
    - Example:
      - doc/examples/demo   demo.c  tp*.c ust_tests_demo*.h demo-trace Makefile

  - Note about dlclose() usage: it is not safe to use dlclose on a
    provider shared object that is being actively used for tracing due
    to a lack of reference counting from lttng-ust to the used shared
    object.
  - Enable instrumentation and control tracing with the "lttng" command
    from lttng-tools. See lttng-tools doc/quickstart.txt.
  - Note for C++ support: although an application instrumented with
    tracepoints can be compiled with g++, tracepoint probes should be
    compiled with gcc (only tested with gcc so far).


ENVIRONMENT VARIABLES:

  - liblttng-ust debug can be activated by setting the environment variable
    "LTTNG_UST_DEBUG" when launching the application. It can also be enabled
    at compile-time by compiling libust with -DLTTNG_UST_DEBUG.

  - The environment variable "LTTNG_UST_REGISTER_TIMEOUT" can be used to
    specify how long the applications should wait for sessiond
    "registration done" command before proceeding to execute the main
    program. The default is 3000ms (3 seconds). The timeout value is
    specified in milliseconds. The value 0 means "don't wait". The value
    -1 means "wait forever". Setting this environment variable to 0 is
    recommended for applications with time constraints on the process
    startup time.

  - The compilation flag "-DLTTNG_UST_DEBUG_VALGRIND" should be enabled
    at build time to allow liblttng-ust to be used with valgrind
    (side-effect: disables per-cpu buffering).


TRACE VIEWER:

  Use babeltrace for viewing traces generated by LTTng UST 2.x.
  See http://lttng.org for download.


CONTACT:

  Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
  Mailing list: lttng-dev@lists.lttng.org


PACKAGE CONTENTS:

  This package contains the following elements.

  - liblttng-ust
    The actual userspace tracing library that must be linked to the
    instrumented programs.

  - include
    The public header files that will be installed on the system.

  - tests
    Various test programs

  - liblttng-ust-libc-wrapper
    An example library that can be LD_PRELOAD'ed to instrument some
    calls to libc (currently malloc() and free()) in any program without
    need to recompile it.

  - liblttng-ust-fork
    A library that is LD_PRELOAD'ed, and that hijacks calls to several system
    calls in order to trace across these calls. It _has_ to be LD_PRELOAD'ed
    in order to hijack calls. In contrast, libust may be linked at build time.

  - liblttng-ust-ctl
    A library to control tracing in other processes. Used by lttng-tools.

  - liblttng-ust-comm
    A static library shared between libust and lttng-tools, that
    provides functions that allow these components to communicate together.

  - libringbuffer
    The ring buffer implementation used within LTTng-UST.

  - snprintf
    An asynchronous signal-safe version of snprintf.

  - liblttng-ust-java
    A simple library that uses JNI to allow tracing in java programs.
    See liblttng-ust-java/README for build instructions.