metadata: fix wait handling

[lttng-ust.git] / README

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

UST web site and manual: http://lttng.org/ust

Updated versions of this package may be found at:

  * Website:  http://lttng.org/ust
  * Releases: http://lttng.org/files/ust/releases
  * GitWeb:   http://git.lttng.org (project: ust)
  * Git:      git://git.lttng.org/ust.git


PREREQUISITES:

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

    -> This release depends on liburcu v0.6

      * 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


INSTALLATION INSTRUCTIONS:

  - Download, compile and install liburcu.
  - In this package's tree, run ./configure.
  - Run make.
  - Run make install.
  - Run ldconfig.
  - See the manual for usage instructions.

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


USAGE:

  - Create an instrumentation header following the tracepoint examples.
    (see tracepoint.h and tests/hello/tp.h).
  - Link application with -lust.
  - (TODO: start tracing with the "lttng" command from lttng-tools)

ENVIRONMENT VARIABLES:

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

  - The environment variable "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".


TRACE VIEWER:

  LTTV is used for viewing UST traces. LTTV may be obtained at
  http://lttng.org in the Downloads section.

  This release has been tested with LTTV 0.12.32.


CONTACT:

  Maintainer: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
  Mailing list: ltt-dev@lists.casi.polymtl.ca


PACKAGE CONTENTS:

  This package contains the following elements.

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

  - ustctl
    A program to control the tracing of userspace applications. It can list
    markers, start the tracing, stop the tracing, enable/disable markers, etc.

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

  - ust-consumerd
    The daemon that collects trace data and writes it to the disk.

  - doc
    The documentation.

  - tests
    Various test programs

  - libustinstr-malloc
    An example library that can be LD_PRELOAD'ed to instrument calls to malloc()
    in any program without need to recompile it.

  - libustfork
    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.

  - libustctl
    A library to control tracing in other processes. Used by ustctl.

  - libustcomm
    A static library shared between libust, ust-consumerd and libustctl, that
    provides functions that allow these components to communicate together.

  - libustconsumer
    A library to create ust consumers by registering callbacks, used by
    ust-consumerd.

  - snprintf
    An asynchronous signal-safe version of snprintf.

  - java
    A simple library that uses JNI to allow tracing in java programs.