[lttng-modules.git] / README

LTTng 2.0 modules

Mathieu Desnoyers
February 8, 2012

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, 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 will need to have your kernel headers available (or
access to your full kernel source tree), and use:

% make
# make modules_install
# depmod -a

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
# depmod -a kernel_version

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

So far, it has been tested on vanilla Linux kernels 2.6.38, 2.6.39, 3.0,
3.1, 3.2, 3.3 (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.

LTTng-modules depends on having kallsyms enabled in the kernel it is
built against. Ideally, if you want to have system call tracing, the
"Trace Syscalls" feature should be enabled too. 

* 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.
Commit	Line	Data
98541fcf MD	1	LTTng 2.0 modules
	2
	3	Mathieu Desnoyers
936e4abc	4	February 8, 2012
98541fcf MD	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)
fe178379	11	- Tracepoints, Function tracer, CPU Performance Monitoring Unit (PMU)
e5fb2910	12	counters, kprobes, and kretprobes support,
98541fcf MD	13	- Integrated interface for both kernel and userspace tracing,
98541fcf MD	14	- Have the ability to attach "context" information to events in the
fe178379 MD	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).
98541fcf MD	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
6b408629 MD	23	% make
6b408629 MD	24	# make modules_install
65a8ae6b	25	# depmod -a
98541fcf MD	26
	27	If you need to specify the target directory to the kernel you want to build
	28	against, use:
	29
6b408629 MD	30	% KERNELDIR=path_to_kernel_dir make
6b408629 MD	31	# KERNELDIR=path_to_kernel_dir make modules_install
65a8ae6b	32	# depmod -a kernel_version
98541fcf	33
6b408629 MD	34	Use lttng-tools to control the tracer. LTTng tools should automatically load
	35	the kernel modules when needed. Use Babeltrace to print traces as a
	36	human-readable text log. These tools are available at the following URL:
	37	http://lttng.org/lttng2.0
bd2fc8af	38
d117fe45 MD	39	So far, it has been tested on vanilla Linux kernels 2.6.38, 2.6.39, 3.0,
	40	3.1, 3.2, 3.3 (on x86 32/64-bit, and powerpc 32-bit at the moment, build
	41	tested on ARM). It should work fine with newer kernels and other
	42	architectures, but expect build issues with kernels older than 2.6.36.
	43	The clock source currently used is the standard gettimeofday (slower,
	44	less scalable and less precise than the LTTng 0.x clocks). Support for
	45	LTTng 0.x clocks will be added back soon into LTTng 2.0. Please note
	46	that lttng-modules 2.0 can build on a Linux kernel patched with the
	47	LTTng 0.x patchset, but the lttng-modules 2.0 replace the lttng-modules
	48	0.x, so both tracers cannot be installed at the same time for a given
	49	kernel version.
a3a8ea22	50
936e4abc MD	51	LTTng-modules depends on having kallsyms enabled in the kernel it is
	52	built against. Ideally, if you want to have system call tracing, the
	53	"Trace Syscalls" feature should be enabled too.
	54
a3a8ea22 MD	55	* Note about Perf PMU counters support
	56
	57	Each PMU counter has its zero value set when it is attached to a context with
	58	add-context. Therefore, it is normal that the same counters attached to both the
	59	stream context and event context show different values for a given event; what
	60	matters is that they increment at the same rate.