[lttng-modules.git] / README

LTTng 2.0 modules

Mathieu Desnoyers
July 19, 2011

LTTng 2.0 kernel modules build against a vanilla or distribution kernel, without
need for additional patches. Other features:

- Produces CTF (Common Trace Format) natively,
  (http://www.efficios.com/ctf)
- Tracepoints, Function tracer, CPU Performance Monitoring Unit (PMU)
  counters and kprobes 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 will need to have your kernel headers available (or
access to your full kernel source tree), and use:

% make
# make modules_install

If you need to specify the target directory to the kernel you want to build
against, use:

% KERNELDIR=path_to_kernel_dir make
# KERNELDIR=path_to_kernel_dir make modules_install

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 still in active development and not released yet.

So far, it has been tested on vanilla Linux kernels 2.6.38, 2.6.39 and 3.0-rc7
(on x86 at the moment). 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.
Commit	Line	Data
	1	LTTng 2.0 modules
	2
	3	Mathieu Desnoyers
	4	July 19, 2011
	5
	6	LTTng 2.0 kernel modules build against a vanilla or distribution kernel, without
	7	need for additional patches. Other features:
	8
	9	- Produces CTF (Common Trace Format) natively,
	10	(http://www.efficios.com/ctf)
	11	- Tracepoints, Function tracer, CPU Performance Monitoring Unit (PMU)
	12	counters and kprobes support,
	13	- Integrated interface for both kernel and userspace tracing,
	14	- Have the ability to attach "context" information to events in the
	15	trace (e.g. any PMU counter, pid, ppid, tid, comm name, etc).
	16	All the extra information fields to be collected with events are
	17	optional, specified on a per-tracing-session basis (except for
	18	timestamp and event id, which are mandatory).
	19
	20	To build and install, you will need to have your kernel headers available (or
	21	access to your full kernel source tree), and use:
	22
	23	% make
	24	# make modules_install
	25
	26	If you need to specify the target directory to the kernel you want to build
	27	against, use:
	28
	29	% KERNELDIR=path_to_kernel_dir make
	30	# KERNELDIR=path_to_kernel_dir make modules_install
	31
	32	Use lttng-tools to control the tracer. LTTng tools should automatically load
	33	the kernel modules when needed. Use Babeltrace to print traces as a
	34	human-readable text log. These tools are available at the following URL:
	35	http://lttng.org/lttng2.0
	36
	37	Please note that the LTTng-UST 2.0 (user-space tracing counterpart of LTTng 2.0)
	38	is still in active development and not released yet.
	39
	40	So far, it has been tested on vanilla Linux kernels 2.6.38, 2.6.39 and 3.0-rc7
	41	(on x86 at the moment). It should work fine with newer kernels and other
	42	architectures, but expect build issues with kernels older than 2.6.36. The clock
	43	source currently used is the standard gettimeofday (slower, less scalable and
	44	less precise than the LTTng 0.x clocks). Support for LTTng 0.x clocks will be
	45	added back soon into LTTng 2.0. Please note that lttng-modules 2.0 can build on
	46	a Linux kernel patched with the LTTng 0.x patchset, but the lttng-modules 2.0
	47	replace the lttng-modules 0.x, so both tracers cannot be installed at the same
	48	time for a given kernel version.