lttng: Add documentation and TODO files

LTTng modules licensing

Mathieu Desnoyers

June 2, 2011

* LGPLv2.1/GPLv2 dual-license

The files contained within this package are licensed under

LGPLv2.1/GPLv2 dual-license (see lgpl-2.1.txt and gpl-2.0.txt for

details), except for files identified by the following sections.

* GPLv2 license

These files are licensed exclusively under the GPLv2 license. See

gpl-2.0.txt for details.

lib/ringbuffer/ring_buffer_splice.c

lib/ringbuffer/ring_buffer_mmap.c

instrumentation/events/mainline/*.h

instrumentation/events/lttng-modules/*.h

* MIT-style license

These files are licensed under an MIT-style license:

lib/prio_heap/lttng_prio_heap.h

lib/prio_heap/lttng_prio_heap.c

lib/bitfield.h

LTTng 2.0 modules

Mathieu Desnoyers

November 1st, 2011

LTTng 2.0 kernel modules is currently part of the Linux kernel staging

tree. It features (new features since LTTng 0.x):

- Produces CTF (Common Trace Format) natively,

  (http://www.efficios.com/ctf)

- Tracepoints, Function tracer, CPU Performance Monitoring Unit (PMU)

  counters, kprobes, and kretprobes support,

- Integrated interface for both kernel and userspace tracing,

- Have the ability to attach "context" information to events in the

  trace (e.g. any PMU counter, pid, ppid, tid, comm name, etc).

  All the extra information fields to be collected with events are

  optional, specified on a per-tracing-session basis (except for

  timestamp and event id, which are mandatory).

To build and install, you need to select "Staging" modules, and the

LTTng kernel tracer.

Use lttng-tools to control the tracer. LTTng tools should automatically

load the kernel modules when needed. Use Babeltrace to print traces as a

human-readable text log. These tools are available at the following URL:

http://lttng.org/lttng2.0

Please note that the LTTng-UST 2.0 (user-space tracing counterpart of

LTTng 2.0) is now ready to be used, but still only available from the

git repository.

So far, it has been tested on vanilla Linux kernels 2.6.38, 2.6.39 and

3.0 (on x86 32/64-bit, and powerpc 32-bit at the moment, build tested on

ARM). It should work fine with newer kernels and other architectures,

but expect build issues with kernels older than 2.6.36. The clock source

currently used is the standard gettimeofday (slower, less scalable and

less precise than the LTTng 0.x clocks).  Support for LTTng 0.x clocks

will be added back soon into LTTng 2.0.  Please note that lttng-modules

2.0 can build on a Linux kernel patched with the LTTng 0.x patchset, but

the lttng-modules 2.0 replace the lttng-modules 0.x, so both tracers

cannot be installed at the same time for a given kernel version.

* Note about Perf PMU counters support

Each PMU counter has its zero value set when it is attached to a context with

add-context. Therefore, it is normal that the same counters attached to both the

stream context and event context show different values for a given event; what

matters is that they increment at the same rate.

Please contact Mathieu Desnoyers <mathieu.desnoyers@efficios.com> for

questions about this TODO list. The "Cleanup/Testing" section would be

good to go through before integration into mainline. The "Features"

section is a wish list of features to complete before releasing the

"LTTng 2.0" final version, but are not required to have LTTng working.

These features are mostly performance enhancements and instrumentation

enhancements.

TODO:

A) Cleanup/Testing

	1) Remove debugfs "lttng" file (keep only procfs "lttng" file).

	   The rationale for this is that this file is needed for

	   user-level tracing support (LTTng-UST 2.0) intended to be

	   used on production system, and therefore should be present as

	   part of a "usually mounted" filesystem rather than a debug

	   filesystem.

	2) Cleanup wrappers. The drivers/staging/lttng/wrapper directory

	   contains various wrapper headers that use kallsyms lookups to

	   work around some missing EXPORT_SYMBOL_GPL() in the mainline

	   kernel. Ideally, those few symbols should become exported to

	   modules by the kernel.

	3) Test lib ring buffer snapshot feature.

	   When working on the lttngtop project, Julien Desfossez

	   reported that he needed to push the consumer position

	   forward explicitely with lib_ring_buffer_put_next_subbuf.

	   This means that although the usual case of pairs of

	   lib_ring_buffer_get_next_subbuf/lib_ring_buffer_put_next_subbuf

	   work fine, there is probably a problem that needs to be

	   investigated in

	   lib_ring_buffer_get_subbuf/lib_ring_buffer_put_subbuf, which

	   depend on the producer to push the reader position.

	   Contact: Julien Desfossez <julien.desfossez@polymtl.ca>

	4) Test latest -rt kernel support.

	   There has been report of corrupted traces when tracing a

	   3.0.10-rt27 in the area of access_ok() system call event.

	   Still has to be investigated. Cannot be reproduced with

	   mainline kernel.

	   Contact: Yannick Brosseau <yannick.brosseau@polymtl.ca>

B) Features

	1) Integration of the LTTng 0.x trace clocks into

	   LTTng 2.0.

	     Currently using mainline kernel monotonic clock. NMIs can

	     therefore not be traced, and this causes a significant

	     performance degradation compared to the LTTng 0.x trace

	     clocks. Imply the creation of drivers/staging/lttng/arch to

	     contain the arch-specific clock support files.

	     * Dependency: addition of clock descriptions to CTF.

	   See: http://git.lttng.org/?p=linux-2.6-lttng.git;a=summary

	        for the LTTng 0.x git tree.

	2) Port OMAP3 LTTng trace clocks to x86 to support systems

	   without constant TSC.

	    * Dependency: (B.1)

	   See: http://git.lttng.org/?p=linux-2.6-lttng.git;a=summary

	        for the LTTng 0.x git tree.

	3) Implement mmap operation on an anonymous file created by a

	   LTTNG_KERNEL_CLOCK ioctl to export data to export

	   synchronized kernel and user-level LTTng trace clocks:

	   with:

	      - shared per-cpu data,

	      - read seqlock.

	   The content exported by this shared memory area will be

	   arch-specific.

	   * Dependency: (B.1) && (B.2)

	   See: http://git.lttng.org/?p=linux-2.6-lttng.git;a=summary

	        for the LTTng 0.x git tree, which has vDSO support for

	        LTTng trace clock on the x86 architecture.

	3) Integrate the "statedump" module from LTTng 0.x into LTTng

	   2.0.

	     * Dependency: addition of "dynamic enumerations" type to CTF.

	   See: http://git.lttng.org/?p=lttng-modules.git;a=shortlog;h=refs/heads/v0.19-stable

	        ltt-statedump.c

	4) Generate system call TRACE_EVENT headers for all

	   architectures (currently done: x86 32/64).

	5) Define "unknown" system calls into instrumentation/syscalls

	   override files / or do SYSCALL_DEFINE improvements to

	   mainline kernel to allow automatic generation of these

	   missing system call descriptions.

	6) Create missing tracepoint event headers files into

	   instrumentation/events from headers located in

	   include/trace/events/. Choice: either do as currently done,

	   and copy those headers locally into the lttng driver and

	   perform the modifications locally, or push TRACE_EVENT API

	   modification into mainline headers, which would require

	   collaboration from Ftrace/Perf maintainers.

	7) Poll: implement a poll and/or epoll exclusive wakeup scheme,

	   which contradicts POSIX, but protect multiple consumer

	   threads from thundering herd effect.

	8) Re-integrate sample modules from libringbuffer into

	   lttng driver. Those modules can be used as example of how to

	   use libringbuffer in other contexts than LTTng, and are

	   useful to perform benchmarks of the ringbuffer library.

	   See: http://www.efficios.com/ringbuffer

	9) NOHZ support for lib ring buffer. NOHZ infrastructure in the

	   Linux kernel does not support notifiers chains, which does

	   not let LTTng play nicely with low power consumption setups

	   for flight recorder (overwrite mode) live traces. One way to

	   allow integration between NOHZ and LTTng would be to add

	   support for such notifiers into NOHZ kernel infrastructure.

	10) Turn drivers/staging/lttng/ltt-probes.c probe_list into a

	    hash table. Turns O(n^2) trace systems registration (cost

	    for n systems) into O(n). (O(1) per system)

	11) drivers/staging/lttng/probes/lttng-ftrace.c:

	    LTTng currently uses kretprobes for per-function tracing,

	    not the function tracer. So lttng-ftrace.c should be used

	    for "all" function tracing.

	12) drivers/staging/lttng/probes/lttng-types.c:

	    This is a currently unused placeholder to export entire C

	    type declarations into the trace metadata, e.g. for support

	    of describing the layout of structures/enumeration mapping

	    along with syscall entry events.  The design of this support

	    will likely change though, and become integrated with the

	    TRACE_EVENT support within lttng, by adding new macros, and

	    support for generation of metadata from these macros, to

	    allow description of those compound types/enumerations.

Please send patches

To: Greg Kroah-Hartman <greg@kroah.com>

To: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>