From mboxrd@z Thu Jan  1 00:00:00 1970
From: pierre-marc.fournier@polymtl.ca (Pierre-Marc Fournier)
Date: Mon, 18 Jan 2010 03:04:42 -0500
Subject: [ltt-dev] Introducing the LTTng Userspace Tracer (UST 0.1)
Message-ID: <4B54161A.3080606@polymtl.ca>

Hi,

This is to introduce UST, the LTTng UserSpace Tracer). UST is a port to
userspace of the LTTng kernel tracer. Its goal is to provide as fast as
possible userspace tracing.

Version 0.1 can be obtained at the following locations.

The repository:
http://git.dorsal.polymtl.ca/?p=ust.git

The tarballs:
http://lttng.org/files/ust/releases/

The documentation, including a quick start guide:
http://lttng.org/files/ust/manual/ust.html

This release is intended as a preview. Development is still in progress
and documentation is not complete. However, most of the tracing
functionality is usable. Feedback is very welcome.

UST uses the same proven buffering algorithms as the kernel tracer.
Instrumentation is done either with markers or tracepoints. A daemon
gathers the trace data and saves it in the same format as the LTTng
kernel tracer. The trace may then be examined with LTTV or the Eclipse
LTTng trace viewer, which is part of the Eclipse linux-tools project.

UST does _not_ require the LTTng kernel tracer to be installed, nor does
it require special kernel support. It is a mere library (libust).

The licence for the tracing library is LGPL v2.1, so it can be linked to
proprietary applications. The tools are GPL v2.

Currently, it has been tested on Linux, but other operating systems
could theoretically be supported without great effort.

The currently supported platforms are x86-32 and x86-64. Supporting
other platforms should not be difficult.

To view traces produced by UST 0.1, LTTV 0.12.20 (commit d081dd5e8ed60)
must be used. This is because UST still uses trace format 2.3. It will
be upgraded to 2.5 in a future release.


Todos and limitations of this release:

- One line of a given source file cannot contain more than one marker
with a given channel and name. (It may however contain several markers
with different channels or names.)

- Buffers are per process. They need to be changed to per-cpu.

- Some changes in the LTTng kernel tracer need to be ported to UST. The
most notable is the change of trace format from 2.3 to 2.5.

- Add support for UST in the LTTng TCF agent, for sending traces via
network.

- There is currently command-line interface support for flight-recorder
mode.

- In early tracing mode, the only channels that can be used reliably are
"metadata" and "ust". The "usttrace" tool always uses early tracing and
is hence subject to this limitation. Traces setup with the "ustctl" tool
("manual mode") are not subject to this limitation and can contain
channels that have any name.

- When loading a library with dlopen(), in order for markers in the
library to generate events in the trace, these markers must be in the
same channel as an event that was in the executable or its dynamically
linked libraries that were loaded at start time. If using early tracing,
only the "ust" channel can be used.

- Tracing across clone() calls without the CLONE_VM flag (that result in
a child that has a distinct address space from its parent) is not yet
supported.

- Currently, only one trace at a time can be recorded on a given process.

--
Pierre-Marc Fournier